开发工具栏应用 API

Astro Dev Toolbar App 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",
      });
    },
  },
});

addDevToolbarApp()

一个在 astro:config:setup 钩子中可用的函数，用于添加开发工具栏应用。它接受一个包含以下必需属性的对象来定义工具栏应用：id、name、icon 和 entrypoint。

id

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

my-integration.js

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

name

应用的名称。当需要使用人类可读的名称引用应用时，这个名称将显示给用户。

my-integration.js

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

icon

用于在工具栏中显示应用的图标。这可以是一个来自图标列表的图标，也可以是一个包含图标 SVG 标记的字符串。

my-integration.js

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

entrypoint

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

my-integration.js

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

添加于： astro@5.0.0

该函数也接受一个 URL 作为 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),
      });
    },
  },
});

开发工具栏应用的结构

开发工具栏应用是一个 .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;
  }
});

defineToolbarApp()

添加于： astro@4.7.0

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

此函数接受一个带 init() 函数的对象，该函数将在开发工具栏应用加载时被调用。它还可以接受一个 beforeTogglingOff() 函数，该函数将在单击工具栏应用以关闭其活动状态时运行。

init()

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

虽然不是必需的，但大多数应用将使用此函数来定义应用的核心行为。此函数仅在应用加载时调用一次，加载时机要么是浏览器空闲时，要么是用户在 UI 中点击应用时，取决于哪个先发生。

该函数接收三个参数来定义你的应用逻辑：canvas（用于在屏幕上渲染元素）、app（用于从开发工具栏发送和接收客户端事件）和 server（用于与服务器通信）。

canvas

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

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

src/my-app.js

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

app

添加于： 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);
    });
  },
});

server

添加于： 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()

签名： beforeTogglingOff(canvas: ShadowRoot): boolean | void

添加于： astro@4.7.0

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

如果返回一个假值，关闭操作将被取消，应用将保持启用状态。

src/my-app.js

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

canvas

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

客户端事件

除了 EventTarget 的标准方法（addEventListener、dispatchEvent、removeEventListener 等）之外，app 对象还具有以下方法

onToggled()

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

添加于： astro@4.7.0

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

src/my-app.js

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

onToolbarPlacementUpdated()

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

添加于： astro@4.7.0

当用户更改开发工具栏的位置时，会触发此事件。例如，这可以用于在工具栏移动时重新定位应用的 UI。

src/my-app.js

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

toggleState()

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

添加于： astro@4.7.0

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

src/my-app.js

app.toggleState({ state: false });

toggleNotification()

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

添加于： astro@4.7.0

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

src/my-app.js

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

state: boolean

指示应用是否需要通知用户。当为 true 时，应用图标将被高亮显示。反之，当为 false 时，高亮将被移除。如果未指定此属性，将假定为 true。

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

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

客户端-服务器通信

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

在客户端

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

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()

签名： 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: 'Hello!' });
}

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

on()

签名： 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()

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

添加于： astro@4.7.0

向客户端发送数据。

my-integration.js

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

on()

签名： 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()

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

添加于： astro@4.7.0

注册一个回调函数，在应用初始化时调用。

my-integration.js

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

注意

Vite 的内置 connection 事件在开发工具栏应用初始化之前触发，因此不能被应用直接使用。使用 onInitialized 方法确保在向应用发送消息之前，应用已完全初始化。

onAppToggled()

签名： 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(`The app is now ${state ? 'enabled' : 'disabled'}!`);
  });
},

组件库

开发工具栏包含一组 Web 组件，可用于构建具有一致外观和感觉的应用。

astro-dev-toolbar-window

显示一个窗口。

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

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

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

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

显示一个按钮。

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

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

按钮的大小（small、medium、large）。

button-style

按钮的样式（ghost、outline、purple、gray、red、green、yellow、blue）。使用 ghost 时，按钮本身是不可见的，只显示按钮的内容。

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

button-border-radius

添加于： astro@4.8.0

按钮的边框半径（normal、rounded）。使用 rounded 时，按钮将具有圆角和所有侧面的均匀内边距。

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

astro-dev-toolbar-badge

显示一个徽章。

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

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

size

徽章的大小（small、large）。

badge-style

徽章的样式（颜色）（purple、gray、red、green、yellow、blue）。

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

astro-dev-toolbar-card

显示一个卡片。指定可选的 link 属性，使卡片像 <a> 元素一样工作。

使用 JavaScript 创建卡片时，可以指定一个 clickAction 属性，使卡片像 <button> 元素一样工作。

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

<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

卡片的样式（purple、gray、red、green、yellow、blue）。颜色仅在悬停时应用于卡片的边框。

在 JavaScript 中，使用 cardStyle 设置此属性。

astro-dev-toolbar-toggle

显示一个切换元素，其作用类似于复选框。该元素内部是原生 <input type="checkbox"> 元素的简单包装。可以使用 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'}!`);
});

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(`The radio is now ${evt.currentTarget.checked ? 'enabled' : 'disabled'}!`);
});

toggle-style

切换开关的样式（purple、gray、red、green、yellow、blue）。

在 JavaScript 中，使用 toggleStyle 属性设置此属性。

astro-dev-toolbar-highlight

可用于高亮页面上的元素。在大多数情况下，你会希望使用 top、left、width 和 height CSS 属性来定位和调整此元素的大小，以匹配你想要高亮的元素。

<!-- 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

高亮的样式（purple、gray、red、green、yellow、blue）。

icon

一个在高亮区域右上角显示的图标。

astro-dev-toolbar-tooltip

显示一个带有不同部分的工具提示。默认情况下，此组件设置为 display: none;，可以使用 data-show="true" 属性使其可见。

部分是使用 sections 属性定义的。此属性是一个对象数组，其形状如下

{
  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!'
}]

此组件通常与 astro-dev-toolbar-highlight 组件结合使用，以在悬停高亮元素时显示工具提示

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

显示一个图标。可以使用 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"，并将从其父元素继承颜色。