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
Sección titulada Agregando appsLas Integraciones de Astro pueden agregar apps en el hook astro:config:setup
utilizando el método addDevToolbarApp
.
Estructura de la App de la Barra de Herramientas de Desarrollo
Sección titulada Estructura de la App de la Barra de Herramientas de DesarrolloUna 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:
id: string
Sección titulada id: stringUn identificador único para la app. Esto se utilizará para identificar de manera única la aplicación en hooks y eventos.
name: string
Sección titulada name: stringEl 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.
icon: Icon
Sección titulada icon: IconEl í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.
init: (canvas: ShadowRoot, eventTarget: EventTarget) => void
Sección titulada init: (canvas: ShadowRoot, eventTarget: EventTarget) => voidEsta 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
Sección titulada canvasUn 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.
eventTarget
Sección titulada eventTargetUn EventTarget
que puede ser usado para enviar y recibir eventos de la Barra de Herramientas de Desarrollo.
beforeTogglingOff
Sección titulada beforeTogglingOffEsta 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.
canvas
Sección titulada canvasEl ShadowRoot de la app se puede utilizar para renderizar cualquier UI necesaria.
Eventos del lado del cliente
Sección titulada Eventos del lado del clienteUtilizando 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
Sección titulada app-toggledEste evento es disparado cuando el usuario hace clic en el icono de la aplicación en la Barra de Herramientas de Desarrollo.
placement-updated
Sección titulada placement-updatedEste evento se dispara cuando el usuario cambia la ubicación de la Barra de Herramientas de Desarrollo.
state: boolean
Sección titulada state: booleanIndica si la aplicación está habilitada o no después del clic del usuario.
toggle-notification
Sección titulada toggle-notificationEste evento puede enviarse para informar al usuario que la aplicación requiere atención.
state: boolean
Sección titulada state: booleanIndica 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'
Sección titulada 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'
.
toggle-app
Sección titulada toggle-appEste 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.
state: boolean
Sección titulada state: booleanIndica 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
Sección titulada Comunicación Cliente-ServidorUtilizando 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
Sección titulada astro-dev-toolbar:APP_ID:initializedEste mensaje se envía cuando se inicializa la aplicación. Los datos de este mensaje están vacíos.
astro-dev-toolbar:APP_ID:toggled
Sección titulada astro-dev-toolbar:APP_ID:toggledEste 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.
El evento integrado connection
de Vite se dispara antes de que se inicialicen las aplicaciones de la Barra de Herramientas de Desarrollo y, por tanto, no puede ser utilizado directamente por las aplicaciones. En su lugar, utiliza el evento astro-dev-toolbar:APP_ID:initialized
.
Herramientas de la UI
Sección titulada Herramientas de la UILa 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
Sección titulada astro-dev-toolbar-windowMuestra una ventana.
El slot del componente que se utilizará como contenido de la ventana.
Cuando se construye una ventana utilizando JavaScript, el contenido asignado debe ir dentro del light DOM del componente.
astro-dev-toolbar-button
Sección titulada astro-dev-toolbar-buttonMuestra un botón.
El slot del componente que se utilizará como contenido del botón.
El tamaño del botón (small
, medium
, large
).
button-style
Sección titulada button-styleEl 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
Sección titulada astro-dev-toolbar-badgeMuestra una insignia.
El slot del componente se utilizará como contenido de la insignia.
El tamaño de la insignia (small
, large
).
badge-style
Sección titulada badge-styleEl 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
Sección titulada astro-dev-toolbar-cardMuestra 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.
card-style
Sección titulada card-styleEl 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
Sección titulada astro-dev-toolbar-toggleMuestra 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
.
toggle-style
Sección titulada toggle-styleEl estilo del toggle (purple
, gray
, red
, green
, yellow
, blue
).
En JavaScript, establece esta propiedad utilizando la propiedad toggleStyle
.
astro-dev-toolbar-highlight
Sección titulada astro-dev-toolbar-highlightPuede 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.
El estilo del resaltado (purple
, gray
, red
, green
, yellow
, blue
).
Un icono para mostrar en la esquina superior derecha del resaltado.
astro-dev-toolbar-tooltip
Sección titulada astro-dev-toolbar-tooltipMuestra 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:
Este componente suele combinarse con el componente astro-dev-toolbar-highlight
para mostrar un tooltip al pasar el ratón sobre un elemento resaltado:
astro-dev-toolbar-icon
Sección titulada astro-dev-toolbar-iconMuestra 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.
Iconos
Sección titulada IconosActualmente, 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.