Início rápido

Os componentes do mdui são componentes Web Components padrão. Você pode usar os componentes do mdui como uma tag <div>. A documentação de cada componente descreve detalhadamente sua API completa, incluindo atributos, métodos, eventos, slots, CSS Part, propriedades CSS personalizadas, etc.

Este capítulo da documentação apresentará como usar os Web Components.

Atributo

Os atributos são divididos em atributos HTML e propriedades JavaScript. Eles geralmente são mapeados um a um e permanecem sincronizados. Ou seja, quando você atualiza o valor de um atributo HTML, o valor da propriedade JavaScript também é atualizado; e vice-versa.

Os atributos HTML podem ser definidos diretamente na string HTML do componente e lidos/modificados pelos métodos getAttribute e setAttribute:

<mdui-button variant="text">Clique em mim</mdui-button>

<script>
  const button = document.querySelector('mdui-button');

  // Modificar atributo HTML
  button.setAttribute('variant', 'outlined');

  // Ler atributo HTML
  console.log(button.getAttribute('variant')); // outlined
</script>

As propriedades JavaScript podem ser lidas ou definidas diretamente no valor da propriedade da instância do componente:

<mdui-button variant="text">Clique em mim</mdui-button>

<script>
  const button = document.querySelector('mdui-button');

  // Definir propriedade JavaScript
  button.variant = 'outlined';

  // Ler propriedade JavaScript
  console.log(button.variant); // outlined
</script>

Algumas propriedades têm valor booleano. Quando o atributo HTML correspondente existe, a propriedade JavaScript é true; caso contrário, é false. No entanto, para compatibilidade com certos frameworks, o mdui também trata o valor string 'false' como o valor booleano false.

<!-- Este componente tem o atributo disabled, ou seja, o valor padrão disabled é true -->
<mdui-button disabled></mdui-button>

<script>
  const button = document.querySelector('mdui-button');

  button.removeAttribute('disabled'); // Equivalente a button.disabled = false;
  button.setAttribute('disabled', ''); // Equivalente a button.disabled = true;

  // Exceção: definir o valor string 'false' equivale a definir o valor booleano false
  button.setAttribute('disabled', 'false'); // Equivalente a button.disabled = false;
</script>

Às vezes, o valor da propriedade é um array, objeto ou função. Nesses casos, existe apenas a propriedade JavaScript, sem o atributo HTML correspondente. Por exemplo, a propriedade labelFormatter do componente <mdui-slider> é uma função. Você só pode definir essa propriedade via JavaScript:

<mdui-slider></mdui-slider>

<script>
  const slider = document.querySelector('mdui-slider');
  slider.labelFormatter = (value) => `${value}%`;
</script>

Abaixo, usando parte da documentação de propriedades do componente <mdui-slider> como exemplo:

Este componente tem atributo HTML e propriedade JavaScript para name, e a coluna reflect indica que atualizar a propriedade JavaScript também atualiza o atributo HTML. Para value, atualizar a propriedade JavaScript não atualiza o atributo HTML. A propriedade labelFormatter existe apenas como propriedade JavaScript.

Método

Alguns componentes fornecem métodos públicos que você pode chamar para diferentes funcionalidades. Por exemplo, o método focus() do componente <mdui-text-field> faz o campo de texto ganhar foco.

<mdui-text-field></mdui-text-field>

<script>
  const textField = document.querySelector('mdui-text-field');
  textField.focus();
</script>

Consulte a página de documentação de cada componente para ver todos os métodos disponíveis e seus parâmetros.

Evento

Alguns componentes acionam eventos ao executar ações específicas. Por exemplo, o componente <mdui-dialog> aciona o evento open ao abrir. Você pode monitorar este evento para executar ações personalizadas.

<mdui-dialog>Diálogo</mdui-dialog>

<script>
  const dialog = document.querySelector('mdui-dialog');

  dialog.addEventListener('open', () => {
    console.log('Este evento é acionado quando o diálogo começa a abrir');
  });
</script>

Consulte a página de documentação de cada componente para ver todos os eventos disponíveis e seus parâmetros.

Se você estiver usando o mdui em outros frameworks (como Vue, React, Angular, etc.), pode usar a sintaxe fornecida pelo framework para vincular eventos. No entanto, alguns frameworks (como React) só permitem vincular eventos padrão (como o evento click) com sua sintaxe de vinculação de eventos, não eventos personalizados (como o evento open). Portanto, ao vincular eventos personalizados no React, você precisa primeiro obter uma referência ao elemento e usar o método addEventListener para vincular o evento.

Para mais informações sobre como usar o mdui no React, consulte Integração com frameworks - React.

Slot

Muitos componentes fornecem slots para inserir conteúdo HTML personalizado dentro do componente.

O mais comum é o slot padrão, que é um fragmento HTML ou texto simples dentro do componente. Por exemplo, o slot padrão do componente <mdui-button> define o texto do botão. No exemplo, "Clique em mim" é o conteúdo do slot padrão:

<mdui-button>Clique em mim</mdui-button>

