Dev Toolbar App API

La API de Dev Toolbar App de Astro te permite crear integraciones de Astro que añaden apps a la barra de herramientas de desarrollo de Astro. Esto te permite añadir nuevas características e integraciones con servicios de terceros.

Related recipe: Crear una aplicación para la barra de herramientas de desarrollo

Configuración de integración de la app de la barra de herramientas

Las integraciones pueden añadir apps a la barra de herramientas de desarrollo en el hook astro:config:setup.

my-integration.js

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

addDevToolbarApp()

Type: (entrypoint: DevToolbarAppEntry) => void

Añadido en: astro@4.0.0

Una función disponible para el hook astro:config:setup que añade apps a la barra de herramientas de desarrollo. Toma un objeto con las siguientes propiedades requeridas para definir la app de la barra de herramientas: id, name y entrypoint. Opcionalmente, también puedes definir un icon para tu app.

id

Type: string

Un identificador único para la app. Esto se utilizará para identificar de forma única la app en hooks y eventos.

my-integration.js

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

name

Type: string

El nombre de la app. Esto se mostrará a los usuarios siempre que sea necesario hacer referencia a la app utilizando un nombre legible por humanos.

my-integration.js

{
  // ...
  name: 'My App',
  // ...
}

icon

Type: Icono | string
Default: "?"

El icono utilizado para mostrar la app en la barra de herramientas. Puede ser un icono de la lista de iconos, o una cadena que contenga el marcado SVG del icono.

my-integration.js

{
  // ...
  icon: '<svg>...</svg>', // or, e.g. 'astro:logo'
  // ...
}

entrypoint

Type: string | URL

La ruta al archivo que exporta la app de la barra de herramientas de desarrollo.

my-integration.js

{
  // ...
  entrypoint: './my-app.js',
}

Añadido en: astro@5.0.0

La función también acepta una URL como entrypoint:

my-integration.js

/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "my-integration",
  hooks: {
    "astro:config:setup": ({ addDevToolbarApp }) => {
      addDevToolbarApp({
        id: "my-app",
        name: "My App",
        icon: "<svg>...</svg>",
        entrypoint: new URL("./my-app.js", import.meta.url),
      });
    },
  },
});

Estructura de una Dev Toolbar App

Una Dev Toolbar App es un archivo .js o .ts que exporta por defecto un objeto utilizando la función defineToolbarApp() disponible en el módulo astro/toolbar.

src/my-app.js

import { defineToolbarApp } from "astro/toolbar";

export default defineToolbarApp({
  init(canvas) {
    const text = document.createTextNode('Hello World!');
    canvas.appendChild(text);
  },
  beforeTogglingOff() {
    const confirmation = window.confirm('Really exit?');
    return confirmation;
  }
});

defineToolbarApp()

Type: (app: DevToolbarApp) => DevToolbarApp

Añadido en: astro@4.7.0

Una función que define la lógica de tu app de la barra de herramientas cuando se carga y se desactiva.

Esta función toma un objeto con una función init() que se llamará cuando se cargue la app de la barra de herramientas de desarrollo. También puede tomar una función beforeTogglingOff() que se ejecutará cuando se haga clic en la app de la barra de herramientas para desactivar su estado activo.

init()

Tipo: (canvas: ShadowRoot, app: ToolbarAppEventTarget, server: ToolbarServerHelpers) => void | Promise<void>

Aunque no es obligatorio, la mayoría de las apps utilizarán esta función para definir el comportamiento principal de la app. Esta función se llamará solo una vez cuando se cargue la app, lo cual ocurrirá cuando el navegador esté inactivo o cuando el usuario haga clic en la app en la UI, lo que ocurra primero.

La función recibe tres argumentos para definir la lógica de tu app: canvas (para renderizar elementos en la pantalla), app (para enviar y recibir eventos del lado del cliente desde la barra de herramientas de desarrollo), y server (para comunicarse con el servidor).

canvas

Type: ShadowRoot

Un ShadowRoot estándar que la app puede usar para renderizar su UI. Los elementos se pueden crear y añadir al ShadowRoot utilizando las APIs estándar del DOM.

Cada app recibe su propio ShadowRoot dedicado para renderizar su UI. Además, el elemento padre se posiciona usando position: absolute; para que la UI de la app no afecte al diseño de una página de Astro.

src/my-app.js

export default defineToolbarApp({
  init(canvas) {
    canvas.appendChild(document.createTextNode('Hello World!'))
  }
});

app

Type: ToolbarAppEventTarget

Añadido en: astro@4.7.0

