wix-cli-dashboard-plugin

Wix 控制面板插件构建器

为 Wix CLI 应用创建控制面板插件扩展。控制面板插件是交互式小组件，可嵌入由 Wix 第一方业务应用（Wix Stores、Wix Bookings、Wix Blog、Wix eCommerce 等）管理的控制面板页面中的预定义插槽。

控制面板插件占据其插槽的全部宽度，并根据内容动态调整高度。

---

快速入门清单

创建控制面板插件时，请按顺序执行以下步骤：

1. 确定目标插槽 ID — 参见插槽参考
2. 创建插件文件夹：src/extensions/dashboard/plugins/<plugin-name>/
3. 创建 <plugin-name>.extension.ts，其中包含 extensions.dashboardPlugin() 和唯一 UUID
4. 创建 <plugin-name>.tsx，其中包含由 WixDesignSystemProvider 包裹的 React 组件
5. 更新 src/extensions.ts，导入并使用新扩展

架构

控制面板插件通过两种机制运行：

1. 视觉集成 — 将插件 UI 嵌入受支持的控制面板页面插槽
2. 逻辑集成 — 通过 observeState() 实现插件与宿主页面数据之间的通信

文件和代码结构

控制面板插件位于 src/extensions/dashboard/plugins/ 下。每个插件都有自己的文件夹。

src/extensions/dashboard/plugins/
└── <plugin-name>/
    ├── <plugin-name>.extension.ts   # Builder configuration
    └── <plugin-name>.tsx            # React component

注意： 这是 CLI 创建的默认文件夹结构。你可以将这些文件移至 src/ 文件夹中的任意位置，并更新 extension.ts 文件中的引用。

插件构建器配置

文件：<plugin-name>.extension.ts

import { extensions } from "@wix/astro/builders";

export const dashboardpluginMyPlugin = extensions.dashboardPlugin({
  id: "{{GENERATE_UUID}}",
  title: "My Dashboard Plugin",
  extends: "<SLOT_ID>",
  component: "./extensions/dashboard/plugins/my-plugin/my-plugin.tsx",
});

重要：生成 UUID

id 必须是唯一的静态 UUID v4 字符串。请为每个扩展生成一个新的 UUID — 不要使用 randomUUID()，也不要复制示例中的 UUID。请将 {{GENERATE_UUID}} 替换为新生成的 UUID，例如 "a1b2c3d4-e5f6-7890-abcd-ef1234567890"。

构建器字段

字段	类型	说明
id	string	唯一的插件 ID（GUID）。在项目的所有扩展中必须唯一。
title	string	插件标题。用于在项目控制面板中引用该插件。
extends	string	容纳插件的控制面板页面插槽 ID。参见插槽参考。
component	string	插件内容组件（.tsx 文件）的相对路径。

extends 字段

extends 字段用于指定容纳插件的控制面板页面插槽。每个 Wix 业务应用都会在其控制面板页面上提供插槽。你必须提供准确的插槽 ID。

重要： 控制面板中的不同页面上可能会出现 ID 相同的插槽。如果你为一个存在于多个页面上的插槽创建插件，该插件会显示在所有这些页面上。

如需查看可用插槽 ID 的完整列表，请参见插槽参考。

插件组件

文件：<plugin-name>.tsx

插件组件是一个在控制面板页面插槽中渲染的 React 组件。

import type { FC } from "react";
import { WixDesignSystemProvider, Card, Text } from "@wix/design-system";
import "@wix/design-system/styles.global.css";

const Plugin: FC = () => {
  return (
    <WixDesignSystemProvider features={{ newColorsBranding: true }}>
      <Card>
        <Card.Header title="My Plugin" />
        <Card.Divider />
        <Card.Content size="medium">
          <Text>Plugin content goes here.</Text>
        </Card.Content>
      </Card>
    </WixDesignSystemProvider>
  );
};

export default Plugin;

插件组件中可用的资源

• React — 组件逻辑和状态管理
• Wix SDK — 访问 Wix 业务解决方案和站点数据
• Wix Dashboard SDK（@wix/dashboard）— 与传递给插槽的控制面板页面数据交互
• Wix Design System（@wix/design-system）— 使用与 Wix 自有控制面板 UI 外观一致的原生风格 React 组件

