@govbr-ds-testing/webcomponents-vue

v1.23.5

Published

10 days ago

Biblioteca de integração dos Web Components GovBR-DS com o Vue

Downloads

585

0High
0Medium
0Low

marcosalves3

rafael.serpro

govbrds

design system govbr-ds web components vue

Webcomponents Vue

Bibiloteca de componentes vue que encapsulam os Web Components GovBR-DS.

Instalação

Instale os pacotes abaixo:

npm install --save-dev @govbr-ds/core @govbr-ds-testing/webcomponents @govbr-ds-testing/webcomponents-vue

Uso

Inclua no main.ts (ou arquivo equivalente) da sua aplicação:

import { ComponentLibrary } from '@govbr-ds-testing/webcomponents-vue'

import '@govbr-ds/core/dist/core.min.css'

O core.min.css é quem define os valores dos tokens de CSS usados.

Estrutura de pastas e arquivos

- vue
  - lib
    - stencil-generated
    - index.ts
    - plugin.ts

Ao gerar um build da biblioteca te Web Components os arquivos da pasta lib/stencil-generated são deletados e recriados. Todas as alterações nesses arquivos vão ser perdidas ao gerar um novo build dos Web Components.

O Arquivo plugin.ts registra os componentes como custom elements.

O Arquivo index.ts é o entry point da biblioteca e exporta os componentes.

Build

Rode o comando npm run build.

Configuração do Projeto Vue

Para utilizar a biblioteca em Stencil criada para o GovBR-DS, é necessário que se tenha um novo projeto Vue previamente configurado. Se ainda não o tiver instalado, siga estes passos para criar um projeto Vue e configurá-lo para utilizar os componentes:

Criar um Projeto Vue: Primeiramente, crie um novo projeto Vue utilizando o Vue CLI ou outro método de sua preferência. Por exemplo:

vue create meu-projeto

Baixar Pacotes Necessários: Após criar o projeto, instale os pacotes necessários, incluindo os componentes do Padrão Digital de Governo.

npm install @govbr-ds-testing/webcomponents-vue @govbr-ds/core

Configurar o Arquivo main.js: No arquivo main.js do seu projeto Vue, configure o uso dos componentes e do roteador, se necessário. Exemplo de arquivo main.js:

import { ComponentLibrary } from '@govbr-ds-testing/webcomponents-vue';
import '@govbr-ds/core/dist/core.min.css';
import { createApp } from 'vue';
import App from './App.vue';
import router from './router';

const app = createApp(App);
app.use(router); // Se estiver utilizando roteador
app.use(ComponentLibrary);
app.mount('#app');

Com esses passos, seu projeto Vue estará configurado para utilizar os componentes do Padrão Digital de Governo.

É importante notar que as dependências estão sendo gerenciadas através do sistema de módulos do JavaScript. Se ainda estiver com dificuldade para aplicar os estilos, incluía no arquivo index.html algumas referências a bibliotecas externas e estilos adicionais, que incluem o GovBR-DS, o Google Fonts e o Font Awesome, verificando sempre se ocorre redundâncias e conflitos entre as importações no arquivo main.js e os scripts e folhas de estilo incluídos no index.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <!-- Inclusão de estilos adicionais e bibliotecas externas -->
    <link rel="stylesheet" href="https://cdngovbr-ds.estaleiro.serpro.gov.br/design-system/fonts/rawline/css/rawline.css" />
    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Raleway:300,400,500,600,700,800,900&amp;display=swap" />
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/all.min.css" />
  </head>
  <body>
    <div id="app"></div>
    <!-- Importação do arquivo main.js -->
    <script type="module" src="/src/main.js"></script>
  </body>
</html>

Geração de componente

Para gerar um componente no seu projeto Vue, vamos utilizar como exemplo o componente Input do GovBR-DS, seguindo o mesmo entendimento nos demais componentes.

Passo 1: Tags do componente

Você pode usar as tags do componente diretamente no template. Por exemplo:

<template>
  <div>
    <br-input></br-input>
  </div>
</template>

Passo 2: Propriedades do componente

Cada componente possui várias propriedades que podem ser utilizadas para personalizar sua aparência e comportamento. A documentação de cada componente deve ser consultada para obtenção de maiores informações. É importante destacar que as propriedades padrão do HTML podem ser utilizadas da mesma forma que em um input HTML comum. Por exemplo, as propriedades id, name, value, disabled, required, entre outras, podem ser aplicadas diretamente à tag do componente br-input. Veja um exemplo:

<template>
  <div>
    <br-input id="nome" name="nome" disabled required density="large" label="Nome"></br-input>
  </div>
</template>

Neste exemplo, além das propriedades HTML comum, foi definido as propriedades density (densidade do input, podendo ser "small" ou "large") e label(geração automática do label para o input).

Passo 3: Bind de Dados

Utilizando : (sintaxe de bind), você pode passar dinamicamente o valor de uma variável para a propriedade do componente e uma variável no seu componente Vue. Por exemplo:

<br-input name="name" :label="textLabel" placeholder="Digite algo"></br-input>

No componente Vue:

data() {
  return {
    textLabel: "Texto do label"
  };
}

Passo 4: Utilizar Eventos Customizados

Você pode ouvir eventos customizados emitidos pelo componente br-input usando a diretiva @, seguida pelo nome do evento. Por exemplo, você está ouvindo o evento input no exemplo fornecido:

<br-input @input="handleInputChange" label="Label" placeholder="Digite algo"></br-input>

No componente Vue:

methods: {
  handleInputChange(newValue) {
    this.inputValue = newValue.target.value;
  },
}

Passo 5: Personalizar Estilos

É importante observar que os componentes utilizam Shadow DOM para encapsular seu estilo e comportamento. Isso significa que os estilos não podem ser facilmente modificados diretamente a partir do componente pai.

No entanto, você ainda pode personalizar alguns aspectos do estilo utilizando CSS personalizado dentro do escopo do componente pai. Isso pode ser feito definindo classes personalizadas ou utilizando estilos embutidos diretamente no componente pai.

Reportar bugs/necessidades

Você pode usar as issues para nos informar os problemas que tem enfrentado ao usar nossa biblioteca ou mesmo o que gostaria que fizesse parte do projeto. Por favor use o modelo que mais se encaixa na sua necessidade e preencha com o máximo de detalhes possível.

Nos comprometemos a responder a todas as issues.

Commits

Nesse projeto usamos um padrão para branches e commits. Por favor observe a documentação na nossa wiki para aprender sobre os nossos padrões.

Precisa de ajuda?

Por favor não crie issues para fazer perguntas.

Use nossos canais abaixo para obter tirar suas dúvidas:

Site do GovBR-DS http://gov.br/ds
Web Components https://gov.br/ds/webcomponents
Usando nosso canal no discord https://discord.gg/U5GwPfqhUP

Créditos

Os Web Components do GovBR-DS são criados pelo SERPRO juntamente com a comunidade.

Licença

Nesse projeto usamos a licença MIT.