# Wix 站点组件生成器使用 Wix CLI 应用程序的编辑器清单创建生产质量的 React 站点组件。站点组件是与 Wix 编辑器集成的 React 组件，允许站点所有者通过可视化界面自定义内容、样式和行为。 ## 架构站点组件由 **四个必需文件** 组成： ### 1\.组件清单（`manifest.json`）定义React组件和Wix生态系统之间的契约： * **editorElement** ：根元素配置（选择器、显示名称、原型、布局） * **cssProperties** ：用于样式定制的 CSS API * **data** ：用于内容配置的数据API * **elements** ：用于精细编辑的嵌套元素定义 * **behaviors** ：编辑器交互行为 ### 2\.反应组件（`component.tsx`）生产就绪的 React 功能组件： * 实现props接口匹配manifest数据结构 * 将 className 和 id 应用于根元素 * 通过 `wix.elementsRemovalState` 处理元素删除状态 * 对嵌套元素使用子组件模式 * 包括正确的 TypeScript 键入和错误处理 ### 3\. CSS 样式（`style.css`）现代 CSS 与响应式设计： * 与清单和 React 类名同步的选择器 * 用于动态样式的 CSS 变量 * 响应式设计，无需媒体查询（flexbox、grid、clamp） * 为编辑器元素启用指针事件 * 静态值没有内联样式 * 每个选择器仅一次，`box-sizing: border-box`所有元素 * 没有“transition: all”，没有媒体查询（“prefers-reduced-motion”除外） * 根显示：声明 `--display: [value]` CSS 变量，然后在根上使用 `display: var(--display)` ### 4\. TypeScript 类型（`types.ts`）严格的类型定义： * 所有组件的 Props 接口 * 数据类型映射（文本→字符串，图像→图像对象） * 具有可选链接的元素 props 结构 * Wix系统类型（Wix接口，REMOVED类型） ## 组件清单结构 **在实现站点组件之前，您必须阅读[MANIFEST_GUIDELINES.md]()。**它包含完整的清单结构、所有数据类型、元素配置和所需模式。清单使用以下关键部分定义了编辑器合约： ### 安装（初始放置） { “安装”：{ "staticContainer": "主页", “初始大小”：{ “宽度”：{“sizingType”：“像素”，“像素”：400}， “高度”：{“尺寸类型”：“像素”，“像素”：300 } } } } * **staticContainer** : 使用 `"HOMEPAGE"` 在 Harmony 编辑器上自动安装 * **initialSize** ：使用 `sizingType` 选项定义初始尺寸： * `"content"` \- 根据内容自动调整大小 * `"stretched"` \- 填充可用空间 * `"pixels"` \- 固定像素尺寸（需要 `pixels` 属性） ### editorElement（根配置） { "选择器": ".组件名称", "displayName": "组件名称", “原型”：“容器”， “布局”：{ "resizeDirection": "水平和垂直", "contentResizeDirection": "水平" }, “css属性”：{ “背景颜色”：{ "displayName": "背景颜色", “默认值”：“#ffffff” } }, “数据”：{ “列”：{ “数据类型”：“数字”， "displayName": "列数", “数字”：{“最小值”：1，“最大值”：4 } } }, “元素”：{ “标题”：{ "elementType": "inlineElement", “内联元素”：{ "选择器": ".组件名称__标题", "显示名称": "标题", “数据”：{ “标题文本”：{ “数据类型”：“文本”， "displayName": "标题文本" } }, “行为”：{ “可选择”：正确， “可移动”：正确 } } } } } ### 数据类型参考类型 |运行时值|使用案例 ---|---|--- `文本` |字符串|名称、标题、描述 `textEnum` |字符串|预定义选项 `数字` |数量 |数量、尺寸 `布尔值` |布尔 |切换、标志 `a11y` |对象|辅助功能属性 `链接` | `{ href、目标、rel }` |导航链接 `图像` | `{ uri、url、alt、宽度、高度}` |图片 `视频` |视频对象|媒体内容 `矢量艺术` |净化后的 SVG 对象 |图标、图形 `本地日期` |字符串（年-月-日）|日期值 `本地时间` |字符串（时：分）|时间值 `webUrl` |字符串|外部网址 `richText` |字符串 (HTML) |格式化内容 `arrayItems` |数组 |集合、列表 `方向` |字符串| HTML 目录属性 `菜单项` |菜单项数组 |导航菜单 ### CSS 属性参考用于样式定制的常见 CSS 属性： * **布局** ：`显示`、`间隙`、`填充`、`边距`、`宽度`、`高度` * **排版** : `font`, `fontSize`, `fontWeight`, `textAlign`, `color` * **背景** : `backgroundColor`, `backgroundImage` * **边框** : `border`, `borderRadius`, `boxShadow` * **定位** : `alignItems`, `justifyContent`, `flexDirection` **完整的 CSS 属性参考：** 请参阅 [CSS_GUIDELINES.md]() 了解所有 CSS 属性、变量模式和样式最佳实践。 ## React 组件模式 **完整参考：** 请参阅 [REACT_PATTERNS.md]() 了解详细的组件架构、所有编码模式和实现示例。 ### 道具结构接口 ComponentProps { // 标准道具（始终存在）类名：字符串； id：字符串；维克斯？：维克斯； // 组件级数据（来自 editorElement.data）列？：数量；布局？：字符串； // 元素 props（来自元素定义）元素属性？：{ 标题？：{ 标题文本？：字符串；维克斯？：维克斯； }; 按钮？：{ 按钮文本？：字符串；按钮链接？：链接；维克斯？：维克斯； }; }; } ### 子组件模式将每个不同的 UI 元素提取到命名的子组件中： // 标题子组件接口 TitleProps { 标题文本？：字符串；类名：字符串； } const 标题: FC = ({ titleText = "默认标题", className }) => (

