wix-cli-data-collection

Wix 数据集合构建器

为 Wix CLI 应用创建 CMS 数据集合。数据集合扩展可让你的应用在安装到网站时自动创建 CMS 集合。集合用于存储结构化数据，可通过仪表板页面、网站页面、后端代码和外部应用访问。

重要： 此扩展会自动启用网站的代码编辑器，这是 Wix Data API 正常运行的必要条件。如果没有此扩展，使用 Data API 的应用就需要 Wix 用户手动为其网站启用代码编辑器，但无法保证用户一定会这么做。借助数据集合扩展，你的应用可以可靠地使用 Data API 在集合中读取和写入数据。

---

应用命名空间处理

数据集合必须使用应用命名空间才能正常运行。命名空间会为集合 ID 添加作用域，以避免不同应用之间发生冲突。

实现行为

如果提示词中提供了应用命名空间：

• 在所有代码示例中使用它：<actual-namespace>/collection-suffix

如果提示词中未提供应用命名空间：

• 在所有代码示例中使用占位符 <app-namespace>：<app-namespace>/collection-suffix
• 在“手动操作事项”中添加：“将 <app-namespace> 替换为 Wix Dev Center 中的实际应用命名空间”

集合 ID 格式

• 在扩展定义中（idSuffix）： 仅使用后缀，例如 "products"
• 在 API 调用中： 使用完整的作用域 ID："<app-namespace>/products" — 必须与 idSuffix 完全一致（区分大小写，不进行 camelCase/PascalCase 转换）
• 在 referencedCollectionId 中： 仅使用 idSuffix（而非完整的作用域 ID）— 系统会自动解析
• 示例：如果 idSuffix 是 "product-recommendations"，API 调用中应使用 "<app-namespace>/product-recommendations"，而不是 "<app-namespace>/productRecommendations"

---

文件结构

在 Wix CLI 应用中，所有 CMS 集合都定义在同一个文件中：

文件： src/extensions/data/extensions.ts

此文件使用 @wix/astro/builders 中的 extensions.genericExtension() 模式注册所有集合：

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

export const dataExtension = extensions.genericExtension({
  compId: "{{GENERATE_UUID}}",
  compName: "data-extension",
  compType: "DATA_COMPONENT",
  compData: {
    dataComponent: {
      collections: [
        // All collections defined here
      ],
    },
  },
});

重要： compId 必须是唯一的静态 UUID 字符串。为每个应用生成一个全新的 UUID v4 — 不要使用 randomUUID()，也不要复制示例中的 UUID。创建或修改此文件后，请按照 wix-cli-extension-registration 生成 UUID，并在 src/extensions.ts 中注册扩展（集合正常运行所必需）。

要点：

• 单个文件包含所有集合
• 使用 @wix/astro/builders 中的 extensions.genericExtension()
• 每个集合都包含：idSuffix、displayName、displayField、fields、dataPermissions，以及可选的 initialData
• displayField 指定当其他集合引用此集合中的项目时，CMS 显示哪个字段
• 通过将操作（INSERT、UPDATE、DELETE）与现有集合合并来生成集合
• 完整结构请参见扩展模板

字段类型

类型	描述	用途
TEXT	单行文本	名称、标题
RICH_TEXT	格式化的 HTML 文本	博客内容
RICH_CONTENT	包含嵌入式媒体的富文本内容	复杂的博客文章
NUMBER	十进制数字	价格、数量
BOOLEAN	真/假	开关、标记
DATE	仅日期	生日
DATETIME	日期和时间	时间戳
TIME	仅时间	日程安排
IMAGE	单张图片	缩略图
DOCUMENT	文件附件	PDF
VIDEO	视频文件	媒体
AUDIO	音频文件	播客
MEDIA_GALLERY	多个媒体文件	画廊
REFERENCE	链接到一个项目	作者 → 用户
MULTI_REFERENCE	链接到多个项目	帖子 → 标签
ADDRESS	结构化地址	地点
URL	URL 验证	链接
PAGE_LINK	链接到 Wix 页面	内部导航
LANGUAGE	语言代码	多语言内容
OBJECT	JSON 对象	灵活的数据
ARRAY	值数组	通用数组
ARRAY_STRING	字符串数组	标签列表
ARRAY_DOCUMENT	文档数组	文件集合
ANY	任意类型	灵活性最高

重要：OBJECT 字段需要 objectOptions。 使用 type: "OBJECT" 时，必须包含 objectOptions 属性——否则 API 会拒绝 OBJECT 字段。如果不需要架构验证，请使用空对象 {}：

