创建一个开发工具栏应用

Astro 包含一个开发工具栏，你可以用它来检查你的网站、检查可访问性和性能问题等。这个工具栏可以通过自定义应用进行扩展。

在本指南中，你将学习如何创建一个开发工具栏应用，帮助你在开发网站时保持动力。每次打开这个应用，它都会显示一条激励人心的信息。

想快速开始吗？通过使用 toolbar-app 模板创建一个新的 Astro 项目来快速启动你的应用。

npm create astro@latest -- --template toolbar-app

pnpm create astro -- --template toolbar-app

yarn create astro -- --template toolbar-app

或者，继续阅读以学习如何从头开始构建应用。

创建 Astro 集成

开发工具栏应用只能通过 Astro 集成使用 the astro:config:setup 钩子来添加。你需要创建一个工具栏应用以及一个集成，该集成会将应用添加到你现有 Astro 项目的工具栏中。

在你现有 Astro 项目的根目录下，为你的应用和集成文件创建一个名为 my-toolbar-app/ 的新文件夹。在这个文件夹中创建两个新文件：app.ts 和 my-integration.ts。
- 目录my-toolbar-app/
  - app.ts
  - my-integration.ts
- 目录src/
  - 目录pages/
    …
  - …
- astro.config.mjs
- package.json
- tsconfig.json
在 my-integration.ts 中，添加以下代码，以提供你的集成名称和使用 astro:config:setup 钩子添加开发工具栏应用所需的 addDevToolbarApp() 函数。
my-toolbar-app/my-integration.ts
```
import { fileURLToPath } from 'node:url';
import type { AstroIntegration } from 'astro';

export default {
  name: 'my-astro-integration',
  hooks: {
    'astro:config:setup': ({ addDevToolbarApp }) => {
      addDevToolbarApp({
        id: "my-toolbar-app",
        name: "My Toolbar App",
        icon: "🚀",
        entrypoint: fileURLToPath(new URL('./app.ts', import.meta.url))
      });
    },
  },
} satisfies AstroIntegration;
```
entrypoint 是你的开发工具栏应用文件的路径，该路径相对于你现有 Astro 项目的根目录，而不是相对于集成文件夹（my-toolbar-app）本身。
要为入口点使用相对路径，请使用 import.meta.url 获取当前文件的路径，并从中解析到入口点的路径。

要在你的项目中使用此集成，请将其添加到你的 astro.config.mjs 文件中的 integrations 数组中。

import { defineConfig } from 'astro/config';
import myIntegration from './my-toolbar-app/my-integration.ts';

export default defineConfig({
  integrations: [myIntegration],
})

如果开发服务器尚未运行，请启动它。如果你的集成已成功添加到项目中，你应该会在开发工具栏中看到一个新的“undefined”应用。

但是，你还会看到一条错误消息，提示你的开发工具栏应用加载失败。这是因为你尚未构建应用本身。你将在下一节中进行此操作。

有关构建 Astro 集成的更多信息，请参阅 Astro 集成 API 文档。

创建应用

开发工具栏应用是使用 astro/toolbar 模块中的 defineToolbarApp() 函数定义的。此函数接受一个包含 init() 函数的对象，该函数将在开发工具栏应用加载时被调用。

这个 init() 函数包含了你的应用逻辑，用于在屏幕上渲染元素、从开发工具栏发送和接收客户端事件，以及与服务器通信。

import { defineToolbarApp } from "astro/toolbar";

export default defineToolbarApp({
    init(canvas, app, server) {
      // ...
    },
});

为了在屏幕上显示激励人心的信息，你将使用 canvas 属性来访问一个标准的 ShadowRoot。可以使用标准的 DOM API 创建元素并将其添加到 ShadowRoot 中。

将以下代码复制到 my-toolbar-app/app.ts 中。这段代码提供了一个激励信息的列表，以及创建一个带有随机信息的新 <h1> 元素的逻辑。

import { defineToolbarApp } from "astro/toolbar";

const motivationalMessages = [
  "You're doing great!",
  "Keep up the good work!",
  "You're awesome!",
  "You're a star!",
];

export default defineToolbarApp({
    init(canvas) {
      const h1 = document.createElement('h1');
      h1.textContent = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)];

      canvas.append(h1);
    },
});

如果开发服务器尚未运行，请启动它，并在开发工具栏中打开该应用。如果你的应用运行成功，你将在屏幕左上角看到一条激励人心的信息。（而且，这是真的！）

然而，当应用被打开和关闭时，这条信息不会改变，因为 init() 函数只在应用加载时被调用一次。