{titleText}

）； // 主要组件 const ProductCard: FC = ({ 类名, 身份证号，元素道具，维克斯 }) => { const removalState = wix?.elementsRemovalState || {}；返回（

{!removalState['标题'] && ( <标题类名=“产品卡__标题” {...elementProps?.title} /> )} {!removalState['按钮'] && ( <按钮类名=“产品卡__按钮” {...elementProps?.button} /> )}

）； }; ### 条件渲染所有元素都必须根据移除状态有条件地渲染： const removalState = wix?.elementsRemovalState || {}；返回（

{!removalState['elementKey'] && }

）； ## CSS 指南 ### 响应式设计策略组件位于不同视口内的用户可调整大小的容器（300-1200px）中： * **根元素** : `宽度: 100%;高度：100%` * **布局结构** ：使用 CSS Grid 和 Flexbox 实现流畅的响应能力 * **排版** ：使用 `clamp()` 进行流体缩放 * **间距**：固定或紧密的夹具间距（≤50% 变化） ### 用于动态样式的 CSS 变量 .组件{ --显示：块； --背景颜色：#ffffff； --文字颜色：#333333；显示：var(--显示)；背景颜色：var(--背景颜色); 颜色：var(--文本颜色)；指针事件：自动； } ### 选择器同步 **关键**：CSS 选择器必须与清单选择器和 React 类名完全匹配： * 反应：`className =“product-card__title”` * CSS: `.product-card__title { ... }` * 清单：`“选择器”：“.product-card__title”` ## 设计指南 **完整参考：** 请参阅 [DESIGN_SYSTEM.md]() 了解视觉设计原则、创意指南和美学最佳实践。 ### 间距作为沟通关系 |价值|使用案例 ---|---|--- 紧（图标+标签）| 0.25-0.5rem (4-8px) |聚类相关项目同类别| 1-1.5rem (16-24px) | 1-1.5rem (16-24px) |卡片部分、表单字段不同部分 | 2-3rem (32-48px) | 2-3rem (32-48px) |主要内容块重点/戏剧| 4rem+ (64px+) |英雄内容，奢华感觉 ### 视觉一致性 * **圆角半径**：所有相似的元素共享相同的半径（0-4px 锐角，6-12px 圆角） * **阴影级别**：最多 3 个级别（静止、悬停、浮动） * **元素高度** ：相似元素的一致高度 * **颜色策略**：有目的地使用完整的调色板来表示层次结构和区域 ### 创意探索超越显而易见的解决方案： * **卡片**：不对称网格、重叠元素、粗重边框 * **列表**：交替风格、聚光灯图案、色彩节奏 * **交互元素**：分割按钮、彩色图标圆圈、平滑过渡 * **内容层次结构**：大量统计数据、引用标注、空白分隔符 ## 组件元素指南 ### 一个元素 = 一个清单条目每个不同的视觉部分都需要一个单独的清单元素： * ✅ 3 个按钮 → 3 个独立的元素 * ✅ 图片 + 文字 → 2 个独立的元素 * ❌ 多个项目分组为一个元素 ### 数据范围规则 **editorElement.data** \- 仅组件范围的配置： * ✅ 布局枚举、数字（列：3，速度：500） * ❌ 文本、链接、图像（属于元素） * ❌ 显示/隐藏布尔值（使用可移动：true代替） **elements[key].data** \- 该特定元素的内容： * ✅ 特定于元素的内容（标题文本、按钮链接、图像） ## 资产要求当组件需要默认图像时，请使用以下格式： // 组件中导入从'./assets/defaultImages'导入{heroImage}； // 用法