{
  "key": "settings",
  "displayName": "Settings",
  "type": "OBJECT",
  "objectOptions": {}
}

对于结构化对象，请在 objectOptions.fields 中定义嵌套字段：

{
  "key": "triggerRules",
  "displayName": "Trigger Rules",
  "type": "OBJECT",
  "objectOptions": {
    "fields": [
      { "key": "url", "displayName": "URL Condition", "type": "TEXT" },
      {
        "key": "scrollDepth",
        "displayName": "Scroll Depth %",
        "type": "NUMBER"
      },
      { "key": "dateStart", "displayName": "Start Date", "type": "DATE" }
    ]
  }
}

字段属性

{
  "key": "email",
  "displayName": "Email Address",
  "type": "TEXT",
  "required": true,
  "unique": true,
  "defaultValue": null,
  "description": "User's primary email"
}

属性	描述
key	字段标识符（驼峰命名）
displayName	在 CMS 中显示的标签
type	字段数据类型
required	必须有值
unique	不允许重复
defaultValue	初始值
description	帮助文本

命名约定

• 字段键： lowerCamelCase，仅限 ASCII 字符（例如，productName、isActive、createdAt）
• 集合 ID（idSuffix）： lower-kebab-case 或 lower_underscore（例如，product-categories、blog_posts）
• 显示名称： 易于理解，可包含空格（例如，"Product Name"、"Is Active"）

系统字段（自动生成）

每个集合都包含：_id、_createdDate、_updatedDate、_owner

权限

访问级别决定谁可以读取、创建、更新和删除集合中的条目。

级别	描述
UNDEFINED	未设置（继承默认值）
ANYONE	公开访问（包括访客）
SITE_MEMBER	任何已登录用户（会员和协作者）
SITE_MEMBER_AUTHOR	已登录用户，但会员只能访问自己的条目
CMS_EDITOR	拥有 CMS 访问权限的网站协作者
PRIVILEGED	CMS 管理员和特权用户

常见模式：

• 公开内容（默认，推荐）：read: ANYONE, write: PRIVILEGED
• 用户生成的内容：read: SITE_MEMBER, write: SITE_MEMBER_AUTHOR
• 编辑工作流：read: ANYONE, write: CMS_EDITOR
• 私有/管理员：read: PRIVILEGED, write: PRIVILEGED

权限层级（从限制最严格到最宽松）：PRIVILEGED > CMS_EDITOR > SITE_MEMBER_AUTHOR > SITE_MEMBER > ANYONE > UNDEFINED

基于上下文的权限规则

重要：权限必须与数据的访问位置和方式相匹配。 数据的使用者决定了最低权限级别——设置的权限如果比访问上下文要求的限制更多，会导致运行时故障（结果为空或出现权限拒绝错误）。

确定权限时，请思考：“谁会与这些数据交互，以及从哪里访问？”

访问上下文	谁可以查看/使用	影响
网站小组件（SITE_WIDGET）	任何网站访客（公开）	读取权限必须为 ANYONE。如果小组件接受输入（例如评论、投稿），插入权限也必须为 ANYONE 或 SITE_MEMBER。
嵌入式脚本	任何网站访客（公开）	与网站小组件相同——读取权限必须为 ANYONE。写入权限取决于访客能否提交数据。
仪表板页面（DASHBOARD_PAGE）	网站所有者/协作者	由于只有获得授权的用户才能访问仪表板，因此所有操作都可以使用 CMS_EDITOR 或 PRIVILEGED。
后端代码（网站端）	在访客上下文中运行	如果由页面代码或网站端模块调用，调用方具有访客级权限——数据必须在相应的公开级别具备可读/可写权限。
后端代码（提升权限）	使用 @wix/essentials 中的 auth.elevate() 运行	可以绕过权限，但对于任何未提升权限的调用方，集合仍需设置正确的默认值。

应用方法：

1. 找出所有读取或写入集合的位置——网站小组件、仪表板页面、嵌入式脚本、后端 API。
2. **以限制最少的上下文作为底线。**如果网站小组件和仪表板页面都会读取数据，itemRead 必须为 ANYONE（因为小组件是公开的）。
3. **按操作分别设置。**集合可以设置为 itemRead: ANYONE（小组件显示数据），但 itemInsert: CMS_EDITOR（只有仪表板用户可以添加条目）。每项操作互不影响。

按蓝图类型划分的示例：