Un EventTarget estándar con algunos ayudantes adicionales para eventos del lado del cliente que se pueden usar para enviar y recibir eventos desde la barra de herramientas de desarrollo.

src/my-app.js

export default defineToolbarApp({
  init(canvas, app) {
    app.onToggled(({ state }) => {
      const text = document.createTextNode(
        `The app is now ${state ? "enabled" : "disabled"}!`,
      );
      canvas.appendChild(text);
    });
  },
});

server

Type: ToolbarServerHelpers

Añadido en: astro@4.7.0

Un objeto que se puede usar para comunicarse con el servidor.

src/my-app.js

export default defineToolbarApp({
  init(canvas, app, server) {
    server.send('my-message', { message: 'Hello!' });

    server.on('server-message', (data) => {
      console.log(data.message);
    });
  },
});

beforeTogglingOff()

Type: (canvas: ShadowRoot) => boolean | Promise<boolean>

Añadido en: astro@4.7.0

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

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

src/my-app.js

export default defineToolbarApp({
  // ...
  beforeTogglingOff() {
    const confirmation = window.confirm('Are you sure you want to disable this app?');
    return confirmation;
  }
});

canvas

Type: ShadowRoot

El ShadowRoot de la app, se puede usar para renderizar cualquier UI necesaria antes de cerrar. Igual que el argumento canvas de la función init.

Eventos del lado del cliente

Además de los métodos estándar de un EventTarget (addEventListener, dispatchEvent, removeEventListener, etc.), el objeto app también tiene los siguientes métodos:

onToggled()

Type: (callback: (options: {state: boolean})) => void

Añadido en: astro@4.7.0

Registra una función callback que se llamará cuando el usuario haga clic en el icono de la app en la UI para activar o desactivar la app.

src/my-app.js

app.onToggled((options) => {
  console.log(`The app is now ${options.state ? 'enabled' : 'disabled'}!`);
});

onToolbarPlacementUpdated()

Tipo: (callback: (options: {placement: 'bottom-left' | 'bottom-center' | 'bottom-right'})) => void

Añadido en: astro@4.7.0

Este evento se dispara cuando el usuario cambia la ubicación de la barra de herramientas de desarrollo. Esto se puede usar, por ejemplo, para reposicionar la UI de la app cuando se mueve la barra de herramientas.

src/my-app.js

app.onToolbarPlacementUpdated((options) => {
  console.log(`The toolbar is now placed at ${options.placement}!`);
});

toggleState()

Type: (options: {state: boolean}) => void

Añadido en: astro@4.7.0

Cambia el estado de la app. Esto se puede usar para habilitar o deshabilitar la app mediante programación, por ejemplo, cuando el usuario hace clic en un botón en la UI de la app.

src/my-app.js

app.toggleState({ state: false });

toggleNotification()

Tipo: (options: {state?: boolean, level?: 'error' | 'warning' | 'info'}) => void

Añadido en: astro@4.7.0

Alterna una notificación en el icono de la app. Esto se puede usar para informar al usuario que la app requiere atención, o para eliminar la notificación actual.

src/my-app.js

app.toggleNotification({
  state: true,
  level: 'warning',
});

state

Type: boolean

Indica si la app tiene o no una notificación para el usuario. Cuando es true, el icono de la app se resaltará. Por el contrario, cuando es false, se quitará el resaltado. Si no se especifica esta propiedad, se asumirá true.

level

Type: 'error' | 'warning' | 'info'
Default: 'error'

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

Comunicación Cliente-Servidor

Utilizando los métodos de Vite para la comunicación cliente-servidor, las Dev Toolbar Apps y el servidor pueden comunicarse entre sí. Para facilitar el envío y la recepción de mensajes personalizados, se proporcionan métodos de ayuda para su uso tanto en tu app de la barra de herramientas (en el cliente) como en tu integración (en el servidor).

En el cliente

En tu app, utiliza el objeto server en el hook init() para enviar y recibir mensajes hacia y desde el servidor.

src/my-app.js

export default defineToolbarApp({
  init(canvas, app, server) {
    server.send('my-message', { message: 'Hello!' });

    server.on('server-message', (data) => {
      console.log(data.message);
    });
  },
});

send()

Type: <T>(event: string, payload: T) => void

Añadido en: astro@4.7.0

Envía datos al servidor desde la lógica definida en tu app de la barra de herramientas.

src/my-app.js

init(canvas, app, server) {
  server.send('my-app:my-message', { message: 'Hello!' });
}

Al enviar mensajes desde el cliente al servidor, es una buena práctica prefijar el nombre del evento con el ID de la app u otros espacios de nombres para evitar conflictos con otras apps u otras integraciones que puedan estar escuchando mensajes.

