wix-cli-dashboard-page

Wix 仪表板页面构建器

为 Wix CLI 应用创建功能完善的仪表板页面扩展。仪表板页面显示在 Wix 网站所有者的仪表板中，供网站管理员管理数据、配置设置并执行管理任务。

---

快速入门清单

创建仪表板页面时，请按顺序执行以下步骤：

1. 创建页面文件夹：src/extensions/dashboard/pages/<page-name>/
2. 创建 page.tsx，使用 WixDesignSystemProvider 包裹 WDS 组件
3. 创建 extensions.ts，使用 extensions.dashboardPage() 和唯一 UUID
4. 更新 src/extensions.ts，导入并使用新扩展

功能

数据操作（Wix Data SDK）

完整文档请参阅 Wix Data 参考。

摘要：

• 读取：items.query('Collection').filter/sort.limit.find() → { items, totalCount, hasNext }
• 写入：items.insert | update | remove。确保集合权限允许执行相应操作

查询方法： eq、ne、gt、ge、lt、le、between、contains、startsWith、endsWith、hasSome、hasAll、isEmpty、isNotEmpty、and、or、not、ascending、descending、limit、skip、include

仪表板 API

完整文档（包括所有方法、页面 ID 和示例）请参阅 仪表板 API 参考。

主要方法：

• dashboard.navigate() - 在仪表板页面之间导航
• dashboard.observeState() - 接收上下文状态和环境信息
• dashboard.showToast() - 显示 Toast 通知
• dashboard.openModal() - 打开仪表板模态扩展（参见 wix-cli-dashboard-modal）
• dashboard.navigateBack() - 返回上一页
• dashboard.getPageUrl() - 获取仪表板页面的完整 URL
• dashboard.openMediaManager() - 打开 Wix 媒体管理器
• dashboard.onBeforeUnload() - 注册 beforeunload 处理程序
• dashboard.addSitePlugin() - 将网站插件添加到插槽
• dashboard.setPageTitle() - 设置浏览器标签页中的页面标题
• dashboard.onLayerStateChange() - 处理前台／后台状态变化

重要：在仪表板页面中使用模态框

当需要从仪表板页面显示弹出表单、确认框、详情视图或任何对话框覆盖层时，必须使用仪表板模态框，而非常规 React 模态框或 WDS Modal 组件。

• 使用仪表板模态框：编辑表单、删除确认框、详情视图、设置对话框及任何弹出内容
• 不要使用 WDS Modal 组件或自定义 React 模态框实现
• 完整实现指南请参阅 wix-cli-dashboard-modal

使用 dashboard.openModal() 打开仪表板模态框，它能与仪表板生命周期、状态管理和导航正确集成。

Ecom 导航： Ecom 专用导航助手请参阅 Ecom 导航参考。

嵌入式脚本配置 API

构建用于配置嵌入式脚本的仪表板页面时，请参阅 动态参数参考 获取完整实现指南。

要点：

• 使用来自 @wix/app-management 的 embeddedScripts
• 参数以字符串形式返回，加载时请进行类型转换
• 所有参数都必须以字符串形式保存（将布尔值／数字转换为字符串）
• 存在动态参数时，请使用 withProviders 包装器

文件和代码结构

仪表板页面位于 src/extensions/dashboard/pages 下。每个页面都有自己的文件夹。

文件结构：

• src/extensions/dashboard/pages/<page>/page.tsx — 页面组件

关键元数据字段：

• id（字符串，GUID）：用于注册页面的唯一页面 ID
• title（字符串）：用于浏览器标签页和可选的侧边栏标签
• additionalRoutes（字符串数组，可选）：指向此页面的额外路由
• sidebar.disabled（布尔值，可选）：从侧边栏中隐藏页面（默认值为 false）
• sidebar.priority（数字，可选）：侧边栏排序；数值越小，优先级越高
• sidebar.whenActive.selectedPageId（字符串，可选）：此页面处于活动状态时，哪个页面显示为选中状态
• sidebar.whenActive.hideSidebar（布尔值，可选）：此页面处于活动状态时隐藏侧边栏

WDS Provider 用法

使用 WixDesignSystemProvider 包裹仪表板页面组件，以启用 WDS 组件和主题。还必须导入全局 CSS 样式，才能正确渲染 WDS 组件。

import { WixDesignSystemProvider } from "@wix/design-system";
import '@wix/design-system/styles.global.css';

