wix-cli-dashboard-page

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Wix Dashboard Page Builder

Wix 仪表盘页面构建器

Creates full-featured dashboard page extensions for Wix CLI applications. Dashboard pages appear in the Wix site owner's dashboard and enable site administrators to manage data, configure settings, and perform administrative tasks.

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

Quick Start Checklist

快速开始检查清单

Follow these steps in order when creating a dashboard page:

Create page folder:
```
src/dashboard/pages/<page-name>/
```
Create
```
page.tsx
```
with WDS components wrapped in
```
WixDesignSystemProvider
```
Create
```
extensions.ts
```
with
```
extensions.dashboardPage()
```
and unique UUID
Update
```
src/extensions.ts
```
to import and use the new extension

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

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

Capabilities

功能特性

Data Operations (Wix Data SDK)

数据操作（Wix Data SDK）

See Wix Data Reference for complete documentation.

Summary:

Read:

items.query('Collection').filter/sort.limit.find()

→

{ items, totalCount, hasNext }

Write:
```
items.insert | update | remove
```
. Ensure collection permissions allow the action

Query methods:

eq

ne

gt

ge

lt

le

between

contains

startsWith

endsWith

hasSome

hasAll

isEmpty

isNotEmpty

and

or

not

ascending

descending

limit

skip

include

完整文档请查看 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

Dashboard APIs

仪表盘 API

See Dashboard API Reference for complete documentation including all methods, page IDs, and examples.

Key methods:

```
dashboard.navigate()
```
- Navigate between dashboard pages
```
dashboard.observeState()
```
- Receive contextual state and environmental information
```
dashboard.showToast()
```
- Display toast notifications
```
dashboard.openModal()
```
- Open dashboard modal extensions (see wix-cli-dashboard-modal)
```
dashboard.navigateBack()
```
- Navigate back to previous page
```
dashboard.getPageUrl()
```
- Get full URL for a dashboard page
```
dashboard.openMediaManager()
```
- Open Wix Media Manager
```
dashboard.onBeforeUnload()
```
- Register beforeunload handler
```
dashboard.addSitePlugin()
```
- Add site plugin to slots
```
dashboard.setPageTitle()
```
- Set page title in browser tab
```
dashboard.onLayerStateChange()
```
- Handle foreground/background state changes

CRITICAL: Using Modals in Dashboard Pages

When you need to display popup forms, confirmations, detail views, or any dialog overlays from a dashboard page, you MUST use dashboard modals, not regular React modals or WDS Modal components.

Use dashboard modals for: edit forms, delete confirmations, detail views, settings dialogs, any popup content
Do NOT use WDS
```
Modal
```
component or custom React modal implementations
See wix-cli-dashboard-modal for complete implementation guide

Dashboard modals are opened using

dashboard.openModal()

and provide proper integration with the dashboard lifecycle, state management, and navigation.

Ecom Navigation: See Ecom Navigation Reference for ecom-specific navigation helpers.

完整文档（包含所有方法、页面ID和示例）请查看仪表盘 API 参考。

核心方法：

```
dashboard.navigate()
```
- 在仪表盘页面之间导航
```
dashboard.observeState()
```
- 接收上下文状态和环境信息
```
dashboard.showToast()
```
- 显示提示通知
```
dashboard.openModal()
```
- 打开仪表盘模态扩展（查看 wix-cli-dashboard-modal）
```
dashboard.navigateBack()
```
- 返回上一页
```
dashboard.getPageUrl()
```
- 获取仪表盘页面的完整URL
```
dashboard.openMediaManager()
```
- 打开 Wix 媒体管理器
```
dashboard.onBeforeUnload()
```
- 注册页面卸载前的处理函数
```
dashboard.addSitePlugin()
```
- 向插槽添加站点插件
```
dashboard.setPageTitle()
```
- 设置浏览器标签页中的页面标题
```
dashboard.onLayerStateChange()
```
- 处理前台/后台状态变更

重要提示：在仪表盘页面中使用模态框

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