要为你的应用添加客户端交互性，请添加 app 参数并使用 onAppToggled() 在每次打开工具栏应用时选择一条新的随机信息。

import { defineToolbarApp } from "astro/toolbar";

const motivationalMessages = [
  "You're doing great!",
  "Keep up the good work!",
  "You're awesome!",
  "You're a star!",
];

export default defineToolbarApp({
    init(canvas, app) {
      const h1 = document.createElement('h1');
      h1.textContent = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)];

      canvas.append(h1);

      // Display a random message when the app is toggled
      app.onToggled(({ state }) => {
        const newMessage = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)];
        h1.textContent = newMessage;
      });
    },
});

在你的浏览器预览中，多次打开和关闭你的应用。通过此更改，每次你打开应用时都会选择一条新的随机信息，为你提供源源不断的动力！

有关构建开发工具栏应用的更多信息，请参阅 Astro 开发工具栏 API 文档。

使用 UI 框架构建应用

像 React、Vue 或 Svelte 这样的 UI 框架也可以用来创建开发工具栏应用。这些框架提供了一种更具声明性的方式来创建 UI，可以使你的代码更易于维护和阅读。

本页前面用 JavaScript 构建到你现有 Astro 项目中的同一个激励人心的开发工具栏应用，也可以改用 UI 框架（例如 Preact）来构建。根据你选择的框架，你可能需要也可能不需要构建步骤。

无构建步骤

如果你的框架支持，你可以创建一个没有构建步骤的开发工具栏应用。例如，你可以使用 Preact 的 h 函数来创建元素并直接将它们渲染到 ShadowRoot。

import { defineToolbarApp } from "astro/toolbar";
import { render, h } from "preact";

const motivationalMessages = [
  "You're doing great!",
  "Keep up the good work!",
  "You're awesome!",
  "You're a star!",
];

export default defineToolbarApp({
    init(canvas) {
      const message = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)];
      render(h('h1', null, message), canvas);
    },
});

另外，htm 包是一个无需构建步骤即可创建开发工具栏应用的好选择，它为 React 和 Preact 提供了原生集成，并支持其他框架。

import { defineToolbarApp } from "astro/toolbar";
import { render } from "preact";
import { html } from 'htm/preact';

const motivationalMessages = [
  "You're doing great!",
  "Keep up the good work!",
  "You're awesome!",
  "You're a star!",
];

export default defineToolbarApp({
    init(canvas) {
      const message = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)];
      render(html`<h1>${message}</h1>`, canvas);
    },
});

在这两种情况下，你现在都可以启动你的项目，并在打开应用时在屏幕左上角看到显示的激励信息。

有构建步骤

Astro 不会预处理开发工具栏应用中的 JSX 代码，因此，要在你的开发工具栏应用中使用 JSX 组件，就需要一个构建步骤。

以下步骤将使用 TypeScript 来完成此操作，但任何其他编译 JSX 代码的工具（例如 Babel、Rollup、ESBuild）也同样适用。

在你的项目中安装 TypeScript。

npm install --save-dev typescript

pnpm install --save-dev typescript

yarn add --dev typescript

在你的工具栏应用文件夹的根目录下创建一个 tsconfig.json 文件，并为其配置适合构建和你所使用的框架的设置（React、Preact、Solid）。例如，对于 Preact：
my-toolbar-app/tsconfig.json
```
{
  "compilerOptions": {
    "skipLibCheck": true,
    "module": "NodeNext",
    "jsx": "react-jsx",
    "jsxImportSource": "preact",
  }
}
```
调整你集成中的 entrypoint，使其指向编译后的文件，请记住此文件路径是相对于你的 Astro 项目根目录的。
my-integration.ts
```
addDevToolbarApp({
  id: "my-toolbar-app",
  name: "My Toolbar App",
  icon: "🚀",
  entrypoint: join(__dirname, "./app.js"),
});
```

运行 tsc 来构建你的工具栏应用，或者运行 tsc --watch 在你做出更改时自动重新构建你的应用。

完成这些更改后，你现在可以将你的 app.ts 文件重命名为 app.tsx（或 .jsx），并使用 JSX 语法来创建你的开发工具栏应用。

import { defineToolbarApp } from "astro/toolbar";
import { render } from "preact";

const motivationalMessages = [
  "You're doing great!",
  "Keep up the good work!",
  "You're awesome!",
  "You're a star!",
];

export default defineToolbarApp({
    init(canvas) {
      const message = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)];
      render(<h1>{message}</h1>, canvas);
    },
});

现在，你应该拥有了使用你选择的 UI 框架创建开发工具栏应用所需的所有工具！

贡献社区赞助