on()

Tipo: <T>(event: string, callback: (data: T) => void) => void

Añadido en: astro@4.7.0

Registra una función callback que se llamará cuando el servidor envíe un mensaje con el evento especificado.

src/my-app.js

init(canvas, app, server) {
  server.on('server-message', (data) => {
    console.log(data.message);
  });
}

En el servidor

En una integración, como la integración que añade tu app de la barra de herramientas, utiliza el hook astro:server:setup para acceder al objeto toolbar para enviar y recibir mensajes hacia y desde tus apps.

my-integration.js

export default () => ({
  name: "my-integration",
  hooks: {
    "astro:config:setup": ({ addDevToolbarApp }) => {},
    "astro:server:setup": ({ toolbar }) => {},
  },
});

send()

Type: <T>(event: string, payload: T) => void

Añadido en: astro@4.7.0

Envía datos al cliente.

my-integration.js

'astro:server:setup': ({ toolbar }) => {
  toolbar.send('server-message', { message: 'Hello!' });
},

on()

Tipo: <T>(event: string, callback: (data: T) => void) => void

Añadido en: astro@4.7.0

Registra una función callback que se llamará cuando el cliente envíe un mensaje con el evento especificado.

my-integration.js

'astro:server:setup': ({ toolbar }) => {
  toolbar.on('my-app:my-message', (data) => {
    console.log(data.message);
  });
},

onAppInitialized()

Type: (appId: string, callback: () => void) => void

Añadido en: astro@4.7.0

Registra una función callback que se llamará cuando se inicialice la app.

my-integration.js

'astro:server:setup': ({ toolbar }) => {
  toolbar.onAppInitialized('my-app', () => {
    console.log('The app is now initialized!');
  });
},

Nota

El evento de conexión incorporado de Vite se dispara antes de que se inicialicen las apps de la barra de herramientas de desarrollo y, por lo tanto, las apps no pueden usarlo directamente. Utiliza el método onAppInitialized para asegurarte de que la app esté completamente inicializada antes de enviarle mensajes.

onAppToggled()

Tipo: (appId: string, callback: (options: {state: boolean}) => void) => void

Añadido en: astro@4.7.0

Registra una función callback que se llamará cuando el usuario haga clic en el icono de la app en la UI para activar o desactivar la app.

my-integration.js

'astro:server:setup': ({ toolbar }) => {
  toolbar.onAppToggled('my-app', ({ state }) => {
    console.log(`The app is now ${state ? 'enabled' : 'disabled'}!`);
  });
},

Biblioteca de componentes

La barra de herramientas de desarrollo incluye un conjunto de componentes web que se pueden usar para crear apps con una apariencia consistente.

astro-dev-toolbar-window

Muestra una ventana.

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

<astro-dev-toolbar-window>
  <p>My content</p>
</astro-dev-toolbar-window>

Al construir una ventana usando JavaScript, el contenido en el slot debe ir dentro del light DOM del componente.

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

// use appendChild directly on `window`, not `myWindow.shadowRoot`
myWindow.appendChild(myContent);

astro-dev-toolbar-button

Muestra un botón.

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

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

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

size

Type: "small" | "medium" | "large"
Default: "small"

El tamaño del botón.

button-style

Type: "ghost" | "outline" | "purple" | "gray" | "red" | "green" | "yellow" | "blue"
Default: "purple"

El estilo del botón. Al usar ghost, el botón en sí es invisible y solo se mostrará el contenido del botón.

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

button-border-radius

Type: "normal" | "rounded"
Default: "normal"

Añadido en: astro@4.8.0

El radio de borde del botón. Al usar rounded, el botón tendrá esquinas redondeadas y un espaciado uniforme en todos los lados.

En JavaScript, establece esta propiedad usando la propiedad buttonBorderRadius.

astro-dev-toolbar-badge

Muestra una insignia.

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

<astro-dev-toolbar-badge>My badge</astro-dev-toolbar-badge>

size

Type: "small" | "large"
Default: "small"

El tamaño de la insignia.

badge-style

Type: "purple" | "gray" | "red" | "green" | "yellow" | "blue"
Default: "purple"

El estilo (color) de la insignia.

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 hacer que la tarjeta actúe como un elemento <a>.

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

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

<astro-dev-toolbar-card icon="astro:logo" link="https://github.com/withastro/astro/issues/new/choose">Report an issue</astro-dev-toolbar-card>

card-style

Type: "purple" | "gray" | "red" | "green" | "yellow" | "blue"
Default: "purple"