使用仪表盘模态框 场景：编辑表单、删除确认、详情视图、设置对话框、任何弹出内容
禁止使用 WDS
```
Modal
```
组件或自定义 React 模态框实现
查看 wix-cli-dashboard-modal 获取完整实现指南

仪表盘模态框通过

dashboard.openModal()

打开，可与仪表盘生命周期、状态管理和导航进行正确集成。

电商导航： 电商专属导航工具请查看电商导航参考。

Embedded Script Configuration API

嵌入式脚本配置 API

When building a dashboard page to configure an embedded script, see Dynamic Parameters Reference for complete implementation guide.

Key points:

Use
```
embeddedScripts
```
from
```
@wix/app-management
```
Parameters are returned as strings - handle type conversions when loading
All parameters must be saved as strings (convert booleans/numbers to strings)
Use
```
withProviders
```
wrapper when dynamic parameters are present

当构建用于配置嵌入式脚本的仪表盘页面时，完整实现指南请查看动态参数参考。

核心要点：

使用
```
@wix/app-management
```
中的
```
embeddedScripts
```
参数以字符串形式返回 - 加载时需处理类型转换
所有参数必须以字符串形式保存（将布尔值/数字转换为字符串）
当存在动态参数时，使用
```
withProviders
```
包装器

Files and Code Structure

文件与代码结构

Dashboard pages live under

src/dashboard/pages

. Each page has its own folder.

File structure:

```
src/dashboard/pages/<page>/page.tsx
```
— page component

Key metadata fields:

```
id
```
(string, GUID): Unique page ID used to register the page
```
title
```
(string): Used for browser tab and optional sidebar label
```
additionalRoutes
```
(string[], optional): Extra routes leading to this page
```
sidebar.disabled
```
(boolean, optional): Hide page from sidebar (default false)
```
sidebar.priority
```
(number, optional): Sidebar ordering; lower is higher priority
```
sidebar.whenActive.selectedPageId
```
(string, optional): Which page appears selected when this page is active
```
sidebar.whenActive.hideSidebar
```
(boolean, optional): Hide sidebar when this page is active

仪表盘页面位于

src/dashboard/pages

目录下，每个页面拥有独立文件夹。

文件结构：

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

核心元数据字段：

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

WDS Provider Usage

WDS Provider 使用方法

Wrap your dashboard page component with

WixDesignSystemProvider

to enable WDS components and theming. You must also import the global CSS styles for WDS components to render correctly.

typescript

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

Note: When using dynamic parameters, use the

withProviders

wrapper instead. See Dynamic Parameters for details.

使用

WixDesignSystemProvider

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

typescript

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

包装器。详情请查看动态参数。

Hard Constraints

硬性约束

Do NOT invent or assume new types, modules, functions, props, events, or imports.
Use only entities explicitly present in the provided references or standard libraries already used in this project.
If something is missing, call it out explicitly and provide a minimal TODO or clearly marked placeholder rather than creating it.
Always verify component availability before using it in your generated code
If you need a component not in the list, use a basic HTML element or create a simple custom component instead
Do NOT use WDS
Modal
component or custom React modal implementations - Always use dashboard modals (see wix-cli-dashboard-modal) for any popup dialogs, forms, or overlays

不得发明或假设新的类型、模块、函数、属性、事件或导入项。
仅使用提供的参考文档中明确列出的实体，或项目中已使用的标准库。
若缺少内容，请明确指出，并提供最小化的 TODO 或清晰标记的占位符，而非自行创建。
在生成代码中使用组件前，务必验证组件是否可用
若需要的组件未在列表中，请使用基础 HTML 元素或创建简单的自定义组件
禁止使用 WDS
```
Modal
```
组件或自定义 React 模态框实现 - 任何弹出对话框、表单或覆盖层都必须使用仪表盘模态框（查看 wix-cli-dashboard-modal）

Examples

示例

Data Management Table

数据管理表格

Request: "Create a dashboard page to manage blog posts"

Output: Page with table displaying posts, search toolbar, add/edit/delete actions, empty state.

