API de la App de la Barra de Herramientas de Desarrollo

La API de la App de la Barra de Herramientas de Desarrollo te permite crear apps que pueden ser usadas para extender la Barra de Herramientas de Desarrollo. Esto te permite añadir nuevas funciones e integraciones con servicios de terceros.

Agregando apps

Las Integraciones de Astro pueden agregar apps en el hook astro:config:setup utilizando el método addDevToolbarApp.

/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "my-integration",
  hooks: {
    "astro:config:setup": ({ addDevToolbarApp }) => {
      addDevToolbarApp("./my-app.js");
    },
  },
});

Estructura de la App de la Barra de Herramientas de Desarrollo

Una app de la Barra de Herramientas de Desarrollo es un archivo .js o .ts que exporta por defecto un objeto con las siguientes propiedades obligatorias:

export default {
  id: 'super-app',
  name: 'Mi Super App',
  icon: '<svg>...</svg>',
  init(canvas, eventTarget) {
    eventTarget.dispatchEvent(
      new CustomEvent('toggle-notification', {
        detail: {
          state: true,
        },
      })
    );
  }
}

`id: string`

Un identificador único para la app. Esto se utilizará para identificar de manera única la aplicación en hooks y eventos.

export default {
  id: 'my-app',
  // ...
}

`name: string`

El nombre de la aplicación. Esto se mostrará a los usuarios siempre que sea necesario hacer referencia a la aplicación mediante un nombre legible para los humanos.

export default {
  // ...
  name: 'Mi App',
  // ...
}

`icon: Icon`

El ícono de la aplicación. Esto se utilizará para mostrar la aplicación en la UI. Puede ser un ícono de la lista de íconos, o un string que contenga el marcado SVG del ícono.

export default {
  // ...
  icon: '<svg>...</svg>', // o 'astro:logo'
  // ...
}

`init: (canvas: ShadowRoot, eventTarget: EventTarget) => void`

Esta es la parte central de la aplicación. Esta función se llamará cuando se cargue la aplicación, ya sea cuando el navegador esté inactivo o cuando el usuario haga clic en la aplicación en la UI.

La función recibe dos argumentos:

`canvas`

Un ShadowRoot que la aplicación puede utilizar para renderizar su UI. Cada aplicación recibe su propio ShadowRoot dedicado para renderizar su UI. Además, el elemento padre se posiciona utilizando position: absolute; y, como tal, la UI de la aplicación no afectará automáticamente el diseño de la página.

export default {
  // ...
  init(canvas) {
    canvas.appendChild(document.createTextNode('¡Hola Mundo!'))
  }
}

`eventTarget`

Un EventTarget que puede ser usado para enviar y recibir eventos de la Barra de Herramientas de Desarrollo.

`beforeTogglingOff`

Esta función opcional se llamará cuando el usuario haga clic en el icono de la aplicación en la UI para desactivar la aplicación. Esta función se puede utilizar, por ejemplo, para realizar operaciones de limpieza, realizar una animación o pedir al usuario confirmación antes de desactivar la aplicación.

Si se devuelve un valor falso, la desactivación se cancelará y la aplicación permanecerá habilitada.

export default {
  // ...
  beforeTogglingOff() {
    const confirmation = window.confirm('¿Estás seguro de que quieres desactivar esta app?');
    return confirmation;
  }
}

canvas

El ShadowRoot de la app se puede utilizar para renderizar cualquier UI necesaria.

Eventos del lado del cliente

Utilizando el argumento eventTarget en el hook init, las aplicaciones pueden enviar y recibir eventos desde la Barra de Herramientas de Desarrollo. Los siguientes eventos están disponibles:

`app-toggled`

Este evento es disparado cuando el usuario hace clic en el icono de la aplicación en la Barra de Herramientas de Desarrollo.

  export default {
    // ...
    init(canvas, eventTarget) {
      eventTarget.addEventListener('app-toggled', (event) => {
        if (event.detail.state === true) {
          console.log("¡La app ya está habilitada!")
        }
      })
    }
  }

`placement-updated`

Este evento se dispara cuando el usuario cambia la ubicación de la Barra de Herramientas de Desarrollo.

  export default {
    // ...
    init(canvas, eventTarget) {
      eventTarget.addEventListener('placement-updated', (event) => {
        console.log(`Placement set to ${event.detail.placement}`);
      })
    }
  }

`state: boolean`

Indica si la aplicación está habilitada o no después del clic del usuario.

`toggle-notification`

Este evento puede enviarse para informar al usuario que la aplicación requiere atención.

  export default {
    // ...
    init(canvas, eventTarget) {
      eventTarget.dispatchEvent(
        new CustomEvent('toggle-notification', {
          detail: {
            state: true,
          },
        })
      );
    }
  }

`state: boolean`

Indica si la aplicación tiene o no una notificación para el usuario. Si es true, el icono de la aplicación se resaltará con un punto rojo. Por el contrario, si es false, se eliminará el resaltado. Si no se especifica esta propiedad, se asumirá true.

