创建开发工具栏应用

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

¥Astro includes a development toolbar that you can use to inspect your site, check for accessibility and performance issues, and more. This toolbar can be extended with custom apps.

构建激励性开发工具栏应用

¥Build a motivational dev toolbar app

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

¥In this recipe, you’ll learn how to create a dev toolbar app that helps you stay motivated while working on your site. This app will display a motivational message every time you toggle it on.

Just want to get started quickly? Jump start your app by creating a new Astro project with the toolbar-app template.

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

pnpm create astro -- --template toolbar-app

yarn create astro -- --template toolbar-app

Or, keep reading to learn how to build an app from scratch.

创建 Astro 集成

¥Creating the Astro integration

只能由 Astro 集成使用 astro:config:setup 钩子添加开发工具栏应用。你将需要创建一个工具栏应用和将其添加到现有 Astro 项目的工具栏的集成。

¥Dev toolbar apps can only be added by Astro Integrations using the astro:config:setup hook. You will need to create both a toolbar app and the integration that will add it to the toolbar of your existing Astro project.

In the root of your existing Astro project, create a new folder named my-toolbar-app/ for your app and integration files. Create two new files in this folder: app.ts and my-integration.ts.
- Directorymy-toolbar-app/
  - app.ts
  - my-integration.ts
- Directorysrc/
  - Directorypages/
    …
  - …
- astro.config.mjs
- package.json
- tsconfig.json
In my-integration.ts, add the following code to provide both the name of your integration and the addDevToolbarApp() function needed to add your dev toolbar app with the astro:config:setup hook:
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;
```
The entrypoint is the path to your dev toolbar app file relative to the root of your existing Astro project, not to the integration folder (my-toolbar-app) itself.
To use relative paths for entrypoints, get the path to the current file using import.meta.url and resolve the path to the entrypoint from there.

To use this integration in your project, add it to the integrations array in your astro.config.mjs file.

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

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

If not already running, start the dev server. If your integration has been successfully added to your project, you should see a new “undefined” app in the dev toolbar.

But, you will also see an error message that your dev toolbar app has failed to load. This is because you have not yet built the app itself. You will do that in the next section.

See the Astro Integration API documentation for more about building Astro integrations.

创建应用

¥Creating the app

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

¥Dev toolbar apps are defined using the defineToolbarApp() function from the astro/toolbar module. This function takes an object with an init() function that will be called when the dev toolbar app is loaded.

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

¥This init() function contains your app logic to render elements to the screen, send and receive client-side events from the dev toolbar, and communicate with the server.

import { defineToolbarApp } from "astro/toolbar";

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

要在屏幕上显示激励信息，你将使用 canvas 属性访问标准 ShadowRoot。可以使用标准 DOM API 创建元素并将其添加到 ShadowRoot。

¥To display motivational messages on the screen, you will use the canvas property to access a standard ShadowRoot. Elements can be created and added to the ShadowRoot using the standard DOM APIs.

Copy the following code into my-toolbar-app/app.ts. This provides a list of motivational messages, and the logic to create a new <h1> element with a random message:

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

Start the dev server if it is not already running and toggle the app on in the dev toolbar. If your app is working successfully, you will see a motivational message displayed in the top-left corner of the screen. (And, it’s true!)

However, this message will not change when the app is toggled on and off, as the init() function is only called once when the app is loaded.

To add client-side interactivity to your app, add the app argument and use onAppToggled() to select a new random message each time your toolbar app is toggled on:

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

In your browser preview, toggle your app on and off several times. With this change, a new random message will be selected every time you toggle the app on, providing you with an infinite source of motivation!

See the Astro Dev Toolbar API documentation for more about building dev toolbar apps.

使用 UI 框架构建应用

¥Building apps with a UI framework

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

¥UI frameworks like React, Vue, or Svelte can also be used to create dev toolbar apps. These frameworks provide a more declarative way to create UIs and can make your code more maintainable and easier to read.

可以使用 UI 框架（例如 Preact）来构建本页上之前使用 JavaScript 内置到你现有 Astro 项目中的相同激励性开发工具栏应用。根据你选择的框架，你可能需要或不需要构建步骤。

¥The same motivational dev toolbar app built into your existing Astro project earlier on this page with JavaScript can be built using a UI framework (e.g. Preact) instead. Depending on your chosen framework, you may or may not require a build step.

不带构建步骤

¥Without a build step

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

¥If your framework supports it, you can create a dev toolbar app without a build step. For example, you can use Preact’s h function to create elements and render them directly to the 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 提供原生集成并支持其他框架：

¥Alternatively, the htm package is a good choice for creating dev toolbar apps without a build step, offering native integration for React and Preact and support for other frameworks:

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

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

¥In both cases, you can now start your project and see the motivational message displayed in the top-left corner of the screen when you toggle the app on.

带有构建步骤

¥With a build step

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

¥Astro does not preprocess JSX code in dev toolbar apps, so a build step is required in order to use JSX components in your dev toolbar app.

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

¥The following steps will use TypeScript to do this, but any other tools that compile JSX code will also work (e.g. Babel, Rollup, ESBuild).

Install TypeScript inside your project:

npm install --save-dev typescript

pnpm install --save-dev typescript

yarn add --dev typescript

Create a tsconfig.json file in the root of your toolbar app’s folder with the appropriate settings to build and for the framework you’re using (React, Preact, Solid). For example, for Preact:
my-toolbar-app/tsconfig.json
```
{
  "compilerOptions": {
    "skipLibCheck": true,
    "module": "NodeNext",
    "jsx": "react-jsx",
    "jsxImportSource": "preact",
  }
}
```
Adjust the entrypoint in your integration to point to the compiled file, remembering that this file is relative to the root of your Astro project:
my-integration.ts
```
addDevToolbarApp({
  id: "my-toolbar-app",
  name: "My Toolbar App",
  icon: "🚀",
  entrypoint: join(__dirname, "./app.js"),
});
```

Run tsc to build your toolbar app, or tsc --watch to automatically rebuild your app when you make changes.

With these changes, you can now rename your app.ts file to app.tsx (or .jsx) and use JSX syntax to create your dev toolbar app:

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 框架创建开发工具栏应用所需的所有工具！

¥You should now have all the tools you need to create a dev toolbar app using a UI framework of your choice!