需求： "创建一个用于管理博客文章的仪表盘页面"

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

Settings Form

设置表单

Request: "Build a settings page for notification preferences"

Output: Page with form fields, save button with toast confirmation, unsaved changes warning.

需求： "构建一个通知偏好设置页面"

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

Order Management

订单管理

Request: "Create an admin panel for customer orders"

Output: Page with orders table, status badges, filters, detail dashboard modal (using wix-cli-dashboard-modal), status update actions.

需求： "创建一个客户订单管理面板"

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

Embedded Script Configuration

嵌入式脚本配置

Request: "Create a settings page for the coupon popup embedded script"

Output: Page with form fields for popup headline, coupon code, minimum cart value, and enable toggle. Uses

embeddedScripts

API to load/save parameters.

typescript

// 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" });
};

需求： "创建一个优惠券弹出嵌入式脚本的设置页面"

输出： 包含弹出标题、优惠券代码、最低购物金额、启用开关等表单字段的页面。使用

embeddedScripts

API 加载/保存参数。

typescript

// 嵌入式脚本配置页面的核心模式
import { embeddedScripts } from "@wix/app-management";

// 挂载时加载
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();
}, []);

// 保存处理函数
const handleSave = async () => {
  await embeddedScripts.embedScript({
    parameters: {
      headline: options.headline,
      enabled: String(options.enabled),
      threshold: String(options.threshold),
    },
  });
  dashboard.showToast({ message: "Saved!", type: "success" });
};

Extension Registration

扩展注册

Extension registration is MANDATORY and has TWO required steps.

扩展注册是强制性的，包含两个必填步骤。

Step 1: Create Page-Specific Extension File

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

Each dashboard page requires an

extensions.ts

file in its folder:

File:

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

typescript

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

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

CRITICAL: UUID Generation

The

id

must be a unique, static UUID v4 string. Generate a fresh UUID for each extension - do NOT use

randomUUID()

or copy UUIDs from examples. Replace

{{GENERATE_UUID}}

with a freshly generated UUID like

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Property	Type	Description
`id`	string	Unique static UUID v4 (generate fresh - see note above)
`title`	string	Display title in dashboard sidebar
`routePath`	string	URL path segment. Lowercase letters, numbers, dashes, and slashes only. Must NOT start with a slash.
`component`	string	Relative path to the page component (.tsx)

每个仪表盘页面在其文件夹中都需要一个

extensions.ts

文件：

文件：

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

typescript

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

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

重要提示：UUID 生成

id

必须是唯一的静态 UUID v4 字符串。为每个扩展生成新的 UUID - 请勿使用

randomUUID()

或复制示例中的 UUID。将

{{GENERATE_UUID}}

替换为新生成的 UUID，例如

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

。

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

Step 2: Register in Main Extensions File

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

CRITICAL: After creating the page-specific extension file, you MUST read wix-cli-extension-registration and follow the "App Registration" section to update

src/extensions.ts

Without completing Step 2, the dashboard page will not appear in the Wix dashboard.

重要提示： 创建页面专属扩展文件后，必须阅读 wix-cli-extension-registration 并按照「应用注册」部分的说明更新

src/extensions.ts

。

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

Common Mistakes - Do NOT

常见错误 - 请勿

API confusion with other extension types:

WRONG (Embedded Script API)	CORRECT (Dashboard Page API)
`name: "..."`	`title: "..."`
`source: "..."`	`component: "..."`
`route: "..."`	`routePath: "..."`

Do NOT copy field names from embedded script or other extension registrations. Dashboard pages use

title

routePath

, and

component

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

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

请勿复制嵌入式脚本或其他扩展注册中的字段名称。仪表盘页面使用

title

、

routePath

和

component

。

Code Quality Requirements

代码质量要求

TypeScript Quality Guidelines

TypeScript 质量指南