资产规格格式： <图像网址名称> { "description": "日落时的现代城市景观", "width": 1920, "height": 1088 } **规则：** * 从“./assets/defaultImages”导入为命名导出 * 宽度/高度：64的倍数，128-2048px之间 * 切勿使用外部 URL ## 输出结构 src/站点/组件/ └── {组件名称}/ ├── manifest.json # 组件清单 ├── component.tsx # React 组件 ├── style.css # CSS 样式 ├── types.ts # TypeScript 类型 └── assets/ # 可选资产 └── defaultImages.ts ## 示例 **完整的工作示例：** 请参阅 [EXAMPLE.md]()，了解具有所有模式的完整生产就绪站点组件，包括清单、React 组件、CSS 和类型。 ### 产品卡组件 **请求：**“创建一个包含图像、标题、价格和购买按钮的产品卡组件” **输出：** * 包含 4 个元素的清单（图像、标题、价格、按钮） * React组件与每个元素的子组件 * CSS 具有响应式网格布局和悬停效果 * 所有 props 和数据结构的 TypeScript 类型 ### 英雄部分组件 **请求：**“构建一个包含背景图片、标题、副标题和 CTA 按钮的英雄部分” **输出：** * 带有背景图像 CSS 属性和 3 个文本元素的清单 * 具有覆盖设计和版式层次结构的 React 组件 * CSS 具有响应式文本缩放和戏剧性间距 * 默认英雄图像的资产规格 ### 功能列表组件 **请求：**“创建一个具有可配置项目数量的功能组件” **输出：** * 使用 arrayItems 数据类型进行特征收集的清单 * 通过安全检查对特征数组进行反应组件映射 * CSS 具有灵活的网格布局，可适应项目计数 * 功能图标、标题和描述的子组件 ## 扩展注册 **扩展注册是强制性的，并且需要两个步骤。** ### 第 1 步：创建特定于组件的扩展文件每个站点组件在其文件夹中都需要一个“extensions.ts”文件：从“@wix/astro/builders”导入{扩展}；从“./manifest.json”导入清单；导出 const sitecomponentMyComponent = extensions.siteComponent({ ...体现， id：“{{GENERATE_UUID}}”，描述：“我的组件”，类型：“platform.MyComponent”，资源：{ 客户：{ 组件：“./site/components/my-component/component.tsx”， componentUrl: "./site/components/my-component/component.tsx", }, }, }); **关键：类型命名约定** `type` 字段使用格式 `platform.{PascalCaseFolderName}`： * 文件夹 `my-component` → `类型："platform.MyComponent"` * 文件夹 `product-card` → `类型："platform.ProductCard"` * 文件夹 `hero-section` → `类型："platform.HeroSection"` 文件夹名称将转换为 PascalCase（连字符已删除，每个单词大写）。 **关键：UUID 生成** `id` 必须是唯一的静态 UUID v4 字符串。为每个扩展生成一个新的 UUID - 不要使用“randomUUID()”或从示例中复制 UUID。 ### 步骤 2：在主扩展文件中注册 **关键：** 创建特定于组件的扩展文件后，您必须阅读 [wix-cli-extension-registration]() 并按照“应用程序注册”部分更新 `src/extensions.ts`。 **如果不完成步骤 2，站点组件将无法在 Wix 编辑器中使用。** ## 代码质量要求 **完整参考：** 请参阅 [TYPESCRIPT_QUALITY.md]() 了解全面的类型安全指南和代码质量标准。 ### TypeScript 标准 * 严格的 TypeScript，没有任何类型 * 所有函数的显式返回类型 * 使用可选链接正确处理空/未定义 * 没有“@ts-ignore”或“@ts-expect-error”注释 ### React 最佳实践 * 带挂钩的功能组件 * useEffect中正确的依赖数组 * 组件必须对 prop 的变化做出反应 * SSR 安全代码（模块范围内没有浏览器 API） ### ESLint 合规性 1.没有未使用的变量/参数/导入（`@typescript-eslint/no-unused-vars`） 2.无外部图像：`img``src`而不是`https://...`（允许：本地导入、`wixstatic.com`、变量） 3. SSR安全：模块范围/构造函数中没有`window`/`document`，在`useEffect`/handlers中保护浏览器API 4. 没有 `dangerouslySetInnerHTML` 或内联 `

Wix CLI 站点组件

包含技能