Introdução Rápida ​

Experimentar a Vue Online ​

• Para termos rapidamente um gosto da Vue, podemos experimentá-la diretamente na nossa Zona de Testes (ou Zona de Experimentos).

• Se preferirmos uma configuração de HTML simples sem quaisquer etapas de construção podemos usar esta JSFiddle como nosso ponto de partida.

• Se já estivermos familiarizados com a Node.js e com o conceito de ferramentas de construção, também podemos experimentar uma configuração de construção completa diretamente dentro do nosso navegador na StackBlitz.

Criando uma Aplicação de Vue ​

Nesta seção introduziremos como estruturar uma Aplicação de Página Única de Vue na nossa máquina local. O projeto criado usará uma configuração de construção baseada na Vite, e nos permitirá usar os Componentes de Ficheiro Único da Vue.

Temos que certificar-nos de que temos uma versão atualizada da Node.js instalada e o nosso diretório de trabalho atual é aquele onde tencionamos criar um projeto. Executamos o seguinte comando na nossa linha de comando (sem o sinal $):

$ npm create vue@latest

$ pnpm create vue@latest

$ yarn create vue@latest

$ bun create vue@latest

Este comando instalará e executará a create-vue, a ferramenta de estruturação de projeto de Vue oficial. Nós seremos presenteados com prontos para várias funcionalidades opcionais tais como o suporte da TypeScript e testes:

✔ Project name: … <your-project-name>
✔ Add TypeScript? … No / Yes
✔ Add JSX Support? … No / Yes
✔ Add Vue Router for Single Page Application development? … No / Yes
✔ Add Pinia for state management? … No / Yes
✔ Add Vitest for Unit testing? … No / Yes
✔ Add an End-to-End Testing Solution? … No / Cypress / Playwright
✔ Add ESLint for code quality? … No / Yes
✔ Add Prettier for code formatting? … No / Yes

Scaffolding project in ./<your-project-name>...
Done.

Se estivermos inseguros sobre uma opção, por agora podemos simplesmente escolher No pressionando Enter. Logo que o projeto for criado, seguimos as instruções para instalarmos as dependências e iniciar o servidor de desenvolvimento:

$ cd <your-project-name>
$ npm install
$ npm run dev

$ cd <your-project-name>
$ pnpm install
$ pnpm run dev

$ cd <your-project-name>
$ yarn
$ yarn dev

$ cd <your-project-name>
$ bun install
$ bun run dev

Nós devemos ter agora o nosso primeiro projeto de Vue em execução! Nota que os componentes de exemplo no projeto gerado estão escritos usando a API de Composição e o <script setup>, ao invés da API de Opções. Eis algumas dicas adicionais:

• A configuração de ambiente de desenvolvimento integrado recomendada é o editor de texto Visual Studio Code mais a extensão Volar. Se usarmos outros editores, temos que consultar a seção do suporte de ambiente de desenvolvimento integrado.
• Mais detalhes sobre o ferramental, incluindo a integração com abstrações de backend, são discutidos no Guia de Ferramental.
• Para sabermos mais sobre a ferramenta de construção subjacente Vite, temos que consultar a documentação da Vite.
• Se escolhermos usar a TypeScript, temos que consultar o Guia de Uso de TypeScript.

Quando estivermos prontos para disponibilizar a nossa aplicação em produção, executaremos o seguinte:

$ npm run build

$ pnpm run build

$ yarn build

$ bun run build

Isto criará uma construção preparada para produção da nossa aplicação dentro do diretório ./dist do projeto. Consulte o Guia de Implementação de Produção por mais informação sobre a disponibilização da nossa aplicação em produção.

Próximos Passos >

Usando a Vue da Rede de Entrega de Conteúdo ​

Nós podemos usar a Vue diretamente a partir duma rede de entrega de conteúdo através dum marcador script:

<script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>

Eis que usamos a unpkg, mas também podemos usar qualquer rede de entrega de conteúdo que serve pacotes de npm, por exemplo a jsdelivr ou a cdnjs. E claro, também podemos descarregar este ficheiro e o servir por conta própria.

Quando usamos a Vue a partir duma rede de entrega de conteúdo, não existe nenhuma "etapa de construção" envolvida. Isto torna a configuração muito mais simples, e é adequando para otimizar a HTML estática ou integrar com uma abstração de backend. No entanto, não serás capaz de usar a sintaxe do Componente de Ficheiro Único (ou, SFC).

Usando a Construção Global ​

A ligação acima carrega a construção global da Vue, onde todas as APIs de alto nível são expostas como propriedades sobre o objeto Vue global. Eis um exemplo completo usando a construção global:

<script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>

<div id="app">{{ message }}</div>