Generated code MUST compile with zero TypeScript errors under strict settings: strict, noImplicitAny, strictNullChecks, exactOptionalPropertyTypes, noUncheckedIndexedAccess
Prefer type-narrowing and exhaustive logic over assertions; avoid non-null assertions (!) and unsafe casts (as any)
Treat optional values, refs, and array indexing results as possibly undefined and handle them explicitly
Use exhaustive checks for unions (e.g., switch with a never check) and return total values (no implicit undefined)
Do NOT use // @ts-ignore or // @ts-expect-error; fix the types or add guards instead

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

Core Principles

核心原则

Do NOT invent or assume new types, modules, functions, props, events, or imports
NEVER use mocks, placeholders, or TODOs in any code
ALWAYS implement complete, production-ready functionality
Follow Wix dashboard page patterns and best practices precisely
Handle all edge cases and error scenarios appropriately

不得发明或假设新的类型、模块、函数、属性、事件或导入项
任何代码中都不得使用模拟、占位符或 TODO
始终实现完整的、可用于生产环境的功能
严格遵循 Wix 仪表盘页面模式和最佳实践
适当处理所有边缘情况和错误场景

Code Quality Standards

代码质量标准

Prefer TypeScript with appropriate typing
Use consistent naming conventions
Include error handling where appropriate
Add documentation for complex or non-obvious logic
Prefer async/await for asynchronous operations
Consider destructuring for cleaner code when beneficial
Return well-structured response objects

优先使用 TypeScript 并配置适当的类型
使用一致的命名规范
在适当的位置包含错误处理
为复杂或不明显的逻辑添加文档
异步操作优先使用 async/await
若有益处，可使用解构简化代码
返回结构清晰的响应对象

Error Handling

错误处理

Always implement proper error handling in dashboard pages
Return appropriate error responses when data is invalid
Log errors appropriately for debugging using console.error
Handle network timeouts and external service failures

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

Output Constraints

输出约束

Token limits: Your max output is ~10,000 tokens. You MUST plan your response to stay well under this limit.

If making a large file (>300 lines), split it into multiple smaller files with imports.
If editing a large section (>100 lines), break it into multiple smaller edit operations.
Count your output before responding - if it seems too long, reduce scope and prioritize.

Brevity rules: Minimize output tokens while maintaining quality and correctness.

Do NOT add README.md, documentation files, or markdown files unless explicitly requested.
Do NOT add excessive comments in code - only add comments where truly necessary for clarity.
Do NOT re-output unchanged files or duplicate existing code.
Do NOT generate placeholder code like "// TODO: implement" - provide working implementations.
Only output files that are directly required for the task.

Modular code strategy: When generating substantial code, split into multiple smaller files with imports:

Extract utilities/helpers into separate files
Separate types/interfaces into dedicated type files
Keep each component/function focused (~50-100 lines max)

令牌限制： 最大输出约为 10,000 个令牌。必须规划响应内容，确保远低于此限制。

若生成大文件（>300 行），请拆分为多个带导入的小文件。
若编辑大段内容（>100 行），请拆分为多个小的编辑操作。
响应前先估算输出长度 - 若过长，请缩小范围并优先处理核心内容。

简洁规则： 在保持质量和正确性的前提下，尽量减少输出令牌数量。

除非明确要求，否则请勿添加 README.md、文档文件或 Markdown 文件。
代码中请勿添加过多注释 - 仅在确实需要提升清晰度时添加。
请勿重复输出未更改的文件或现有代码。
请勿生成占位符代码如 "// TODO: implement" - 请提供可运行的实现。
仅输出任务直接需要的文件。

模块化代码策略： 生成大量代码时，拆分为多个带导入的小文件：

将工具/辅助函数提取到单独文件
将类型/接口分离到专用的类型文件
保持每个组件/函数的专注性（最多约 50-100 行）

Verification

验证

After implementation completes, the wix-cli-orchestrator will run validation using wix-cli-app-validation.

实现完成后，wix-cli-orchestrator 将使用 wix-cli-app-validation 运行验证。

API Spec Support

API 规范支持

When an API specification is provided, you can make API calls to those endpoints. See API Spec Reference for details on how to use API specs in dashboard pages.