• 仪表板管理数据，网站小组件显示数据：itemRead: ANYONE、itemInsert: CMS_EDITOR、itemUpdate: CMS_EDITOR、itemRemove: CMS_EDITOR
• 网站小组件收集用户投稿（例如评论），仪表板负责审核：itemRead: ANYONE、itemInsert: ANYONE、itemUpdate: CMS_EDITOR、itemRemove: CMS_EDITOR
• 仅会员可访问的小组件读取数据，会员可以投稿：itemRead: SITE_MEMBER、itemInsert: SITE_MEMBER、itemUpdate: SITE_MEMBER_AUTHOR、itemRemove: CMS_EDITOR
• 仅限仪表板（没有公开界面）：itemRead: CMS_EDITOR、itemInsert: CMS_EDITOR、itemUpdate: CMS_EDITOR、itemRemove: CMS_EDITOR

**反模式：**在网站小组件会查询的集合上设置 itemRead: PRIVILEGED——由于访客没有特权访问权限，小组件会向所有访客返回空结果。

关系

一对一／多对一（REFERENCE）：

{
  "key": "category",
  "displayName": "Category",
  "type": "REFERENCE",
  "referenceOptions": {
    "referencedCollectionId": "categories"
  }
}

多对多（MULTI_REFERENCE）：

{
  "key": "tags",
  "displayName": "Tags",
  "type": "MULTI_REFERENCE",
  "multiReferenceOptions": {
    "referencedCollectionId": "tags"
  }
}

关键约束：

• REFERENCE／MULTI_REFERENCE 字段只能链接到应用中定义的其他自定义 CMS 集合
• referencedCollectionId 必须是同一计划中另一个集合的 idSuffix
• 切勿使用 REFERENCE 字段链接到 Wix 业务实体（Products、Orders、Contacts、Members 等）
• 请改用 Wix SDK API 访问 Wix 业务实体

集合操作

集合支持三种操作类型来修改集合：

INSERT

创建新集合，或替换具有相同 idSuffix 的现有集合。

使用场景： 创建新集合或完全替换现有集合。

UPDATE

通过将新数据与现有字段合并来修改现有集合。

使用场景： 添加字段、更新权限或修改集合属性。

行为：

• 如果集合存在：将新数据与现有集合合并
• 如果集合不存在：将更新视为插入（创建新集合）

DELETE

从应用中移除集合。

使用场景： 移除不再需要的集合。

行为：

• 从 src/extensions/data/extensions.ts 中移除集合
• 如果删除了所有集合，则删除整个文件

合并逻辑： 操作通过以 idSuffix 为键的 Map 来应用。首先将现有集合载入 Map，然后每项操作都会对其进行修改：INSERT 设置／替换，UPDATE 与现有集合合并（若不存在则创建），DELETE 移除集合。最终 Map 中的值将成为输出集合。

应用版本更新

更改数据集合扩展需要发布应用的新主版本。用户更新到新主版本后，其集合将按以下方式更新：

• 添加新集合： 在站点上创建新集合。
• 移除集合： 如果旧版应用定义了某个集合，而新版没有定义，则从站点移除该集合。
• 修改集合架构： 对集合应用字段的添加、移除和类型更改。保留现有数据。

重要说明：

• 集合更改仅影响更新到新主版本的用户。未更新的用户将保留当前集合。
• 更新后，集合更改最多需要 5 分钟才能生效。
• 仅在首次创建集合时导入初始数据。 如果集合已包含数据，则更新时会忽略 initialData。

Wix CLI 特定约束

嵌入式脚本参数与集合

重要：切勿创建 CMS 集合来存储嵌入式脚本的配置。

所有嵌入式脚本配置都必须通过嵌入式脚本参数（embeddedScriptParameters）进行，而不是使用 CMS 集合。

不要为以下内容创建集合：

• 颜色、消息、标题、文本内容
• 优惠券代码、显示设置
• UI 自定义（位置、尺寸、样式）
• 时间设置、功能开关
• 显示频率、阈值
• 最小值/最大值
• 任何用于控制嵌入式脚本行为或外观的配置

配置示例（使用参数，而非集合）：

• 弹窗标题 → 嵌入式脚本参数
• 优惠券代码 → 嵌入式脚本参数
• 背景颜色 → 嵌入式脚本参数
• 显示位置 → 嵌入式脚本参数
• 显示/隐藏开关 → 嵌入式脚本参数

CMS 集合只能用于：

• 业务数据（产品、订单、库存等）
• 用户生成的内容（评价、评论、提交内容）
• 事件日志（仅在明确要求用于分析/跟踪时）
• 非配置类的多记录关系型数据