export default function () {
  return (
    <WixDesignSystemProvider>
      <Page>
        <Page.Header
          title="My Page"
          subtitle="This is a subtitle for your page"
        />
        <Page.Content>
          <EmptyState title="My Page" subtitle="Hello World!" theme="page" />
        </Page.Content>
      </Page>
    </WixDesignSystemProvider>
  );
}

注意： 使用动态参数时，请改用 withProviders 包装器。详情请参阅动态参数。

严格限制

• 不要虚构或假设新的类型、模块、函数、属性、事件或导入。
• 仅使用所提供的参考资料中明确列出的实体，或此项目已使用的标准库。
• 如果缺少某项内容，请明确指出，并提供最精简的 TODO 或标注明确的占位内容，而不是自行创建。
• 使用组件前，务必确认该组件可用。
• 如果列表中没有所需组件，请使用基本 HTML 元素或创建简单的自定义组件。
• 不要使用 WDS Modal 组件或自定义 React 模态框实现——对于任何弹出对话框、表单或叠加层，始终使用仪表板模态框（参见 wix-cli-dashboard-modal）。

示例

数据管理表格

请求：“创建一个用于管理博客文章的仪表板页面”

**输出：**包含文章列表、搜索工具栏、添加／编辑／删除操作和空状态的页面。

设置表单

请求：“为通知偏好设置构建一个设置页面”

**输出：**包含表单字段、带 Toast 确认提示的保存按钮，以及未保存更改警告的页面。

订单管理

请求：“为客户订单创建一个管理面板”

**输出：**包含订单表格、状态徽章、筛选器、详情仪表板模态框（使用 wix-cli-dashboard-modal）和状态更新操作的页面。

嵌入式脚本配置

请求：“为优惠券弹出窗口嵌入式脚本创建一个设置页面”

**输出：**包含弹出窗口标题、优惠券代码、最低购物车金额和启用开关等表单字段的页面。使用 embeddedScripts API 加载／保存参数。

// Key pattern for embedded script configuration pages
import { embeddedScripts } from "@wix/app-management";

// Load on mount
useEffect(() => {
  const load = async () => {
    const script = await embeddedScripts.getEmbeddedScript();
    const data = script.parameters || {};
    setOptions({
      headline: data.headline || "Default",
      enabled: data.enabled === "true",
      threshold: Number(data.threshold) || 0,
    });
  };
  load();
}, []);

// Save handler
const handleSave = async () => {
  await embeddedScripts.embedScript({
    parameters: {
      headline: options.headline,
      enabled: String(options.enabled),
      threshold: String(options.threshold),
    },
  });
  dashboard.showToast({ message: "Saved!", type: "success" });
};

扩展注册

扩展注册是必需的，且必须完成两个步骤。

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

每个仪表盘页面都需要在其文件夹中包含一个 extensions.ts 文件：

文件： src/extensions/dashboard/pages/<page-name>/extensions.ts

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

export const dashboardpageMyPage = extensions.dashboardPage({
  id: "{{GENERATE_UUID}}",
  title: "My Page",
  routePath: "my-page",
  component: "./extensions/dashboard/pages/my-page/page.tsx",
});

重要：UUID 生成

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

属性	类型	说明
id	string	唯一的静态 UUID v4（生成新的 UUID，参见上方说明）
title	string	在仪表盘侧边栏中显示的标题
routePath	string	URL 路径段。只能包含小写字母、数字、连字符和斜杠。不得以斜杠开头。
component	string	页面组件（.tsx）的相对路径

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

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

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

常见错误——请勿这样做

与其他扩展类型的 API 混淆：

错误（嵌入式脚本 API）	正确（仪表盘页面 API）
name: "..."	title: "..."
source: "..."	component: "..."
route: "..."	routePath: "..."

不要从嵌入式脚本或其他扩展注册中复制字段名。仪表盘页面使用 title、routePath 和 component。

代码质量要求

TypeScript 质量指南

• 生成的代码在严格设置下必须编译通过，且不得有任何 TypeScript 错误：strict、noImplicitAny、strictNullChecks、exactOptionalPropertyTypes、noUncheckedIndexedAccess
• 优先使用类型收窄和穷尽逻辑，而非类型断言；避免非空断言（!）和不安全的类型转换（as any）
• 将可选值、引用和数组索引结果视为可能为 undefined，并显式处理
• 对联合类型使用穷尽检查（例如，使用 never 检查的 switch），并返回完整的值（不得隐式返回 undefined）
• 不要使用 // @ts-ignore 或 // @ts-expect-error；应修正类型或添加保护条件

核心原则