与控制面板数据交互

使用 Dashboard SDK 中的 observeState() 接收宿主控制面板页面的数据：

import { dashboard } from "@wix/dashboard";
import { useEffect, useState } from "react";

const Plugin: FC = () => {
  const [params, setParams] = useState<Record<string, unknown>>({});

  useEffect(() => {
    dashboard.observeState((componentParams) => {
      setParams(componentParams);
    });
  }, []);

  return (
    <WixDesignSystemProvider features={{ newColorsBranding: true }}>
      <Card>
        <Card.Content size="medium">
          <Text>Received data: {JSON.stringify(params)}</Text>
        </Card.Content>
      </Card>
    </WixDesignSystemProvider>
  );
};

宿主应用提供的类型化 Props

部分 Wix 应用会为其插槽参数提供类型化接口。请从应用的控制面板软件包中导入这些接口：

import type { plugins } from "@wix/blog/dashboard";

type Props = plugins.BlogPosts.PostsBannerParams;

const Plugin: FC<Props> = (props) => {
  // props are typed according to the Blog Posts slot contract
};

注意： 类型化 props 是否可用因 Wix 应用而异。请查阅相应应用的 SDK 文档。并非所有插槽都提供类型化参数接口。

扩展注册

扩展注册为必需操作，且必须完成以下两个步骤。

步骤 1：创建插件专属扩展文件

每个仪表盘插件都需要在其文件夹中有一个 <plugin-name>.extension.ts 文件。请参阅上文的 插件构建器配置。

步骤 2：在主扩展文件中注册

重要： 创建插件专属扩展文件后，你必须阅读 wix-cli-extension-registration，并按照其中的“应用注册”部分更新 src/extensions.ts。

如果未完成步骤 2，仪表盘插件将不会显示在仪表盘页面上。

尺寸行为

• 仪表盘插件会占满其插槽的全部宽度
• 高度会根据插槽边界内的内容动态调整
• 使用 Dashboard SDK 或 dashboard-react SDK 时，尺寸会根据内容动态变化

故障排除

症状	原因	修复方法
插件未显示在仪表盘页面上	缺少注册	在 src/extensions.ts 中导入并调用 .use()
插件未显示在仪表盘页面上	插槽 ID 错误	确认 extends 字段与 插槽参考 中的有效插槽 ID 匹配

严格约束

• 不要编造或假设新的类型、模块、函数、属性、事件或导入；只能使用提供的参考资料或本项目已使用的标准库中明确包含的实体
• 任何代码中都绝不要使用模拟数据、占位符或 TODO；始终实现完整、可用于生产环境的功能
• extends 字段必须包含 Wix 商业应用中的有效插槽 ID；不要编造插槽 ID
• 优先使用类型收窄和穷尽逻辑，而不是断言；避免非空断言（!）和不安全的类型转换（as any）
• 不要使用 // @ts-ignore 或 // @ts-expect-error；应修正类型或添加守卫

示例

博客文章横幅插件

请求：“为 Wix Blog 文章页面创建一个展示促销横幅的插件”

**输出：**针对插槽 46035d51-2ea9-4128-a216-1dba68664ffe（博客文章页面）的插件，包含一个展示促销内容的 Card 组件，并使用 observeState() 访问博客文章数据。

预订员工日历小组件

请求：“在 Wix Bookings 员工页面添加一个展示每周可用时间的插件”

**输出：**针对插槽 261e84a2-31d0-4258-a035-10544d251108（预订员工页面）的插件，包含一个日程显示组件，并使用 observeState() 接收员工数据。

订单详情插件

请求：“在 eCommerce 订单页面上创建一个展示履行状态的插件”

**输出：**针对插槽 cb16162e-42aa-41bd-a644-dc570328c6cc（eCommerce 订单页面）的插件，包含状态徽章和履行详情，并使用 observeState() 访问订单数据。

输出约束

**令牌限制：**输出上限约为 10,000 个令牌。请规划回复内容，确保不超过此限制。

• 如果要创建大型文件（超过 300 行），请将其拆分为多个较小文件并添加导入语句
• 仅输出任务直接需要的文件
• 除非明确提出要求，否则不要添加 README.md 或文档文件