跳转到内容

开发者工具栏应用 API

Astro 开发者工具栏应用 API 允许你创建 Astro 集成,以便在 Astro 开发者工具栏中添加应用。这使你可以添加新功能并与第三方服务进行集成。

相关操作指南: 创建开发者工具栏应用

开发者工具栏应用集成设置

段落标题 开发者工具栏应用集成设置

集成可以在 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",
});
},
},
});

这是一个可用于 astro:config:setup 钩子 的函数,用于添加开发者工具栏应用。它接受一个对象,该对象包含定义工具栏应用所需的以下属性:idnameiconentrypoint

应用的唯一标识符。这将用于在钩子和事件中唯一的标识应用。

my-integration.js
{
id: '我的应用',
// ...
}

应用的名称。每当需要使用人类可读的名称引用应用时,都会向用户显示此名称。

my-integration.js
{
// ...
name: '我的应用',
// ...
}

用于在工具栏中显示应用的图标。可以是 图标列表 中的图标,或包含图标 SVG 标记的字符串。

my-integration.js
{
// ...
icon: '<svg>...</svg>', // 或例如 'astro:logo'
// ...
}

导出开发者工具栏应用的文件路径。

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

开发者工具栏应用的结构

段落标题 开发者工具栏应用的结构

开发者工具栏应用是一个 .js.ts 文件,它默认导出一个对象,该对象使用来自 astro/toolbar 模块的 defineToolbarApp() 函数

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

添加于: astro@4.7.0

一个在你的工具栏应用加载和关闭时定义逻辑的函数。

此函数接收一个对象,其中包含一个 init() 函数,该函数将在开发者工具栏应用加载时被调用。它还可以包含一个 beforeTogglingOff() 函数,该函数将在点击工具栏应用以关闭其活动状态时运行。

签名: init(canvas: ShadowRoot, app: ToolbarAppEventTarget, server: ToolbarServerHelpers) => void

虽然不是必需的,但大多数应用会使用这个函数来定义应用的核心行为。这个函数只会在应用加载时被调用一次,具体是在浏览器空闲时或用户在 UI 中点击应用时,具体取决于哪个先发生。

该函数接收三个参数来定义你的应用逻辑:canvas(用于向屏幕渲染元素),app(用于从开发者工具栏发送和接收客户端事件),和 server(用于与服务器通信)。

一个标准的 ShadowRoot,应用可以用来渲染其 UI。可以使用标准的 DOM API 创建元素并添加到 ShadowRoot 中。

每个应用都会接收到一个专用的 ShadowRoot 用于渲染其 UI。此外,父元素使用 position: absolute; 进行定位,因此应用的 UI 不会影响 Astro 页面的布局。

src/my-app.js
export default defineToolbarApp({
init(canvas) {
canvas.appendChild(document.createTextNode('你好,世界!'))
}
});

添加于: astro@4.7.0

一个标准的 EventTarget ,附带一些额外的 客户端事件,可用于从开发者工具栏发送和接收事件。

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);
});
},
});

添加于: astro@4.7.0

一个用于与服务器通信的对象。

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(canvas: ShadowRoot): boolean | void

添加于: astro@4.7.0

当用户在 UI 中点击应用图标来关闭应用时,将调用此可选函数。例如,此函数可以用于执行清理操作,或在关闭应用前要求用户确认。

如果返回 false 值,将取消关闭操作,应用将保持启用状态。

src/my-app.js
export default defineToolbarApp({
// ...
beforeTogglingOff() {
const confirmation = window.confirm('你确定要禁用这个应用吗?');
return confirmation;
}
});

应用的 ShadowRoot 可用于在关闭前渲染所需的任何 UI。与 init 函数的 canvas 参数 相同。

除了 EventTarget 的标准方法(addEventListenerdispatchEventremoveEventListener 等),app 对象还包括以下方法:

签名: onToggled(callback: (options: {state: boolean})) => void

添加于: astro@4.7.0

当用户在 UI 中点击应用图标以开启或关闭应用时,注册一个回调函数。

src/my-app.js
app.onToggled((options) => {
console.log(`应用现在${options.state ? '已启用' : '已禁用'}`);
});

onToolbarPlacementUpdated()

段落标题 onToolbarPlacementUpdated()

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

添加于: astro@4.7.0

当用户更改 Dev Toolbar 的位置时,将触发此事件。例如,这可以用来在工具栏移动时重新定位应用的 UI。

src/my-app.js
app.onToolbarPlacementUpdated((options) => {
console.log(`工具栏现在位于 ${options.placement}`);
});