`level: 'error' | 'warning' | 'info'`

Indica el nivel de la notificación. Se utilizará para determinar el color y la forma (círculo rosa oscuro, triángulo dorado o cuadrado azul) del resalte en el icono de la aplicación. Si no se especifica esta propiedad, se asumirá 'error'.

eventTarget.dispatchEvent(
  new CustomEvent("toggle-notification", {
    detail: {
      level: "warning",
    },
  })
);

`toggle-app`

Este evento puede ser enviado desde tu aplicación para cambiar el estado de la misma. Puede ser útil, por ejemplo, para implementar un botón “Cerrar” en la UI de tu app.

  export default {
    // ...
    init(canvas, eventTarget) {
      eventTarget.dispatchEvent(
        new CustomEvent('toggle-app', {
          detail: {
            state: false,
          },
        })
      );
    }
  }

`state: boolean`

Indica si la aplicación debe estar habilitada o no. Si es true, la aplicación estará habilitada. Por el contrario, si es false, la aplicación estará deshabilitada. Si no se especifica esta propiedad, se asumirá true.

Comunicación Cliente-Servidor

Utilizando los métodos de Vite para la comunicación cliente-servidor, las aplicaciones de la Barra de Herramientas de Desarrollo pueden comunicarse con el servidor.

Además de poder enviar y recibir mensajes personalizados, la Barra de Herramientas de Desarrollo también envía los siguientes mensajes, donde APP_ID es el ID de la app:

`astro-dev-toolbar:APP_ID:initialized`

Este mensaje se envía cuando se inicializa la aplicación. Los datos de este mensaje están vacíos.

{
  // ...
  "astro:server:setup": ({ server }) => {
    server.ws.on("astro-dev-toolbar:super-app:initialized", () => {
      console.log("¡Mi app se ha inicializado!");
    });
  },
  // ...
}

`astro-dev-toolbar:APP_ID:toggled`

Este mensaje se envía cuando el usuario hace clic en el icono de la aplicación en la UI. Los datos de este mensaje son un booleano que indica si la aplicación está activada o no.

{
  // ...
  "astro:server:setup": ({ server }) => {
    server.ws.on("astro-dev-toolbar:super-app:toggled", (data) => {
      console.log(`¡Mi app está ahora ${data.state ? "activada" : "desactivada"}!`);
    });
  },
  // ...
}

Herramientas de la UI

La Barra de Herramientas de Desarrollo incluye un conjuento de componentes web que pueden utilizarse para construir apps con un aspecto coherente.

`astro-dev-toolbar-window`

Muestra una ventana.

El slot del componente que se utilizará como contenido de la ventana.

<astro-dev-toolbar-window>
  <p>Mi contenido</p>
</astro-dev-toolbar-window>

Cuando se construye una ventana utilizando JavaScript, el contenido asignado debe ir dentro del light DOM del componente.

const myWindow = document.createElement('astro-dev-toolbar-window');
const myContent = document.createElement('p');
myContent.textContent = 'Mi contenido';

// usar appendChild directamente en la ventana
myWindow.appendChild(myContent);

`astro-dev-toolbar-button`

Muestra un botón.

El slot del componente que se utilizará como contenido del botón.

const myButton = document.createElement('astro-dev-toolbar-button');
myButton.textContent = '¡Hazme clic!';
myButton.buttonStyle = "purple";
myButton.size = "medium";

myButton.addEventListener('click', () => {
  console.log('¡Clickeado!');
});

`size`

El tamaño del botón (small, medium, large).

`button-style`

El estilo del botón (ghost, outline, purple, gray, red, green, yellow, blue). Cuando se utiliza ghost, el botón es invisible y sólo se muestra su contenido.

En JavaScript, establece esta propiedad utilizando la propiedad buttonStyle para evitar conflictos con la propiedad nativa style.

`astro-dev-toolbar-badge`

Muestra una insignia.

El slot del componente se utilizará como contenido de la insignia.

<astro-dev-toolbar-badge>Mi insignia</astro-dev-toolbar-badge>

`size`

El tamaño de la insignia (small, large).

`badge-style`

El estilo (color) de la insignia (purple, gray, red, green, yellow, blue).

En JavaScript, establece esta propiedad usando la propiedad badgeStyle para evitar conflictos con la propiedad nativa style.

`astro-dev-toolbar-card`

Muestra una tarjeta. Especifica un atributo opcional link para que la tarjeta actúe como un elemento <a>.

Al crear una tarjeta mediante JavaScript, se puede especificar una propiedad clickAction para que la tarjeta actúe como un elemento <button>.

El contenido de la tarjeta se tomará del slot del componente.

<astro-dev-toolbar-card icon="astro:logo" link="https://github.com/withastro/astro/issues/new/choose">Informar de un problema</astro-dev-toolbar-card>

`card-style`

El estilo de la tarjeta (purple, gray, red, green, yellow, blue). El color sólo se aplica al borde de la tarjeta al pasar el ratón por encima.

En JavaScript, establece esta propiedad usando cardStyle.

