# Wix 仪表板插件生成器为 Wix CLI 应用程序创建仪表板插件扩展。仪表板插件是交互式小部件，嵌入到由 Wix 第一方业务应用程序（Wix 商店、Wix 预订、Wix 博客、Wix 电子商务等）管理的仪表板页面上的预定义**插槽**中。仪表板插件占据其插槽的整个宽度，并根据内容保持动态高度。 ** ** ## 快速入门清单创建仪表板插件时请按顺序执行以下步骤： 1. 识别目标插槽 ID — 请参阅[插槽参考]() 2. 创建插件文件夹： `src/extensions/dashboard/plugins//` 3. 使用“extensions.dashboardPlugin()”和唯一的 UUID 创建“.extension.ts” 4. 使用包含在 `WixDesignSystemProvider` 中的 React 组件创建 `.tsx` 5.更新 `src/extensions.ts` 以导入并使用新扩展 ## 架构仪表板插件通过两种机制运行： 1. **视觉集成** - 将插件 UI 嵌入支持的仪表板页面插槽中 2. **逻辑集成** — 通过`observeState()`实现插件和主页数据之间的通信 ## 文件和代码结构仪表板插件位于“src/extensions/dashboard/plugins/”下。每个插件都有自己的文件夹。 src/扩展/仪表板/插件/ └── <插件名称>/ ├── .extension.ts # 构建器配置 └── .tsx # React 组件 > **注意：** 这是 CLI 创建的默认文件夹结构。您可以将这些文件移动到“src/”文件夹中的任何位置，并更新“extension.ts”文件中的引用。 ## 插件生成器配置 ### 文件：`<插件名称>.extension.ts` 从“@wix/astro/builders”导入{扩展}；导出常量仪表板插件MyPlugin = 扩展.dashboardPlugin({ id：“{{GENERATE_UUID}}”， title: "我的仪表板插件", 扩展：“”，组件：“./extensions/dashboard/plugins/my-plugin/my-plugin.tsx”， }); **关键：UUID 生成** `id` 必须是唯一的静态 UUID v4 字符串。为每个扩展生成一个新的 UUID — 不要使用“randomUUID()”或从示例中复制 UUID。将“{{GENERATE_UUID}}”替换为新生成的 UUID，例如“a1b2c3d4-e5f6-7890-abcd-ef1234567890”。 ### 构建器字段领域|类型 |描述 ---|---|--- `id` |字符串|唯一的插件 ID (GUID)。在项目的所有扩展中必须是唯一的。 `标题` |字符串|插件标题。用于引用项目仪表板中的插件。 `延伸` |字符串|托管插件的仪表板页面的槽 ID。请参阅[插槽参考]()。 `组件` |字符串|插件内容组件的相对路径（`.tsx` 文件）。 ### `extends` 字段 “extends”字段指定哪个仪表板页面槽托管您的插件。每个 Wix 业务应用程序都会在其仪表板页面上公开插槽。您必须提供准确的插槽 ID。 **重要提示：** 某些具有相同 ID 的插槽出现在仪表板内的不同页面上。如果您为存在于多个页面上的插槽创建插件，则该插件将显示在所有这些页面上。有关可用插槽 ID 的完整列表，请参阅[插槽参考]()。 ## 插件组件 ### 文件：`<插件名称>.tsx` 插件组件是一个在仪表板页面槽中呈现的 React 组件。从“react”导入类型{FC}；从“@wix/design-system”导入 { WixDesignSystemProvider, Card, Text }; 导入“@wix/design-system/styles.global.css”； const 插件： FC = () => { 返回（ <卡片> <卡片分隔符/> 此处为插件内容。）； }; 导出默认插件； ### 插件组件中的可用资源 * **React** — 组件逻辑和状态管理 * **Wix SDK** — 访问 Wix 业务解决方案和站点数据 * **Wix Dashboard SDK** (`@wix/dashboard`) — 与传递到插槽的仪表板页面数据进行交互 * **Wix Design System** (`@wix/design-system`) — 与 Wix 自己的仪表板 UI 相匹配的原生 React 组件 ## 与仪表板数据交互使用仪表板 SDK 中的“observeState()”从主机仪表板页面接收数据：从“@wix/dashboard”导入{仪表板}；从“react”导入{useEffect，useState}； const 插件： FC = () => { const [params, setParams] = useState>({}); 使用效果（（）=> { 仪表板.observeState((componentParams) => { setParams（组件参数）； }); }, []); 返回（ <卡片> 收到的数据：{JSON.stringify(params)} ）； }; ### 来自主机应用程序的类型化 Pros 一些 Wix 应用程序为其插槽参数公开类型化接口。从应用程序的仪表板包导入它们：从“@wix/blog/dashboard”导入类型{插件}；类型 Props = plugins.BlogPosts.PostsBannerParams; const 插件: FC = (props) => { // props 根据博客帖子槽合约输入 }; > **注意：** 键入的道具可用性因 Wix 应用程序而异。请参阅特定应用程序的 SDK 文档。并非所有插槽都提供类型化参数接口。 ## 扩展注册 **扩展注册是强制性的，并且需要两个步骤。** ### 第 1 步：创建特定于插件的扩展文件每个仪表板插件在其文件夹中都需要一个“.extension.ts”文件。请参阅上面的插件生成器配置。 ### 步骤 2：在主扩展文件中注册 **关键：** 创建插件特定的扩展文件后，您必须阅读 [wix-cli-extension-registration]() 并按照“应用程序注册”部分更新 `src/extensions.ts`。 **如果不完成步骤 2，仪表板插件将不会出现在仪表板页面上。** ## 尺寸调整行为 * 仪表板插件采用其插槽的**全宽** * **高度** 根据槽边界内的内容动态调整 * 使用Dashboard SDK或dashboard-react SDK时，尺寸根据内容动态变化 ## 故障排除症状|原因 |修复 ---|---|--- 插件未出现在仪表板页面上 |缺少注册 |在`src/extensions.ts`中导入和`.use()` 插件未出现在仪表板页面上 |插槽 ID 错误 |验证“extends”字段与 [Slots Reference]() 中的有效槽 ID 匹配 ## 硬约束 * 不要发明或假定新的类型、模块、函数、道具、事件或导入 - 仅使用在提供的引用或已在本项目中使用的标准库中明确存在的实体 * 切勿在任何代码中使用模拟、占位符或 TODO - 始终实现完整的、可用于生产的功能 * `extends` 字段必须包含来自 Wix 业务应用程序的有效槽 ID — 不要发明槽 ID * 与断言相比，更喜欢类型缩小和详尽的逻辑；避免非空断言 (`!`) 和不安全的强制转换 (`as any`) * 不要使用 `// @ts-ignore` 或 `// @ts-expect-error`；修复类型或添加防护 ## 示例 ### 博客文章横幅插件 **请求：**“为 Wix 博客帖子页面创建一个显示促销横幅的插件” **输出：** 插件定位槽“46035d51-2ea9-4128-a216-1dba68664ffe”（博客文章页面），带有显示促销内容的卡片组件，使用“observeState()”访问博客文章数据。 ### 预订员工日历小部件 **请求：**“向 Wix Bookings 员工页面添加一个插件，显示每周的可用性” **输出：** 带有时间表显示组件的插件定位槽“261e84a2-31d0-4258-a035-10544d251108”（预订员工页面），使用“observeState()”接收员工数据。 ### 订单详情插件 **请求：**“在电子商务订单页面上创建一个插件，显示履行状态” **输出：** 插件定位插槽“cb16162e-42aa-41bd-a644-dc570328c6cc”（电子商务订单页面），带有状态徽章和履行详细信息，使用“observeState()”访问订单数据。 ### 输出约束 **代币限制：** 您的最大输出约为 10,000 个代币。计划你的反应以保持在这个限制之下。 * 如果创建一个大文件（>300 行），请将其拆分为多个带有导入的较小文件 * 只输出任务直接需要的文件 * 除非明确要求，否则请勿添加 README.md 或文档文件 ## 验证实现后，使用 wix-cli-app-validation 来验证 TypeScript 编译、构建、预览和运行时行为。

Wix Cli 仪表板插件

包含技能