签名: toggleState(options: {state: boolean}) => void

添加于: astro@4.7.0

更改应用的状态。例如,当用户在应用的 UI 中点击按钮时,可以通过编程方式启用或禁用应用。

src/my-app.js
app.toggleState({ state: false });

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

添加于: astro@4.7.0

在应用图标上切换通知。这可以用来通知用户应用需要关注,或者移除当前的通知。

src/my-app.js
app.toggleNotification({
state: true,
level: 'warning',
});

指示应用是否有针对用户的通知。当 true 时,应用图标将被高亮显示。相反,当 false 时,将移除高亮显示。如果未指定此属性,默认为 true

指示通知的级别。这将用于确定应用图标上高亮显示的颜色和形状(深粉色圆圈、金色三角形或蓝色正方形)。如果未指定此属性,将默认为 'error'

客户端 - 服务器通信

段落标题 客户端 - 服务器通信

使用 Vite 的客户端 - 服务器通信方法,Dev Toolbar Apps 和服务器可以相互通信。为了便于发送和接收自定义消息,提供了辅助方法,可在你的工具栏应用(客户端)和你的集成(服务器端)中使用。

在你的应用中,使用 init() 钩子上的 server 对象 来发送和接收服务器的消息。

src/my-app.js
export default defineToolbarApp({
init(canvas, app, server) {
server.send('my-message', { message: '你好!' });
server.on('server-message', (data) => {
console.log(data.message);
});
},
});

Signature: send<T>(event: stringify, data: T) => void

添加于: astro@4.7.0

从你的工具栏应用中定义的逻辑发送数据到服务器。

src/my-app.js
init(canvas, app, server) {
server.send('my-app:my-message', { message: '你好!' });
}

在从客户端向服务器发送消息时,最好在事件名称前加上应用 ID 或其他命名空间,以避免与可能正在监听消息的其他应用或其他集成发生冲突。

签名: on<T>(event: string, callback: (data: T) => void) => void

添加于: astro@4.7.0

注册一个回调函数,当服务器发送带有指定事件的消息时调用此函数。

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

在一个集成中,例如添加你的工具栏应用的集成,使用 astro:server:setup 钩子 来访问 toolbar 对象,以便向你的应用发送和接收消息。

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

签名: send<T>(event: string, data: T) => void

添加于: astro@4.7.0

向客户端发送数据。

my-integration.js
'astro:server:setup': ({ toolbar }) => {
toolbar.send('server-message', { message: '你好!' });
},

签名: on<T>(event: string, callback: (data: T) => void) => void

添加于: astro@4.7.0

注册一个回调函数,当客户端发送带有指定事件的消息时调用此函数。

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

签名: onInitialized(appId: string, callback: () => void) => void

添加于: astro@4.7.0

注册一个回调函数,当应用初始化时调用此函数。

my-integration.js
'astro:server:setup': ({ toolbar }) => {
toolbar.onInitialized('my-app', () => {
console.log('应用现在已初始化!');
});
},

签名: onAppToggled(appId: string, callback: (options: {state: boolean}) => void) => void

添加于: astro@4.7.0

当用户在 UI 中点击应用图标以开启或关闭应用时,注册一个回调函数。

my-integration.js
'astro:server:setup': ({ toolbar }) => {
toolbar.onAppToggled('my-app', ({ state }) => {
console.log(`应用现在已${state ? '启用' : '禁用'}`);
});
},

Dev Toolbar 包含一套可以用来构建具有一致外观和感觉的应用的 web 组件。

显示窗口。

组件的插槽将被用作窗口的内容。

<astro-dev-toolbar-window>
<p>我的内容</p>
</astro-dev-toolbar-window>

使用 JavaScript 构建窗口时,插槽内容必须放在组件的 light DOM 内。

const myWindow = document.createElement('astro-dev-toolbar-window');
const myContent = document.createElement('p');
myContent.textContent = '我的内容';
// 直接在 `window` 上使用 appendChild,不要使用 `myWindow.shadowRoot`
myWindow.appendChild(myContent);

显示按钮。

组件的插槽将被用作按钮的内容。

const myButton = document.createElement('astro-dev-toolbar-button');
myButton.textContent = '点击我!';
myButton.buttonStyle = "purple";
myButton.size = "medium";
myButton.addEventListener('click', () => {
console.log('被点击了!');
});

按钮的大小(smallmediumlarge)。

按钮的样式(ghostoutlinepurplegrayredgreen, yellow, blue)。当使用 ghost 时,按钮本身是不可见的,只会显示按钮的内容。

