Dev Toolbar App API
このコンテンツはまだ日本語訳がありません。
The Astro Dev Toolbar App API allows you to create apps that can be used to extend the Astro Dev Toolbar. This allows you to add new features and integrations with third-party services.
Adding apps
Section titled Adding appsAstro Integrations can add apps in the astro:config:setup
hook using the addDevToolbarApp
method.
This method takes an object with different properties to define the app:
/** * @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", }); }, },});
A unique identifier for the app. This will be used to uniquely identify the app in hooks and events.
{ id: 'my-app', // ...}
The name of the app. This will be shown to users whenever the app needs to be referenced using a human-readable name.
{ // ... name: 'My App', // ...}
The icon of the app. This will be used to display the app in the UI. This can either be an icon from the icon list, or a string containing the SVG markup of the icon.
{ // ... icon: '<svg>...</svg>', // or, e.g. 'astro:logo' // ...}
entrypoint
Section titled entrypointThe path to the app’s entrypoint.
{ // ... entrypoint: './my-app.js',}
Structure of a Dev Toolbar App
Section titled Structure of a Dev Toolbar AppA Dev Toolbar App is a .js
or .ts
file that default exports an object with the following properties:
import { defineToolbarApp } from "astro:toolbar";
export default defineToolbarApp({ init(canvas) { const text = document.createTextNode('Hello World!'); canvas.appendChild(text); }});
init()
Section titled init()Signature: init(canvas: ShadowRoot, app: ToolbarAppEventTarget, server: ToolbarServerHelpers) => void
This is the core part of the app. This function will be called when the app is loaded, which will either be when the browser is idle or when the user clicks on the app in the UI, depending on which one comes first.
The function receives three arguments:
canvas
Section titled canvasA ShadowRoot that the app can use to render its UI. Every app receives its own dedicated ShadowRoot for rendering its UI. Additionally, the parent element is positioned using position: absolute;
and as such, the app UI automatically won’t affect the layout of the page.
export default defineToolbarApp({ init(canvas) { canvas.appendChild(document.createTextNode('Hello World!')) }});
An EventTarget
augmented with a few helpers that can be used to send and receive events from the Dev Toolbar, see the Client-side Events section for more information.
export default defineToolbarApp({ init(canvas, app) { app.onAppToggled(({ state }) => { const text = document.createTextNode( `The app is now ${state ? "enabled" : "disabled"}!`, ); canvas.appendChild(text); }); },});
server
Section titled serverAn object that can be used to communicate with the server, see the Client-Server Communication section for more information.
export default defineToolbarApp({ init(canvas, app, server) { server.send('my-message', { message: 'Hello!' });
server.on('server-message', (data) => { console.log(data.message); }); },});
beforeTogglingOff()
Section titled beforeTogglingOff()Signature: beforeTogglingOff(canvas: ShadowRoot): boolean | void
This optional function will be called when the user clicks on the app icon in the UI to toggle off the app. This function can be used, for example, to perform cleanup operations, or to ask the user for confirmation before toggling off the app.
If a falsy value is returned, the toggling off will be cancelled and the app will stay enabled.
export default defineToolbarApp({ // ... beforeTogglingOff() { const confirmation = window.confirm('Are you sure you want to disable this app?'); return confirmation; }});
canvas
Section titled canvasThe ShadowRoot of the app, can be used to render any UI needed before closing. Same as the canvas
argument of the init
function.
Client-side Events
Section titled Client-side EventsIn addition to the standard methods of an EventTarget
(addEventListener, dispatchEvent, etc), the app
object also has the following methods:
onToggled()
Section titled onToggled()Signature: onToggled(callback: (options: {state: boolean})) => void
Registers a callback to be called when the user clicks on the app icon in the UI to toggle the app on or off.
app.onToggled((options) => { console.log(`The app is now ${options.state ? 'enabled' : 'disabled'}!`);});
onToolbarPlacementUpdated()
Section titled onToolbarPlacementUpdated()Signature: onToolbarPlacementUpdated(callback: (options: {placement: 'bottom-left' | 'bottom-center' | 'bottom-right'})) => void
This event is fired when the user changes the placement of the Dev Toolbar. This can, for example, be used to reposition the app’s UI when the toolbar is moved.
app.onToolbarPlacementUpdated((options) => { console.log(`The toolbar is now placed at ${options.placement}!`);});
toggleState()
Section titled toggleState()Signature: toggleState(options: {state: boolean}) => void
Changes the state of the app. This can be used to enable or disable the app programmatically, for example, when the user clicks on a button in the app’s UI.
app.changeAppState({state: false});
toggleNotification()
Section titled toggleNotification()Signature: toggleNotification(options: {state?: boolean, level?: 'error' | 'warning' | 'info'}) => void
Toggles a notification on the app icon. This can be used to inform the user that the app requires attention, or remove the current notification.
app.toggleNotification({ state: true, level: 'warning',});
state: boolean
Section titled state: booleanIndicates whether or not the app has a notification for the user. When true
, the app icon will be highlighted. Conversely, when false
, the highlight will be removed. If this property is not specified, true
will be assumed.
level: 'error' | 'warning' | 'info'
Section titled level: 'error' | 'warning' | 'info'Indicates the level of the notification. This will be used to determine the color and shape (dark pink circle, gold triangle, or blue square) of the highlight on the app icon. If this property is not specified, 'error'
will be assumed.
Client-Server Communication
Section titled Client-Server CommunicationUsing Vite’s methods for client-server communication, Dev Toolbar Apps can communicate with the server and vice versa. In order to facilitate this, helper methods are provided both in the app (client) and your integration (server).
On the client
Section titled On the clientIn your app, you can use the server
object on the init()
hook to send and receive messages from the server.
send()
Section titled send()Signature: send<T>(event: stringify, data: T) => void
Sends data to the server.
init(canvas, app, server) { server.send('my-app:my-message', { message: 'Hello!' });}
When sending messages from the client to the server, it is good practice to prefix the event name with the app ID or other namespaces to avoid conflicts with other apps or other integrations that may be listening for messages.
Signature: on<T>(event: string, callback: (data: T) => void) => void
Registers a callback to be called when the server sends a message with the specified event.
init(canvas, app, server) { server.on('server-message', (data) => { console.log(data.message); });}
On the server
Section titled On the serverIn your integration’s astro:server:setup
hook, you can use the toolbar
object to send and receive messages from your apps.
send()
Section titled send()Signature: send<T>(event: string, data: T) => void
Sends data to the client
'astro:server:setup': ({ toolbar }) => { toolbar.send('server-message', { message: 'Hello!' });},
Signature: on<T>(event: string, callback: (data: T) => void) => void
Registers a callback to be called when the client sends a message with the specified event.
'astro:server:setup': ({ toolbar }) => { toolbar.on('my-app:my-message', (data) => { console.log(data.message); });},
onInitialized
Section titled onInitializedSignature: onInitialized(appId: string, callback: () => void) => void
Registers a callback to be called when the app is initialized.
'astro:server:setup': ({ toolbar }) => { toolbar.onInitialized('my-app', () => { console.log('The app is now initialized!'); });},
The built-in connection
event from Vite fires before Dev Toolbar apps are initialized and therefore cannot be used directly by apps, as such you should always use the onInitialized
method to ensure that the app is fully initialized before sending messages to it.
onAppToggled
Section titled onAppToggledSignature: onAppToggled(appId: string, callback: (options: {state: boolean}) => void) => void
Registers a callback to be called when the user clicks on the app icon in the UI to toggle the app on or off.
'astro:server:setup': ({ toolbar }) => { toolbar.onAppToggled('my-app', ({ state }) => { console.log(`The app is now ${state ? 'enabled' : 'disabled'}!`); });},
Component Library
Section titled Component LibraryThe Dev Toolbar includes a set of web components that can be used to build apps with a consistent look and feel.
astro-dev-toolbar-window
Section titled astro-dev-toolbar-windowShows a window.
The slot of the component will be used as the content of the window.
<astro-dev-toolbar-window> <p>My content</p></astro-dev-toolbar-window>
When building a window using JavaScript, slotted content must go inside the light DOM of the component.
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
Section titled astro-dev-toolbar-buttonShows a button.
The slot of the component will be used as the content of the button.
const myButton = document.createElement('astro-dev-toolbar-button');myButton.textContent = 'Click me!';myButton.buttonStyle = "purple";myButton.size = "medium";
myButton.addEventListener('click', () => { console.log('Clicked!');});
The size of the button (small
, medium
, large
).
button-style
Section titled button-styleThe style of the button (ghost
, outline
, purple
, gray
, red
, green
, yellow
, blue
). When using ghost
, the button itself is invisible and only the content of the button will be shown.
In JavaScript, set this property using the buttonStyle
property to avoid conflict with the native style
property.
astro-dev-toolbar-badge
Section titled astro-dev-toolbar-badgeShows a badge.
The slot of the component will be used as the content of the badge.
<astro-dev-toolbar-badge>My badge</astro-dev-toolbar-badge>
The size of the badge (small
, large
).
badge-style
Section titled badge-styleThe style (color) of the badge (purple
, gray
, red
, green
, yellow
, blue
).
In JavaScript, set this property using the badgeStyle
property to avoid conflict with the native style
property.
astro-dev-toolbar-card
Section titled astro-dev-toolbar-cardShows a card. Specify an optional link
attribute to make the card act like an <a>
element.
When making a card using JavaScript, a clickAction
property can be specified to make the card act like a <button>
element.
The slot of the component will be used as the content of the card.
<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
Section titled card-styleThe style of the card (purple
, gray
, red
, green
, yellow
, blue
). The color is only applied to the border of the card on hover.
In JavaScript, set this property using the cardStyle
.
astro-dev-toolbar-toggle
Section titled astro-dev-toolbar-toggleShows a toggle element, acting as a checkbox. This element internally is a simple wrapper around a native <input type="checkbox">
element. The checkbox element can be accessed using the input
property.
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
Section titled toggle-styleThe style of the toggle (purple
, gray
, red
, green
, yellow
, blue
).
In JavaScript, set this property using the toggleStyle
property.
astro-dev-toolbar-highlight
Section titled astro-dev-toolbar-highlightCan be used to highlight an element on the page. In most cases, you’ll want to position and resize this element using the top
, left
, width
and height
CSS properties to match the element you want to highlight.
<!-- 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';
style
Section titled styleThe style of the highlight (purple
, gray
, red
, green
, yellow
, blue
).
An icon to show in the top right corner of the highlight.
astro-dev-toolbar-tooltip
Section titled astro-dev-toolbar-tooltipShows a tooltip with different sections. This component is set to display: none;
by default and can be made visible using a data-show="true"
attribute.
Sections are defined using the sections
property. This property is an array of objects with the following shape:
{ 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!'}]
This component is often combined with the astro-dev-toolbar-highlight
component to show a tooltip when hovering a highlighted element:
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
Section titled astro-dev-toolbar-iconShows an icon. An icon from the icon list can be specified using the icon
attribute, or the SVG markup of an icon can be passed as a slot.
<astro-dev-toolbar-icon icon="astro:logo" />
<astro-dev-toolbar-icon> <svg>...</svg></astro-dev-toolbar-icon>
Icons
Section titled IconsCurrently, the following icons are available and can be used in any component that accepts an icon:
astro:logo
warning
arrow-down
bug
file-search
check-circle
gear
lightbulb
checkmark
dots-three
copy
All of the above icons have fill="currentColor"
set by default and will inherit their color from the parent element.