Alguns componentes também fornecem slots nomeados. Para slots nomeados, você precisa especificar o nome do slot no atributo HTML slot. No exemplo a seguir, o componente <mdui-icon> especifica slot="start", indicando que é um slot nomeado chamado start. Isso significa que este ícone será inserido no lado esquerdo do componente:

<mdui-button>
  <mdui-icon slot="start" name="settings"></mdui-icon>
  Configurações
</mdui-button>

Se um componente usa vários slots nomeados, a ordem entre eles não é importante. Contanto que estejam dentro do componente, o navegador os colocará automaticamente nas posições corretas.

Consulte a página de documentação de cada componente para ver todos os slots suportados.

Propriedade CSS personalizada

Propriedades CSS personalizadas são variáveis em CSS. O mdui define uma série de propriedades CSS personalizadas globais que são referenciadas internamente por cada componente. Portanto, modificando essas propriedades CSS personalizadas, você pode alterar globalmente a aparência dos componentes do mdui.

Por exemplo, o código a seguir reduz o tamanho dos cantos arredondados de todos os componentes:

:root {
  --mdui-shape-corner-extra-small: 0.125rem;
  --mdui-shape-corner-small: 0.25rem;
  --mdui-shape-corner-medium: 0.375rem;
  --mdui-shape-corner-large: 0.5rem;
  --mdui-shape-corner-extra-large: 0.875rem;
}

Você também pode modificar as propriedades CSS personalizadas em um escopo local. Por exemplo, o código a seguir reduz o tamanho dos cantos arredondados apenas no elemento com class="sharp" e seus elementos filhos:

.sharp {
  --mdui-shape-corner-extra-small: 0.125rem;
  --mdui-shape-corner-small: 0.25rem;
  --mdui-shape-corner-medium: 0.375rem;
  --mdui-shape-corner-large: 0.5rem;
  --mdui-shape-corner-extra-large: 0.875rem;
}

Alguns componentes também fornecem propriedades CSS personalizadas específicas do componente. O escopo dessas propriedades é o componente específico, portanto não incluem o prefixo --mdui. Por exemplo, o código a seguir modifica a propriedade z-index do componente <mdui-dialog> alterando sua propriedade personalizada --z-index:

mdui-dialog {
  --z-index: 3000;
}

Consulte a página de documentação de cada componente para ver as propriedades CSS personalizadas suportadas pelo componente.

CSS Part

Os componentes mdui usam shadow DOM para encapsular estilos e comportamentos, mas seletores CSS convencionais não conseguem selecionar elementos dentro do shadow DOM. Portanto, alguns componentes adicionam o atributo part a elementos do shadow DOM. Você pode usar o seletor CSS ::part para selecionar os elementos correspondentes e sobrescrever parte de seus estilos.

Por exemplo, o código a seguir usa a part button para modificar o preenchimento interno do botão, e as parts label, icon, end-icon para modificar as cores do texto e dos ícones esquerdo/direito:

<mdui-button class="custom-button" icon="explore" end-icon="flight">Botão</mdui-button>

<style>
  .custom-button::part(button) {
    padding: 0 2rem;
  }

  .custom-button::part(label) {
    color: blue;
  }

  .custom-button::part(icon) {
    color: red;
  }

  .custom-button::part(end-icon) {
    color: yellow;
  }
</style>

Para ver a estrutura e os estilos padrão dos elementos shadow DOM do componente, você pode abrir as ferramentas de desenvolvimento do seu navegador.

Antes de usar CSS Part, você deve avaliar se as propriedades CSS personalizadas globais e as propriedades CSS personalizadas específicas do componente atendem às suas necessidades. Se atenderem, priorize o uso de propriedades CSS personalizadas para personalizar os estilos.

Consulte a página de documentação de cada componente para ver todas as partes part expostas pelo componente.

Mecanismo de atualização do componente

Os componentes mdui são baseados no Lit. Lit é uma biblioteca leve que torna o desenvolvimento de Web Components mais simples. Ao usar componentes mdui, você pode precisar entender seu mecanismo de renderização e atualização.

Quando você modifica uma propriedade de um componente mdui, o componente é re-renderizado. No entanto, esse processo de re-renderização não é síncrono. Quando você modifica várias propriedades ao mesmo tempo, o Lit armazena em cache essas alterações até o próximo ciclo de atualização, garantindo que cada componente seja re-renderizado apenas uma vez, independentemente de quantas vezes você modificar as propriedades. Além disso, apenas as partes do shadow DOM que sofreram alterações são re-renderizadas.

No exemplo a seguir, definimos a propriedade JavaScript disabled do botão como true e imediatamente consultamos seu atributo HTML. No entanto, como o componente ainda não foi re-renderizado, o atributo HTML consultado ainda é false:

const button = document.querySelector('mdui-button');
button.disabled = true;

console.log(button.hasAttribute('disabled')); // false

Para aguardar a conclusão da re-renderização após uma alteração de propriedade, use a propriedade updateComplete do componente. Esta propriedade retorna uma Promise que será resolvida quando a re-renderização do componente for concluída:

const button = document.querySelector('mdui-button');
button.disabled = true;

button.updateComplete.then(() => {
  console.log(button.hasAttribute('disabled')); // true
});