在 JavaScript 中,使用 buttonStyle 属性设置此属性以避免与原生 style 属性冲突。

添加于: astro@4.8.0

按钮的边框半径(normal, rounded)。使用 rounded 时,按钮将具有圆角和四周均匀的填充。

在 JavaScript 中,使用 buttonBorderRadius 属性设置此属性。

显示徽章。

组件的插槽将被用作徽章的内容。

<astro-dev-toolbar-badge>我的徽章</astro-dev-toolbar-badge>

徽章的大小(smalllarge)。

徽章的样式(颜色)(purplegrayredgreenyellowblue)。

在 JavaScript 中,使用 badgeStyle 属性设置此属性以避免与原生 style 属性冲突。

显示一张卡片。指定可选的 link 属性使卡片像 <a> 元素一样行动。

当使用 JavaScript 制作卡片时,可以指定 clickAction 属性使卡片像 <button> 元素一样行动。

组件的插槽将被用作卡片的内容。

<astro-dev-toolbar-card icon="astro:logo" link="https://github.com/withastro/astro/issues/new/choose">报告问题</astro-dev-toolbar-card>

卡片的样式(purplegrayredgreenyellowblue)。这些颜色只会在鼠标悬停时应用于卡片的边框上。

在 JavaScript 中,使用 cardStyle 属性来设置这个属性。

显示切换元素,作为复选框。这个元素内部是简单的包装器,围绕着原生的 <input type="checkbox"> 元素。可以使用 input 属性访问复选框元素。

const toggle = document.createElement('astro-dev-toolbar-toggle');
toggle.input.addEventListener('change', (evt) => {
console.log(`现在的切换状态是 ${evt.currentTarget.checked ? '启用' : '禁用'}!`);
});

astro-dev-toolbar-radio-checkbox

段落标题 astro-dev-toolbar-radio-checkbox

添加于: astro@4.8.0

展示一个单选框。类似于 astro-dev-toolbar-toggle 组件,这个元素是围绕原生 <input type="radio"> 元素的简单包装器。可以通过 input 属性访问单选框元素。

const radio = document.createElement('astro-dev-toolbar-radio-checkbox');
radio.input.addEventListener('change', (evt) => {
console.log(`单选框现在${evt.currentTarget.checked ? '启用' : '禁用'}了!`);
});

切换的样式(purplegrayredgreenyellowblue)。

在 JavaScript 中,使用 toggleStyle 属性来设置这个属性。

astro-dev-toolbar-highlight

段落标题 astro-dev-toolbar-highlight

可以用来高亮显示页面上的元素。在大多数情况下,你会想要使用 topleftwidthheight CSS 属性来定位和调整这个元素的大小,以匹配你想要高亮的元素。

<!-- 高亮整个页面 -->
<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';

高亮显示的样式(purplegrayredgreenyellowblue)。

用于在高亮显示的右上角展示的 图标

显示带有不同 sections 的工具提示。此组件默认设置为 display: none;,可以使用 data-show="true" 属性使其可见。

使用 sections 属性定义 sections。此属性是具有以下形状的对象的数组:

{
title?: string; // sections 的标题
inlineTitle?: string; // sections 的标题,显示在标题旁边
icon?: Icon; // sections 的图标
content?: string; // sections 的内容
clickAction?: () => void | Promise<void>; // 点击 sections 时执行的操作
clickDescription?: string; // 点击 sections 时执行的操作的描述
}
const tooltip = document.createElement('astro-dev-toolbar-tooltip');
tooltip.sections = [{
title: '我的部分',
icon: 'astro:logo',
content: '我的内容',
clickAction: () => {
console.log('点击了!')
},
clickDescription: '点击我!'
}]

此组件通常与 astro-dev-toolbar-highlight 组件结合使用,当鼠标悬停在高亮的元素上时显示工具提示:

const highlight = document.createElement('astro-dev-toolbar-highlight');
// 定位高亮...
const tooltip = document.createElement('astro-dev-toolbar-tooltip');
// 向工具提示添加部分...
highlight.addEventListener('mouseover', () => {
tooltip.dataset.show = 'true';
});
highlight.addEventListener('mouseout', () => {
tooltip.dataset.show = 'false';
});

显示图标。可以使用 icon 属性指定图标列表中的图标,或者将图标的 SVG 标记作为插槽传递。

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

目前,可以在任何接受图标的组件中使用以下图标:

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

以上所有图标默认设置为 fill="currentColor",并将从父元素继承其颜色。