El estilo de la tarjeta. El color solo se aplica al borde de la tarjeta al pasar el cursor.

En JavaScript, establece esta propiedad usando cardStyle.

astro-dev-toolbar-toggle

Muestra un elemento interruptor (toggle), que actúa como una casilla de verificación (checkbox). Este elemento internamente es un simple contenedor alrededor de un elemento nativo <input type="checkbox">. Se puede acceder al elemento de la casilla de verificación usando la propiedad input.

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

toggle.input.addEventListener('change', (evt) => {
  console.log(`The toggle is now ${evt.currentTarget.checked ? 'enabled' : 'disabled'}!`);
});

toggle-style

Type: "purple" | "gray" | "red" | "green" | "yellow" | "blue"
Default: "gray"

El estilo del toggle.

En JavaScript, establece esta propiedad usando la propiedad toggleStyle.

astro-dev-toolbar-radio-checkbox

Añadido en: astro@4.8.0

Muestra una casilla de radio. Similar al componente astro-dev-toolbar-toggle, este elemento es un contenedor simple alrededor de un elemento nativo <input type="radio">. Se puede acceder al elemento de radio usando la propiedad input.

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

radio.input.addEventListener('change', (evt) => {
  console.log(`The radio is now ${evt.currentTarget.checked ? 'enabled' : 'disabled'}!`);
});

radio-style

Type: "purple" | "gray" | "red" | "green" | "yellow" | "blue"
Default: "purple"

El estilo del botón de radio.

En JavaScript, establece esta propiedad usando la propiedad radioStyle.

astro-dev-toolbar-highlight

Se puede usar para resaltar un elemento en la página. En la mayoría de los casos, querrás posicionar y redimensionar este elemento utilizando las propiedades CSS top, left, width y height para que coincidan con el elemento que deseas resaltar.

<!-- Highlight the entire page -->
<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';

highlight-style

Type: "purple" | "gray" | "red" | "green" | "yellow" | "blue"
Default: "purple"

El estilo del resaltado.

icon

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

astro-dev-toolbar-tooltip

Muestra un tooltip con diferentes secciones. Este componente está establecido en display: none; por defecto y se puede hacer visible utilizando un atributo data-show="true".

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

{
  title?: string; // Title of the section
  inlineTitle?: string; // Title of the section, shown inline next to the title
  icon?: Icon; // Icon of the section
  content?: string; // Content of the section
  clickAction?: () => void | Promise<void>; // Action to perform when clicking on the section
  clickDescription?: string; // Description of the action to perform when clicking on the section
}

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

tooltip.sections = [{
  title: 'My section',
  icon: 'astro:logo',
  content: 'My content',
  clickAction: () => {
    console.log('Clicked!')
  },
  clickDescription: 'Click me!'
}]

Este componente a menudo se combina con el componente astro-dev-toolbar-highlight para mostrar un tooltip al pasar el cursor sobre un elemento resaltado:

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

// Position the highlight...

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

// Add sections to the 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 usando 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>

astro-dev-toolbar-select

Añadido en: astro@4.6.0

Muestra un elemento select. Similar al componente astro-dev-toolbar-toggle, este elemento es un simple contenedor al rededor de un elemento <select> nativo. Usa la propiedad element para tener acceso al elemento select.

const mySelect = document.createElement("astro-dev-toolbar-select");
const options = [
  { label: "First option", value: "first" },
  { label: "Second option", value: "second", isDefault: true },
];
const myOptions = options.map((option) => {
  const optionEl = document.createElement("option");
  optionEl.textContent = option.label;
  optionEl.setAttribute("value", option.value);
  optionEl.selected = option.isDefault || false;
  return optionEl;
});

mySelect.selectStyle = "green";
mySelect.append(...myOptions);

mySelect.element.addEventListener("change", (evt) => {
  if (evt.currentTarget instanceof HTMLSelectElement) {
    console.log(`The select value is now ${evt.currentTarget.value}!`);
  }
});

select-style

Type: "purple" | "gray" | "red" | "green" | "yellow" | "blue"
Default: "gray"

El estilo del select.

En JavaScript, establece esta propiedad usando la propiedad selectStyle.

Iconos

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

• astro:logo
• warning
• arrow-down
• bug
• check-circle
• gear
• lightbulb
• file-search
• star
• checkmark
• dots-three
• copy
• compress
• grid
• puzzle
• approveUser
• checkCircle
• resizeImage
• searchFile
• image
• robot
• sitemap
• gauge
• person-arms-spread
• arrow-left
• houston-detective

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