Uso rápido

Los componentes de mdui son Web Components estándar. Puedes usarlos como si fueran etiquetas <div>. La documentación de cada componente describe su API completa, incluidos atributos, propiedades, métodos, eventos, slots, CSS Part y CSS Custom Properties.

Este capítulo te introducirá al uso de Web Components.

Atributos

Los atributos se dividen en atributos HTML y propiedades JavaScript. Por lo general, tienen una correspondencia uno a uno y se mantienen sincronizados. Es decir, cuando actualizas el valor de un atributo HTML, el valor de la propiedad JavaScript también se actualiza; y viceversa.

Los atributos HTML se pueden establecer directamente en la cadena HTML del componente, y se pueden leer y modificar mediante los métodos getAttribute y setAttribute:

<mdui-button variant="text">Haz clic</mdui-button>

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

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

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

Las propiedades JavaScript se pueden leer o establecer directamente en el valor de la propiedad de la instancia del componente:

<mdui-button variant="text">Haz clic</mdui-button>

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

  // Establecer la propiedad JavaScript
  button.variant = 'outlined';

  // Leer la propiedad JavaScript
  console.log(button.variant); // outlined
</script>

Algunos atributos tienen valores booleanos. Para estos atributos, cuando el atributo HTML existe, la propiedad JavaScript es true; de lo contrario, es false. Sin embargo, por compatibilidad con ciertos frameworks, mdui también considera el valor de cadena 'false' como el valor booleano false.

<!-- Este componente tiene el atributo disabled, es decir, el valor predeterminado de disabled es true -->
<mdui-button disabled></mdui-button>

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

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

  // Excepción: establecer la cadena 'false' equivale a establecer el valor booleano false
  button.setAttribute('disabled', 'false'); // equivale a button.disabled = false;
</script>

A veces el valor de un atributo puede ser un array, objeto o función. En ese caso, solo existe la propiedad JavaScript, sin su correspondiente atributo HTML. Por ejemplo, la propiedad labelFormatter del componente <mdui-slider> es una función, y solo se puede establecer mediante JavaScript:

<mdui-slider></mdui-slider>

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

A modo de ejemplo, tomamos parte de la documentación de atributos del componente <mdui-slider>:

Este componente tiene el atributo name tanto como atributo HTML y propiedad JavaScript, y la columna reflect indica que al actualizar la propiedad JavaScript se sincroniza con el atributo HTML. En cambio, al actualizar la propiedad value no se actualiza el atributo HTML. La propiedad labelFormatter solo existe como propiedad JavaScript.

Métodos

Algunos componentes ofrecen métodos públicos que puedes invocar para realizar distintas acciones. Por ejemplo, el método focus() del componente <mdui-text-field> permite enfocar el campo de texto.

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

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

Puedes consultar todos los métodos disponibles y sus parámetros en la página de documentación de cada componente.

Eventos

Algunos componentes activan eventos al realizar ciertas acciones. Por ejemplo, el componente <mdui-dialog> activa el evento open al abrirse. Puedes escuchar este evento para ejecutar acciones personalizadas.

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

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

  dialog.addEventListener('open', () => {
    console.log('Cuando el diálogo comienza a abrirse, se activa este evento');
  });
</script>

Puedes consultar todos los eventos disponibles y sus parámetros en la página de documentación de cada componente.

Si usas mdui en otros frameworks (como Vue, React o Angular), puedes usar la sintaxis del propio framework para vincular eventos. Sin embargo, algunos frameworks (como React) solo permiten vincular eventos estándar (como el evento click), pero no eventos personalizados (como open). Por lo tanto, en React, para vincular eventos personalizados, necesitas obtener una referencia al elemento y usar el método addEventListener.

Para más información sobre el uso de mdui con React, consulta Integración con frameworks - React.

Slot

Muchos componentes ofrecen slots para insertar contenido HTML personalizado en su interior.

El más común es el slot por defecto, que es un fragmento de HTML o texto plano dentro del componente. Por ejemplo, el slot por defecto del componente <mdui-button> se usa para establecer el texto del botón. En el ejemplo, "Haz clic" es el contenido del slot por defecto:

<mdui-button>Haz clic</mdui-button>

Algunos componentes también proporcionan slots con nombre. Los slots con nombre requieren especificar el nombre del slot en el atributo slot del HTML. En el siguiente ejemplo, el componente <mdui-icon> especifica slot="start", indicando que es un slot con nombre start, es decir, este ícono se insertará en el lado izquierdo del componente:

<mdui-button>
  <mdui-icon slot="start" name="settings"></mdui-icon>
  Configuración
</mdui-button>

Si un componente usa múltiples slots con nombre, el orden entre ellos no es importante. Siempre que estén dentro del componente, el navegador los colocará automáticamente en la posición correcta.

Puedes consultar todos los slots soportados en la página de documentación de cada componente.

CSS Custom Properties

Las CSS Custom Properties son variables en CSS. mdui define una serie de CSS Custom Properties globales que son referenciadas dentro de cada componente, por lo que puedes modificar estas CSS Custom Properties para cambiar globalmente el estilo de los componentes de mdui.

Por ejemplo, el siguiente código reduce el tamaño de las esquinas redondeadas de todos los 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;
}

También puedes modificar las CSS Custom Properties en un ámbito local. Por ejemplo, el siguiente código solo reduce el tamaño de las esquinas redondeadas en el elemento con class="sharp" y sus elementos hijos:

.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;
}

Algunos componentes también ofrecen CSS Custom Properties específicas de ese componente. Como su ámbito es el propio componente, no incluyen el prefijo --mdui. Por ejemplo, el siguiente código modifica la propiedad --z-index del componente <mdui-dialog> para cambiar su estilo z-index:

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

Puedes consultar las CSS Custom Properties soportadas por cada componente en su página de documentación.

CSS Part

Los componentes de mdui usan shadow DOM para encapsular estilos y comportamientos, pero los selectores CSS convencionales no pueden seleccionar elementos dentro del shadow DOM. Por lo tanto, algunos componentes añaden el atributo part a los elementos del shadow DOM. Puedes usar el selector CSS ::part para seleccionar esos elementos y sobrescribir parte de su estilo.

Por ejemplo, el siguiente código usa el part button para modificar el relleno del botón, y los parts label, icon y end-icon para modificar el color del texto y de los íconos izquierdo y derecho:

<mdui-button class="custom-button" icon="explore" end-icon="flight">Botón</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>

Puedes abrir las herramientas de desarrollo del navegador para inspeccionar la estructura y los estilos predeterminados de los elementos del shadow DOM del componente.

Antes de usar CSS Part, debes considerar si las CSS Custom Properties globales y las CSS Custom Properties específicas del componente pueden satisfacer tus necesidades. Si es así, es recomendable usar CSS Custom Properties para personalizar los estilos.

Puedes consultar todas las propiedades part que un componente expone en su página de documentación.

Mecanismo de actualización de componentes

Los componentes de mdui están desarrollados con Lit. Lit es una biblioteca ligera que facilita el desarrollo de Web Components. Al usar componentes de mdui, es posible que necesites comprender su mecanismo de renderizado y actualización.

Cuando modificas una propiedad de un componente de mdui, este se vuelve a renderizar. Sin embargo, este proceso de re-renderizado no es síncrono. Cuando modificas múltiples propiedades a la vez, Lit almacena en caché estos cambios hasta el siguiente ciclo de actualización, asegurando que cada componente se renderice solo una vez, sin importar cuántas veces se hayan modificado las propiedades. Además, solo se vuelve a renderizar la parte del shadow DOM que ha cambiado.

En el siguiente ejemplo, establecemos la propiedad JavaScript disabled del botón en true y luego consultamos inmediatamente su atributo HTML. Sin embargo, como el componente aún no se ha re-renderizado, el atributo HTML sigue siendo false:

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

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

Para esperar a que termine el re-renderizado después de cambiar una propiedad, puedes usar updateComplete. Esta propiedad devuelve una Promise que se resuelve cuando el componente ha terminado de re-renderizarse:

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

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