<script>
  const { createApp } = Vue

  createApp({
    data() {
      return {
        message: 'Hello Vue!'
      }
    }
  }).mount('#app')
</script>

<script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>

<div id="app">{{ message }}</div>

<script>
  const { createApp, ref } = Vue

  createApp({
    setup() {
      const message = ref('Hello Vue!')
      return {
        message
      }
    }
  }).mount('#app')
</script>

Usando a Construção de Módulo de ECMAScript ​

Por toda a documentação, usaremos essencialmente a sintaxe de módulos de ECMAScript. A maioria dos navegadores agora suportam os módulos de ECMAScript de maneira nativa, então podemos usar a Vue a partir duma rede de entrega de conteúdo através dos módulos de ECMScript desta maneira:

<div id="app">{{ message }}</div>

<script type="module">
  import { createApp } from 'https://unpkg.com/vue@3/dist/vue.esm-browser.js'

  createApp({
    data() {
      return {
        message: 'Hello Vue!'
      }
    }
  }).mount('#app')
</script>

<div id="app">{{ message }}</div>

<script type="module">
  import { createApp, ref } from 'https://unpkg.com/vue@3/dist/vue.esm-browser.js'

  createApp({
    setup() {
      const message = ref('Hello Vue!')
      return {
        message
      }
    }
  }).mount('#app')
</script>

Repara que usamos o <script type="module">, e que a URL da rede de entrega de conteúdo importada aponta para uma construção de módulos de ECMAScript da Vue.

Ativando os Mapas de Importação ​

No exemplo acima, importamos a partir da URL completa da rede de entrega de conteúdo, mas no resto da documentação veremos o código desta maneira:

import { createApp } from 'vue'

Nós podemos ensinar o navegador onde localizar a importação da vue usando os Mapas de Importação:

<script type="importmap">
  {
    "imports": {
      "vue": "https://unpkg.com/vue@3/dist/vue.esm-browser.js"
    }
  }
</script>

<div id="app">{{ message }}</div>

<script type="module">
  import { createApp } from 'vue'

  createApp({
    data() {
      return {
        message: 'Hello Vue!'
      }
    }
  }).mount('#app')
</script>

<script type="importmap">
  {
    "imports": {
      "vue": "https://unpkg.com/vue@3/dist/vue.esm-browser.js"
    }
  }
</script>

<div id="app">{{ message }}</div>

<script type="module">
  import { createApp, ref } from 'vue'

  createApp({
    setup() {
      const message = ref('Hello Vue!')
      return {
        message
      }
    }
  }).mount('#app')
</script>

Nós também podemos adicionar entradas para outras dependências ao mapa de importação - porém temos que certificar-nos de que apontam às versões de módulos de ECMAScript da biblioteca que tencionamos usar.

Separando os Módulos ​

Conforme mergulharmos mais fundo no guia, podemos precisar dividir o código em ficheiros de JavaScript separados para serem mais fáceis de gerir. Por exemplo:

<!-- index.html -->
<script type="module">
  import { createApp } from 'vue'
  import MyComponent from './my-component.js'

  createApp(MyComponent).mount('#app')
</script>

// my-component.js
export default {
  data() {
    return { count: 0 }
  },
  template: `<div>count is {{ count }}</div>`
}

// my-component.js
import { ref } from 'vue'
export default {
  setup() {
    const count = ref(0)
    return { count }
  },
  template: `<div>count is {{ count }}</div>`
}

Se abrirmos o index.html acima diretamente no nosso navegador, descobriremos que lança um erro porque os módulos de ECMAScript não podem funcionar sobre o protocolo file://, que é o protocolo que o navegador usa quando abrimos um ficheiro local.

Por razões de segurança, os módulos de ECMAScript apenas podem funcionar sobre o protocolo http://, que é o que os navegadores usam quando abrimos as páginas na Web. Para os módulos de ECMAScript funcionarem na nossa máquina local, precisamos servir o index.html sobre o protocolo http://, com um servidor de HTTP local.

Para iniciar um servidor de HTTP local, temos de certificar-nos que temos a Node.js instalada, depois executamos npx serve a partir da linha de comando no mesmo diretório onde o nosso ficheiro de HTML está. Nós também podemos usar qualquer outro servidor de HTTP que pode servidor ficheiros estáticos com os tipos de tipo de ficheiro corretos.

Nós podemos ter reparado que o modelo de marcação do componente importado está em linha como uma sequência de caracteres de JavaScript. Se usamos o VSCode, podemos instalar a extensão es6-string-html e prefixar as sequências de caracteres com um comentário /*html*/ para obtermos destacamento da sua sintaxe.

Próximos Passos ​

Se saltaste a Introdução, recomendamos fortemente a leitura da mesma antes de avançarmos para o resto da documentação.