`astro-dev-toolbar-toggle`

Muestra un elemento toggle, que actúa como una checkbox. Este elemento internamente es una simple envoltura alrededor de un elemento nativo <input type="checkbox">. Se puede acceder al elemento checkbox utilizando la propiedad input.

const toggle = document.createElement('astro-dev-toolbar-toggle');

toggle.input.addEventListener('change', (evt) => {
  console.log(`¡Ahora el interruptor está ${evt.currentTarget.checked ? 'activado' : 'desactivado'}!`);
});

`toggle-style`

El estilo del toggle (purple, gray, red, green, yellow, blue).

En JavaScript, establece esta propiedad utilizando la propiedad toggleStyle.

`astro-dev-toolbar-highlight`

Puede utilizarse para resaltar un elemento de la página. En la mayoría de los casos, querrás posicionar y redimensionar este elemento usando las propiedades CSS top, left, width y height para que coincida con el elemento que quieres resaltar.

<!-- Resaltar toda la página -->
<astro-dev-toolbar-highlight style="top: 0; left: 0; width: 100%; height: 100%;"></astro-dev-toolbar-highlight>

const elementToHighlight = document.querySelector('h1');
const rect = elementToHighlight.getBoundingClientRect();

const highlight = document.createElement('astro-dev-toolbar-highlight');

highlight.style.top = `${Math.max(rect.top + window.scrollY - 10, 0)}px`;
highlight.style.left = `${Math.max(rect.left + window.scrollX - 10, 0)}px`;
highlight.style.width = `${rect.width + 15}px`;
highlight.style.height = `${rect.height + 15}px`;
highlight.icon = 'astro:logo';

`style`

El estilo del resaltado (purple, gray, red, green, yellow, blue).

`icon`

Un icono para mostrar en la esquina superior derecha del resaltado.

`astro-dev-toolbar-tooltip`

Muestra un tooltip con diferentes secciones. Este componente se establece en display: none; de forma predeterminada y puede hacerse visible mediante un atributo data-show="true".

Las secciones se definen utilizando la propiedad sections. Esta propiedad es un array de objetos con la siguiente estructura:

{
  title?: string; // Título de la sección
  inlineTitle?: string; // Título de la sección, mostrado en línea junto al título
  icon?: Icon; // Icono de la sección
  content?: string; // Contenido de la sección
  clickAction?: () => void | Promise<void>; // Acción a realizar al pulsar sobre la sección
  clickDescription?: string; // Descripción de la acción a realizar al pulsar sobre la sección
}

const tooltip = document.createElement('astro-dev-toolbar-tooltip');

tooltip.sections = [{
  title: 'Mi seccion',
  icon: 'astro:logo',
  content: 'Mi contenido',
  clickAction: () => {
    console.log('¡Clickeado!')
  },
  clickDescription: '¡Hazme clic!'
}]

Este componente suele combinarse con el componente astro-dev-toolbar-highlight para mostrar un tooltip al pasar el ratón sobre un elemento resaltado:

const highlight = document.createElement('astro-dev-toolbar-highlight');

// Posicionar el resaltado...

const tooltip = document.createElement('astro-dev-toolbar-tooltip');

// Añadir secciones al tooltip...

highlight.addEventListener('mouseover', () => {
  tooltip.dataset.show = 'true';
});

highlight.addEventListener('mouseout', () => {
  tooltip.dataset.show = 'false';
});

`astro-dev-toolbar-icon`

Muestra un icono. Se puede especificar un icono de la lista de iconos utilizando el atributo icon, o se puede pasar el marcado SVG de un icono como un slot.

<astro-dev-toolbar-icon icon="astro:logo" />

<astro-dev-toolbar-icon>
  <svg>...</svg>
</astro-dev-toolbar-icon>

Iconos

Actualmente, los siguientes iconos están disponibles y pueden ser usando en cualquier componente que acepte un icono:

astro:logo
warning
arrow-down
bug
file-search
check-circle
gear
lightbulb
checkmark
dots-three
copy

Todos los iconos anteriores tienen fill="currentColor" establecido por defecto y heredarán su color del elemento padre.

Crear un problema en GitHub

Envíanos comentarios

API de la App de la Barra de Herramientas de Desarrollo

Agregando apps

Estructura de la App de la Barra de Herramientas de Desarrollo

`id: string`

`name: string`

`icon: Icon`

`init: (canvas: ShadowRoot, eventTarget: EventTarget) => void`

`canvas`

`eventTarget`

`beforeTogglingOff`

canvas

Eventos del lado del cliente

`app-toggled`

`placement-updated`

`state: boolean`

`toggle-notification`

`state: boolean`

`level: 'error' | 'warning' | 'info'`

`toggle-app`

`state: boolean`

Comunicación Cliente-Servidor

`astro-dev-toolbar:APP_ID:initialized`

`astro-dev-toolbar:APP_ID:toggled`

Herramientas de la UI

`size`

`button-style`

`size`

`badge-style`

`card-style`

`toggle-style`

`style`

`icon`

Iconos