若提供了 API 规范，则可以调用这些端点。仪表盘页面中如何使用 API 规范请查看 API 规范参考。

Layout Guidelines

布局指南

Layout determines how users interact with your dashboard content. It establishes the structure, hierarchy, and rhythm of your dashboard page, contributing to the overall coherence and user experience. By making mindful and calculated choices in how you organize your content, users can move around more smoothly, saving time and frustration when completing tasks.

布局决定了用户与仪表盘内容的交互方式。它建立了仪表盘页面的结构、层级和节奏，有助于提升整体一致性和用户体验。通过谨慎、合理地组织内容，用户可以更顺畅地操作，完成任务时节省时间并减少挫败感。

Design Principles

设计原则

To create dashboard pages optimized for user experience, follow these design principles:

Consistent: Maintain repetitive layouts and content patterns for intuitive and easy-to-read pages.
Inclusive: Create layouts and content that adapt well to various screen sizes.
Balanced: Emphasize the priority of regions and content elements through deliberate management of size and white space.
Connected: Minimize the distance between related regions or content elements to enhance cohesion and navigation.

为创建优化用户体验的仪表盘页面，请遵循以下设计原则：

一致性： 保持重复的布局和内容模式，使页面直观且易于阅读。
包容性： 创建能适应各种屏幕尺寸的布局和内容。
平衡性： 通过刻意管理尺寸和留白，突出区域和内容元素的优先级。
关联性： 最小化相关区域或内容元素之间的距离，增强连贯性和导航性。

Screen Size

屏幕尺寸

Dashboard pages are designed to accommodate various screen sizes rather than being tailored to one specific resolution. The primary content should be at the top of the page to ensure users immediately understand the purpose of the page.

Note: Content displayed in the top 600 pixels of the page will be visible for the majority of users.

仪表盘页面旨在适应各种屏幕尺寸，而非针对特定分辨率。主要内容应位于页面顶部，确保用户能立即理解页面用途。

注意： 页面顶部 600 像素内的内容将被大多数用户看到。

Base Unit

基础单位

The base unit establishes the increment by which all elements and measurements are multiplied. This practice ensures consistency in the spacing and sizing of design elements.

Note: The design system is based on a 6px unit.

The layout grid, spacing tokens, and nearly all visual elements and sizes adhere to multiples of six (6, 12, 18, 24, etc.), with only occasional exceptions.

TOKEN	SIZE	USE FOR
SP1	6px	Spacing between components
SP2	12px	Spacing between components
SP3	18px	Spacing between components
SP4	24px	Spacing between components, layout spacing
SP5	30px	Layout spacing
SP6	36px	Layout spacing
SP7	42px	Layout spacing
SP8	48px	Layout spacing
SP10	54px	Layout spacing
SP11	60px	Layout spacing

基础单位确定了所有元素和测量值的增量倍数。此做法确保设计元素的间距和尺寸保持一致。

注意： 该设计系统基于 6px 单位。

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

令牌	尺寸	用途
SP1	6px	组件间间距
SP2	12px	组件间间距
SP3	18px	组件间间距
SP4	24px	组件间间距、布局间距
SP5	30px	布局间距
SP6	36px	布局间距
SP7	42px	布局间距
SP8	48px	布局间距
SP10	54px	布局间距
SP11	60px	布局间距

Layout Structure

布局结构

To best design the layout for your app, understand:

The core frame of the app (Application frame)
The placement and alignment of each segment within the grid layout (Grid layout)
The content to appear in the grid (Common layouts)

要为应用设计最佳布局，请了解：

应用的核心框架（Application frame）
网格布局中每个部分的位置和对齐方式（Grid layout）
网格中显示的内容（Common layouts）

Application Frame

应用框架

The dashboard app frame is used by the majority of Wix applications settings. Dashboard pages consist of 4 areas:

AREA	USAGE
1. Global navigation (top bar)	General navigation at the top of a page which allows users to navigate between different environments. Full width container with a fixed height of 48px.
2. Sidebar navigation	Local navigation of an environment. Container with a fixed width of 228px.
3. Content area	Page content area with a width that's adaptive to screen size.
4. Side panel (optional)	An optional panel that shows additional actions or content associated with the content of a page. Fixed width of 420px. Can either overlay the main content area or push it from the right side.

Side Panel Guidelines:

Let the side panel overlay main content when it contains supplementary actions or settings, such as data filters
Push main content with the side panel when users must see the full context to continue

仪表盘应用框架被大多数 Wix 应用设置所使用。仪表盘页面包含 4 个区域：

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

侧边面板指南：

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

Grid Layout

网格布局

The system uses a fluid grid layout with a fixed maximum width. It uses columns that scale and resize the content accordingly.

The grid is constructed from 3 elements:

Columns - The design system uses a 12-column grid. Column width is fluid and changes according to the page width.
Gutters - The gaps between the columns. Gutter width has a fixed value of 24px.
Margins - By default, a page's content area has 48px side margins and a 48px bottom margin.

Grid Specifications:

Minimum content area width: 864 pixels (each grid column is 50px wide)
Maximum content area width: 1248px (each column is 82px wide)
Wider screens maintain 1248px content width with side margins stretching to center content
Use 24px gap between cards both vertically and horizontally

该系统使用具有固定最大宽度的流式网格布局。它使用可缩放的列来调整内容大小。

网格由 3 个元素构成：

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

网格规格：

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

Common Layouts

常见布局

Page layouts can be divided by intention into the following types:

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

1. Form Layouts

1. 表单布局

Forms are pages that allow users to fill in data or edit existing data. Two variations:

2/3 layout with optional sidebar (8/4 column split) - Provides flexibility to expose primary and secondary content at the same time
Full width (12 columns) - Supports advanced product needs with complex structures

Both form page layouts include mandatory Save and Cancel actions in the header and footer areas.

2/3 Layout Best Practices:

Use to expose primary and secondary content at the same time
Keep the form easy to scan and comprehend
Display a live content preview on the side (widget can be sticky)
Use 8 columns for forms to keep text lines and input fields narrow for quicker reading
Bring actions closer to related titles (e.g., toggle switches near settings)

Full Width Layout Best Practices:

Use when a form includes complex structures such as tables
Use for list items that contain many data columns

Combining Layouts:

Avoid coast-to-coast inputs; keep inputs to 2/3 width of a card, or lay them out in two columns
Use white space on the right side for content preview
Use full width for tables with many columns and dividers that separate sections

Note: A column is easy to read if it is wide enough to accommodate an average of 10 words per line.

表单页面允许用户填写数据或编辑现有数据。有两种变体：

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

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

2/3 布局最佳实践：

用于同时展示主要和次要内容
保持表单易于浏览和理解
在侧边显示实时内容预览（小部件可设为粘性）
使用 8 列布局放置表单，使文本行和输入字段更窄，便于快速阅读
将操作按钮放在相关标题附近（例如，开关控件靠近设置项）

全宽布局最佳实践：

当表单包含复杂结构（如表）时使用
用于包含多列数据的列表项

布局组合：

避免跨整行的输入框；将输入框限制为卡片宽度的 2/3，或分为两列布局
在右侧留白区域放置内容预览
多列表格和分隔内容的分区使用全宽布局

注意： 若列宽足够容纳每行平均 10 个单词，则该列易于阅读。

2. Display Layouts

2. 展示布局

Display pages showcase data or content without accepting input from users. They can contain minor actions such as data filtering.

List (Table):

Tables display large data sets and provide users with a quick overview
Use a 12-column layout for tables
Enables users to manipulate and act on a data set

List (Grid) Options:

2 columns (6/6 split) - For items with lengthy descriptions
3 columns (4/4/4 split) - For visual items with multiple data types
4 columns (3/3/3/3 split) - For user-generated galleries and collections, reveals up to 50% more content above the fold than 4/4/4
Custom - For mixed content needs

Grid Selection Considerations:

Total amount of items to show
Content to display in each list item
What objects the list items reflect (match physical shapes when applicable)