判断规则：

• 如果某项内容控制嵌入式脚本的工作方式或外观 → 它属于配置 → 使用嵌入式脚本参数
• 如果某项内容属于业务数据或用户生成的内容 → 它属于数据 → 使用 CMS 集合

站点组件设置与集合

重要：站点组件内置设置面板（panel.tsx），用于处理所有组件配置。

对于仅包含 SITE_WIDGET 的蓝图（不含 DASHBOARD_PAGE 或其他扩展）：

• 始终返回 collections: []（空数组）
• 组件面板负责处理所有内容
• 切勿创建集合来存储组件配置数据

由组件面板处理的配置（而非集合）：

• 倒计时的目标日期/时间 → 组件面板
• 显示颜色、字体、尺寸 → 组件面板
• 标题、标签、消息 → 组件面板
• 功能开关、显示/隐藏选项 → 组件面板
• 数值设置（延迟、间隔、阈值）→ 组件面板

仅当满足以下所有条件时，才为 SITE_WIDGET 创建集合：

1. 蓝图还包含一个需要管理组件所显示数据的 DASHBOARD_PAGE 扩展
2. 或组件明确需要显示多条用户生成/业务数据记录（而非配置）
3. 且这些数据不属于配置（日期、颜色、设置、显示选项始终属于配置）

反模式

不要创建聚合字段。 如果你有单独的 rating 字段，请动态计算平均值，不要存储 averageRating 之类的计算值。

不要重复配置。 如果嵌入式脚本参数中已经保存了 { headline, color }，就不要再创建包含相同数据的 CMS 集合。

不要创建单值集合。 像 { theme: "dark" } 这样只有一个字段的集合，应改用嵌入式脚本参数或组件设置。

初始数据规则

initialData 中的每个项目都必须与集合架构完全匹配：

• 字段键必须使用 lowerCamelCase，并与架构相符
• TEXT → 字符串，NUMBER → 数字，BOOLEAN → 布尔值
• DATE/DATETIME → 使用 { "$date": "2024-01-15T10:30:00.000Z" } 格式
• REFERENCE → 提供被引用集合的 idSuffix
• 必填字段始终必须有值

示例

包含初始数据的简单集合

请求：“创建一个用于处理手续费的集合，并提供示例数据”

生成的文件： src/extensions/data/extensions.ts

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

export const dataExtension = extensions.genericExtension({
  compId: "{{GENERATE_UUID}}",
  compName: "data-extension",
  compType: "DATA_COMPONENT",
  compData: {
    dataComponent: {
      collections: [
        {
          schemaUrl: "https://www.wix.com/",
          idSuffix: "additional-fees",
          displayName: "Additional Fees",
          displayField: "title",
          fields: [
            { key: "title", displayName: "Fee Title", type: "TEXT" },
            { key: "amount", displayName: "Fee Amount", type: "NUMBER" },
          ],
          dataPermissions: {
            itemRead: "ANYONE",
            itemInsert: "PRIVILEGED",
            itemUpdate: "PRIVILEGED",
            itemRemove: "PRIVILEGED",
          },
          initialData: [
            { title: "Handling Fee", amount: 5 },
            { title: "Gift Wrapping", amount: 3.5 },
          ],
        },
      ],
    },
  },
});

带引用关系的集合

请求：“创建带有关系的产品和类别集合”

集合：

• categories - 类别定义
• products - 引用类别的产品

这两个集合都定义在同一个 src/extensions/data/extensions.ts 文件中，其中 products 集合使用 REFERENCE 字段链接到 categories。请参阅扩展示例模板，了解完整的多集合示例。

常见模式

**软删除：**添加 isDeleted（BOOLEAN，默认值：false）

**状态/工作流：**添加 status（TEXT），可使用 draft/pending/published 等值

**URL 别名：**添加 slug（TEXT，唯一），用于便于 SEO 的 URL

**所有者追踪：**添加 createdBy（REFERENCE → 自定义集合，而非 Members）

**注意：**如需追踪所有者，请为用户创建自定义集合，而不是直接引用 Wix Members。

参考文档

• extension-template.ts - src/extensions/data/extensions.ts 的模板

公开文档

• 关于数据集合扩展 - 何时使用该扩展、实现选项以及应用版本更新行为
• 在应用仪表板中添加数据集合扩展 - 通过应用仪表板 JSON 编辑器配置集合的分步指南，并附有配置示例
• 数据集合扩展 JSON 参考 - 数据集合扩展的完整 JSON 架构和字段定义