• 不要臆造或假定新的类型、模块、函数、属性、事件或导入
• 绝不在任何代码中使用模拟对象、占位符或 TODO
• 始终实现完整且可用于生产环境的功能
• 严格遵循 Wix 仪表盘页面模式和最佳实践
• 妥善处理所有边缘情况和错误场景

代码质量标准

• 优先使用带有适当类型的 TypeScript
• 使用一致的命名约定
• 在适当的位置添加错误处理
• 为复杂或不明显的逻辑添加文档说明
• 异步操作优先使用 async/await
• 在有助于提升代码清晰度时考虑使用解构
• 返回结构良好的响应对象

错误处理

• 始终在仪表盘页面中实现适当的错误处理
• 当数据无效时返回适当的错误响应
• 使用 console.error 记录错误，以便调试
• 处理网络超时和外部服务故障

输出约束

Token 限制： 最大输出约为 10,000 个 token。你必须规划回复，确保远低于此限制。

• 如果文件较大（超过 300 行），请拆分成多个较小的文件，并使用导入语句。
• 如果要编辑较大的部分（超过 100 行），请将其拆分为多个较小的编辑操作。
• 回复前请统计输出长度；如果看起来太长，请缩小范围并优先处理重点。

简洁规则： 在保证质量和准确性的前提下，尽量减少输出 token。

• 除非明确要求，否则不要添加 README.md、文档文件或 Markdown 文件。
• 不要在代码中添加过多注释；仅在确实有助于理解时添加注释。
• 不要重新输出未更改的文件，也不要重复现有代码。
• 不要生成类似 "// TODO: implement" 的占位代码；请提供可用的实现。
• 仅输出任务直接需要的文件。

模块化代码策略： 编写大量代码时，请拆分为多个较小的文件，并使用导入语句：

• 将实用工具／辅助函数提取到单独的文件中
• 将类型／接口单独放入专用的类型文件
• 让每个组件／函数职责清晰（每个约 50–100 行）

API 规范支持

提供 API 规范时，你可以调用其中的端点。有关如何在仪表板页面中使用 API 规范的详情，请参阅 API Spec Reference。

---

布局指南

布局决定用户如何与仪表板内容交互。它构建仪表板页面的结构、层次和节奏，有助于提升整体一致性和用户体验。通过有意识地、审慎地安排内容，用户可以更顺畅地浏览页面，在完成任务时节省时间并减少挫败感。

设计原则

为了打造优化用户体验的仪表板页面，请遵循以下设计原则：

1. 一致： 保持布局和内容模式的重复一致，让页面直观易读。
2. 包容： 创建能够良好适配各种屏幕尺寸的布局和内容。
3. 均衡： 通过有意控制尺寸和留白，突出各个区域和内容元素的优先级。
4. 关联： 缩短相关区域或内容元素之间的距离，以增强整体连贯性并便于导航。

---

屏幕尺寸

仪表板页面旨在适配各种屏幕尺寸，而非针对某个特定分辨率进行设计。主要内容应置于页面顶部，确保用户能够立即了解页面用途。

注意： 页面顶部 600 像素内显示的内容，大多数用户都能看到。

---

基准单位

基准单位规定了所有元素和尺寸的倍数。采用这种做法可以确保设计元素的间距和尺寸保持一致。

注意： 设计系统以 6px 为单位。

布局网格、间距 token，以及几乎所有视觉元素和尺寸都遵循 6 的倍数（6、12、18、24 等），仅偶尔例外。

TOKEN	SIZE	USE FOR
SP1	6px	组件之间的间距
SP2	12px	组件之间的间距
SP3	18px	组件之间的间距
SP4	24px	组件之间的间距、布局间距
SP5	30px	布局间距
SP6	36px	布局间距
SP7	42px	布局间距
SP8	48px	布局间距
SP10	54px	布局间距
SP11	60px	布局间距

---

布局结构

要为应用设计出最佳布局，请了解以下内容：

1. 应用的核心框架（应用框架）
2. 网格布局中各个部分的位置和对齐方式（网格布局）
3. 网格中要显示的内容（常见布局）

应用框架

大多数 Wix 应用的设置都使用此仪表板应用框架。仪表板页面由 4 个区域组成：

区域	用途
1. 全局导航（顶部栏）	页面顶部的常规导航，可让用户在不同环境之间切换。全宽容器，固定高度为 48px。
2. 侧边栏导航	环境内的本地导航。容器固定宽度为 228px。
3. 内容区域	页面内容区域，宽度可根据屏幕尺寸自适应。
4. 侧面板（可选）	可选面板，用于显示与页面内容相关的其他操作或内容。固定宽度为 420px。可覆盖主内容区域，也可从右侧推开主内容区域。