Dashboards: Display different types of data on a specific topic using a combination grid.

Column span recommendations:

3 or 4 columns - For list items, previews, marketing, statistics, and charts
12 columns (full width) - For tables and marketing content
8 columns - For lists, tables with few data columns, setup wizards, and charts
6 columns - For lists, tables with few data columns, and statistics

Empty States:

Use full width layout for empty state of a page
Indicates feature/product has no data yet, all data cleared, or not set up yet
Include clear CTA indicating what to do to fill the page
Can combine with other layout elements such as tabs, statistics widgets, or marketing cards

展示页面用于展示数据或内容，不接受用户输入。可包含数据筛选等次要操作。

列表（表格）：

表格用于展示大型数据集，为用户提供快速概览
表格使用 12 列布局
允许用户操作数据集

列表（网格）选项：

2 列（6/6 拆分） - 用于包含长描述的项
3 列（4/4/4 拆分） - 用于包含多种数据类型的可视化项
4 列（3/3/3/3 拆分） - 用于用户生成的图库和集合，比 4/4/4 布局在首屏多显示约 50% 的内容
自定义 - 用于混合内容需求

网格选择注意事项：

要显示的项总数
每个列表项中要显示的内容
列表项所代表的对象（适用时匹配物理形状）

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

列跨度建议：

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

空状态：

页面的空状态使用全宽布局
表示功能/产品尚无数据、所有数据已清除或尚未设置
包含清晰的 CTA，说明如何填充页面
可与其他布局元素（如标签页、统计小部件或营销卡片）组合使用

3. Marketing Layouts

3. 营销布局

Marketing pages promote new products that site owners are not aware of yet. Built using the

<MarketingPageLayout/>

component split into 2 columns:

Promo messaging
Visual representation of product and features

Optional footer area can display features or testimonials list.

营销页面用于推广站点所有者尚不了解的新产品。使用

<MarketingPageLayout/>

组件分为 2 列：

推广信息
产品和功能的可视化展示

可选页脚区域可显示功能列表或推荐语。

4. Wizard Layouts

4. 向导布局

Wizard pages guide users through setting up a product or feature. They split complex forms into steps for easier completion.

Entry Points:

A marketing page
A marketing card
The primary action of a page
An empty state

Note: Wizards must have a final destination. After completing all steps, users should end up on a relevant page: a dashboard, a details page, or any other relevant location.

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

入口点：

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

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

wix-cli-dashboard-page

Original

Translation

Wix Dashboard Page Builder

Wix 仪表盘页面构建器

Quick Start Checklist

快速开始检查清单

Capabilities

功能特性

Data Operations (Wix Data SDK)

数据操作（Wix Data SDK）

Dashboard APIs

仪表盘 API

Embedded Script Configuration API

嵌入式脚本配置 API

Files and Code Structure

文件与代码结构

WDS Provider Usage

WDS Provider 使用方法

Hard Constraints

硬性约束

Examples

示例

Data Management Table

数据管理表格

Settings Form

设置表单

Order Management

订单管理

Embedded Script Configuration

嵌入式脚本配置

Extension Registration

扩展注册

Step 1: Create Page-Specific Extension File

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

Step 2: Register in Main Extensions File

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

Common Mistakes - Do NOT

常见错误 - 请勿

Code Quality Requirements

代码质量要求

TypeScript Quality Guidelines

TypeScript 质量指南

Core Principles

核心原则

Code Quality Standards

代码质量标准

Error Handling

错误处理

Output Constraints

输出约束

Verification

验证

API Spec Support

API 规范支持

Layout Guidelines

布局指南

Design Principles

设计原则

Screen Size

屏幕尺寸

Base Unit

基础单位

Layout Structure

布局结构

Application Frame

应用框架

Grid Layout

网格布局

Common Layouts

常见布局

1. Form Layouts

1. 表单布局

2. Display Layouts

2. 展示布局

3. Marketing Layouts

3. 营销布局

4. Wizard Layouts

4. 向导布局

Related WDS Components