侧面板指南：

• 当侧面板包含辅助操作或设置（例如数据筛选器）时，让侧面板覆盖主内容
• 当用户必须查看完整上下文才能继续操作时，让侧面板推开主内容

---

网格布局

系统采用流式网格布局，并设有固定的最大宽度。网格使用可缩放的列，以相应调整内容。

网格由 3 个元素构成：

• 列 - 设计系统使用 12 列网格。列宽为流式，会随页面宽度变化。
• 间距 - 列之间的间隙。间距宽度固定为 24px。
• 边距 - 默认情况下，页面内容区域左右边距为 48px，底部边距为 48px。

网格规格：

• 内容区域最小宽度：864 像素（每列网格宽 50px）
• 内容区域最大宽度：1248px（每列宽 82px）
• 在更宽的屏幕上，内容宽度保持为 1248px，侧边距则延伸以使内容居中
• 卡片之间的垂直和水平间距均为 24px

---

常见布局

页面布局可按用途分为以下类型：

1. 表单布局

表单页面用于让用户填写数据或编辑现有数据。有两种形式：

• 2/3 布局，带可选侧边栏（8/4 列划分） - 灵活地同时展示主要内容和次要内容
• 全宽（12 列） - 支持具有复杂结构的高级产品需求

两种表单页面布局的页眉和页脚区域都必须包含 保存 和 取消 操作。

2/3 布局最佳实践：

• 用于同时展示主要内容和次要内容
• 让表单便于浏览和理解
• 在侧面显示实时内容预览（小组件可以设为粘性定位）
• 表单使用 8 列，让文本行和输入字段保持较窄，以便更快阅读
• 将操作放在相关标题附近（例如，将切换开关放在设置旁边）

全宽布局最佳实践：

• 表单包含表格等复杂结构时使用
• 用于包含多个数据列的列表项

组合布局：

• 避免输入框横跨整个页面；将输入框限制在卡片宽度的 2/3，或将其分为两列排列
• 利用右侧的留白显示内容预览
• 对于包含多列的表格，使用全宽布局，并用分隔线区分各个部分

注意： 如果一列的宽度足以容纳每行平均 10 个词，就容易阅读。

2. 展示布局

展示页面用于呈现数据或内容，不接受用户输入。可以包含数据筛选等轻量操作。

列表（表格）：

• 表格用于展示大量数据，并帮助用户快速概览
• 表格采用 12 列布局
• 允许用户操作和处理数据集

列表（网格）选项：

• 2 列（6/6 分栏）——适用于描述较长的项目
• 3 列（4/4/4 分栏）——适用于包含多种数据类型的视觉内容
• 4 列（3/3/3/3 分栏）——适用于用户生成的图库和集合，与 4/4/4 布局相比，首屏可多展示至多 50% 的内容
• 自定义——适用于混合内容需求

选择网格时的考量：

• 要展示的项目总数
• 每个列表项中要展示的内容
• 列表项所代表的对象（适用时应匹配实际形状）

仪表板： 使用组合网格，围绕特定主题展示不同类型的数据。

列跨度建议：

• 3 或 4 列——适用于列表项、预览、营销内容、统计数据和图表
• 12 列（全宽）——适用于表格和营销内容
• 8 列——适用于列表、数据列较少的表格、设置向导和图表
• 6 列——适用于列表、数据列较少的表格和统计数据

空状态：

• 页面空状态使用全宽布局
• 表示功能或产品尚无数据、所有数据已清除或尚未设置
• 添加明确的 CTA，说明如何填充页面
• 可与标签页、统计信息组件或营销卡片等其他布局元素组合使用

3. 营销布局

营销页面用于推广网站所有者尚不了解的新产品。使用 <MarketingPageLayout/> 组件构建，分为 2 列：

1. 宣传信息
2. 产品及其功能的视觉呈现

可选的页脚区域可展示功能或评价列表。

4. 向导布局

向导页面引导用户设置产品或功能。它将复杂表单拆分为多个步骤，方便用户完成。

入口：

• 营销页面
• 营销卡片
• 页面的主要操作
• 空状态

**注意：**向导必须设有最终目的地。完成所有步骤后，用户应进入相关页面，例如仪表板、详情页面或其他相关位置。

---

相关 WDS 组件

• <Page /> - 主页面包装器
• <Layout /> - 网格布局容器
• <MarketingPageLayout /> - 营销页面包装器
• <Card /> - 内容容器，卡片之间间距为 24px