# Wix 网站小工具生成器为 Wix CLI 应用程序创建自定义元素小部件扩展。站点小部件是转换为 Wix 编辑器中显示的 Web 组件的 React 组件，允许站点所有者使用内置设置面板向其页面添加交互式、可配置的小部件。 ## 快速入门清单创建站点小部件时请按顺序执行以下步骤： 1. 创建小部件文件夹： `src/site/widgets/custom-elements//` 2. 使用 React 组件和 `reactToWebComponent` 转换创建 `widget.tsx` 3. 使用 WDS 组件和 `widget.getProp/setProp` 创建 `panel.tsx` 4. 使用 `extensions.customElement()` 和唯一的 UUID 创建 `extensions.ts` 5.更新 `src/extensions.ts` 以导入并使用新扩展 ## 架构站点小部件由 **两个必需文件** 组成： ### 1\.小部件组件（`widget.tsx`）使用“react-to webcomponent”将 React 组件转换为 Web 组件： * 定义具有可配置属性的 Props 接口 (camelCase) * 创建一个渲染widget UI的React功能组件 * 使用 props 映射转换为 Web 组件 * 使用内联样式（无 CSS 导入） * 使用 Wix Data API 时处理 Wix Editor 环境 ### 2\.设置面板（`panel.tsx`） Wix 编辑器侧栏中显示的设置面板： * 使用 Wix 设计系统组件（请参阅 [references/SETTINGS_PANEL.md]()） * 通过“@wix/editor”小部件 API 管理小部件属性 * 使用 `widget.getProp('kebab-case-name')` 加载初始值 * 使用 `widget.setProp('kebab-case-name', value)` 更新属性 * 包裹在 `WixDesignSystemProvider > SidePanel > SidePanel.Content` 中 * 对于颜色选择器，请使用 `@wix/editor` 中的 `inputs.selectColor()` 和 `FillPreview` — 而不是 `` * 对于字体选择器，请使用“@wix/editor”中的“inputs.selectFont()”和“Button”——而不是文本输入 ## 小部件组件模式导入 React, { type FC, useState, useEffect } from 'react'; 从'react-dom'导入ReactDOM；从“react-to-webcomponent”导入reactToWebComponent；接口 WidgetProps { 标题？：字符串；目标日期？：字符串；目标时间？：字符串； bgColor？：字符串；文本颜色？：字符串；字体？：字符串； } const CustomElement: FC = ({ title = '倒计时', 目标日期 = '', 目标时间 = '00:00', bgColor = '#ffffff', 文本颜色 = '#333333', 字体=“{}”， }) => { const { 字体：textFont, textDecoration } = JSON.parse(font); const [时间, setTime] = useState({ 天: 0, 小时: 0, 分钟: 0, 秒: 0, isExpired: false }); 使用效果（（）=> { if (!targetDate) 返回；常量更新 = () => { const target = new Date(`${targetDate}T${targetTime}`); const diff = target.getTime() - Date.now(); 如果（差异 <= 0）{ setTime({ 天: 0, 小时: 0, 分钟: 0, 秒: 0, isExpired: true }); 返回； } 设置时间（{ 天：Math.floor(diff / (1000 * 60 * 60 * 24)), 小时：Math.floor((diff % (1000 * 60 * 60 * 24)) / (1000 * 60 * 60)), 分钟：Math.floor((diff % (1000 * 60 * 60)) / (1000 * 60)), 秒：Math.floor((diff % (1000 * 60)) / 1000), 已过期：假， }); }; 更新（）； const 间隔 = setInterval(更新, 1000); 返回（）=>清除间隔（间隔）； }, [目标日期, 目标时间]); 常量样式 = { 包装：{ 背景颜色：bgColor，内边距：'24px 32px', textAlign: 'center' 作为 const, 显示：'内联块'， }, 标题：{ 字体：textFont || '600 24px 无衬线', 颜色：文字颜色，文字装饰， marginBottom: '16px', }, }; 返回（

{标题 &&

{title}

} {/* 小部件内容 */}

）； }; const customElement = ReactToWebComponent(CustomElement, React, ReactDOM, { 道具：{ 标题：'字符串'，目标日期：'字符串'，目标时间：'字符串'， bgColor: '字符串', 文本颜色：'字符串'，字体：'字符串'， }, }); 导出默认的自定义元素； **要点：** * Props 接口使用 **camelCase** （例如，`targetDate`、`bgColor`） *`reactToWebComponent`配置使用`'string'`类型的camelCase键 * 所有 props 都作为字符串从 Web 组件传递 * 使用内联样式，而不是 CSS 导入 * 从 JSON 字符串中解析复杂的 props（如 `font`）： `const { font: textFont, textDecoration } = JSON.parse(font)` * 通过 `font` CSS 简写和 `textDecoration` 属性应用字体 * 将帮助器组件、实用函数和样式提取到单独的文件中，以实现干净的代码组织 ## 设置面板图案导入 React, { type FC, useState, useEffect, useCallback } from "react"; 从“@wix/editor”导入{ widget }；导入{ 侧面板， WixDesignSystemProvider, 输入，表单字段，时间输入，盒子， } 来自“@wix/design-system”；导入“@wix/design-system/styles.global.css”；从“./components/ColorPickerField”导入{ ColorPickerField }；从“./components/FontPickerField”导入{ FontPickerField }；从“./utils”导入{parseTimeValue}；常量 DEFAULT_BG_COLOR = "#0a0e27"; 常量 DEFAULT_TEXT_COLOR = "#00ff88"; 常量 DEFAULT_TEXT_FONT = ""; 常量 DEFAULT_TEXT_DECORATION = ""; 常量面板： FC = () => { const [title, setTitle] = useState("倒计时"); const [targetDate, setTargetDate] = useState(""); const [targetTime, setTargetTime] = useState("00:00"); const [bgColor, setBgColor] = useState<字符串>(DEFAULT_BG_COLOR); const [textColor, setTextColor] = useState<字符串>(DEFAULT_TEXT_COLOR); const [font, setFont] = useState({ 字体: DEFAULT_TEXT_FONT, textDecoration: DEFAULT_TEXT_DECORATION }); 使用效果（（）=> { Promise.all([ widget.getProp("标题"), widget.getProp("目标日期"), widget.getProp("目标时间"), widget.getProp("背景颜色"), widget.getProp("文本颜色"), widget.getProp(“字体”), ]） .then(([titleVal, dateVal, timeVal, bgColorVal, textColorVal, fontString]) => { setTitle(titleVal || "倒计时"); setTargetDate(dateVal || ""); setTargetTime(timeVal || "00:00"); setBgColor(bgColorVal || DEFAULT_BG_COLOR); setTextColor(textColorVal || DEFAULT_TEXT_COLOR); setFont(JSON.parse(fontString || "{}")); }) .catch((error) => console.error("无法获取小部件属性：", error)); }, []); const handleTitleChange = useCallback((事件: React.ChangeEvent) => { const newTitle = event.target.value; 设置标题（新标题）； widget.setProp("标题", newTitle); }, []); const handleDateChange = useCallback((事件: React.ChangeEvent) => { const newDate = event.target.value; 设置目标日期（新日期）； widget.setProp("目标日期", newDate); }, []); const handleTimeChange = useCallback(({ date }: { date: Date }) => { 如果（日期）{ const 小时 = String(date.getHours()).padStart(2, '0'); const 分钟 = String(date.getMinutes()).padStart(2, '0'); const newTime = `${小时}:${分钟}`; 设置目标时间（新时间）； widget.setProp("目标时间", newTime); } }, []); const handleBgColorChange = (值: 字符串) => { 设置背景颜色（值）； widget.setProp("背景颜色", value); }; const handleTextColorChange = (值: 字符串) => { 设置文本颜色（值）； widget.setProp("文本颜色", value); }; const handleFontChange = (值: { 字体: 字符串; textDecoration: 字符串 }) => { 设置字体（值）； widget.setProp("字体", JSON.stringify(value)); }; 返回（ <侧面板宽度=“300”高度=“100vh”> <框方向=“垂直”间隙=“24px”> <侧面板.字段> <输入类型=“文本” 值={标题} onChange={handleTitleChange} placeholder="输入倒计时标题" /> <侧面板.字段> <输入类型=“日期” 值={目标日期} onChange={handleDateChange} /> <侧面板.字段> <时间输入值={parseTimeValue(目标时间)} onChange={handleTimeChange} /> <颜色选择器字段标签=“背景颜色” 值={背景颜色} onChange={handleBgColorChange} /> <颜色选择器字段标签=“文字颜色” 值={文本颜色} onChange={handleTextColorChange} /> <字体选择器字段标签=“文本字体” 值={字体} onChange={handleFontChange} /> ）； }; 导出默认面板； **要点：** * `widget.getProp()` 和 `widget.setProp()` 中的 Prop 名称使用 **kebab-case** (例如，`"target-date"`、`"bg-color"`) * 始终更新 onChange 处理程序中的本地状态和 widget 属性 * 将内容包裹在 `WixDesignSystemProvider > SidePanel > SidePanel.Content` 中 * 使用 `@wix/design-system` 中的 WDS 组件（请参阅 [references/SETTINGS_PANEL.md]()） * 导入 `@wix/design-system/styles.global.css` 样式 * 对于颜色，请使用“ColorPickerField”和“@wix/editor”中的“inputs.selectColor()”，而不是“” * 对于字体，请使用“FontPickerField”和“@wix/editor”中的“inputs.selectFont()”——而不是文本输入 * 字体值通过 `JSON.stringify()` / `JSON.parse()` 存储为 JSON 字符串 ## 道具命名约定 **关键：** 道具在每个文件中使用不同的命名约定：文件|大会 |示例 ---|---|--- `widget.tsx`（Props 接口）|驼峰式 | `目标日期`、`bgColor`、`textColor` `panel.tsx`（小部件 API）|烤肉串盒 | `"目标日期"`、`"背景颜色"`、`"文本颜色"` `reactToWebComponent` 配置 |驼峰式 | `目标日期：'字符串'` Web 组件会自动在驼峰命名法（React props）和短横线命名法（HTML 属性）之间进行转换。 ## Wix 数据 API 集成在小部件中使用 Wix 数据 API 时，您**必须**妥善处理 Wix 编辑器环境：从“@wix/data”导入{items}；从“@wix/site-window”导入{ window as wixWindow }； const CustomElement: FC = ({ collectionId }) => { const [数据，setData] = useState(null); const [isEditor, setIsEditor] = useState(false); 使用效果（（）=> { const loadData = async () => { const currentViewMode = 等待 wixWindow.viewMode(); if (currentViewMode === "编辑器") { // 不要在编辑器中获取数据 - 显示占位符 setIsEditor(真); 返回； } // 仅在实时站点上获取真实数据尝试{ const results = wait items.query(collectionId).limit(10).find(); setData(结果.items); } 捕获（错误）{ console.error("加载数据失败：", error); } }; 加载数据（）； }, [集合Id]); 如果（是编辑器）{ 返回（

小部件将在实时站点上显示数据

集合：{collectionId}

）； } // 使用真实数据渲染小部件返回（

{数据？.map((项目) => (

{item.title}

))}

）； }; **要求：** * 从“@wix/site-window”导入“{ window as wixWindow }” * 在获取数据之前检查 `await wixWindow.viewMode()` * 如果 `viewMode === 'Editor'`，则显示占位符 UI * 仅在不处于编辑器模式时获取和渲染真实数据 ## 颜色选择对于设置面板中的颜色选择，请使用“ColorPickerField”组件和“@wix/editor”中的“inputs.selectColor()”。不要使用``。 // 组件/ColorPickerField.tsx 导入 React, { type FC } from 'react'; 从“@wix/editor”导入{输入}；从 '@wix/design-system' 导入 { FormField, Box, FillPreview, SidePanel }; 接口 ColorPickerFieldProps { 标签：字符串；值：字符串； onChange: (值: 字符串) => void; } 导出常量 ColorPickerField: FC = ({ 标签，值，改变时， }) => ( <侧面板.字段> <表单字段标签={标签}> <框宽度=“30px”高度=“30px”> <填充预览填充={值} onClick={() => input.selectColor(value, { onChange: (val) => { if (val) onChange(val); } })} /> ）；在面板中的用法： const handleBgColorChange = (值: 字符串) => { 设置背景颜色（值）； widget.setProp("背景颜色", value); }; **重要提示：** 将 `@wix/editor` 中的 `inputs.selectColor(value, { onChange })` 与 WDS 中的 `FillPreview` 一起使用。这将打开本机 Wix 颜色选择器，其中包含主题颜色、渐变等。切勿使用``。 ## 字体选择对于设置面板中的字体选择，请使用“FontPickerField”组件和“@wix/editor”中的“inputs.selectFont()”。不要使用文本输入。 // 组件/FontPickerField.tsx 导入 React, { type FC } from 'react'; 从“@wix/editor”导入{输入}；从 '@wix/design-system' 导入 { FormField, Button, Text, SidePanel }; 接口 FontValue { 字体：字符串；文本装饰：字符串； } 接口 FontPickerFieldProps { 标签：字符串；值：字体值； onChange: (值: FontValue) => void; } 导出 const FontPickerField: FC = ({ 标签，值，改变时， }) => ( <侧面板.字段> <表单字段标签={标签}> <按钮尺寸=“小” 优先级=“次要” onClick={() => input.selectFont(value, { onChange: (val) => onChange({ font: val.font, textDecoration: val.textDecoration || "" }) })} 全宽 > 更改字体）；在面板中的用法： const [font, setFont] = useState({ font: "", textDecoration: "" }); const handleFontChange = (值: FontValue) => { 设置字体（值）； widget.setProp("字体", JSON.stringify(value)); }; **重要提示：** 将 `@wix/editor` 中的 `inputs.selectFont(value, { onChange })` 与回调模式一起使用。这提供了丰富的字体选择器对话框，具有粗体、斜体、大小和版式功能。字体值存储为 JSON 字符串。 ## 输出结构 src/site/widgets/custom-elements/ └── {小部件名称}/ ├── widget.tsx # 主widget组件 ├── panel.tsx # 设置面板组件 ├── extensions.ts # 扩展注册 ├── Components/ # 可选子组件 │ ├── ColorPickerField.tsx │ └── FontPickerField.tsx └── utils/ # 可选的辅助函数 └── 格式化程序.ts ## 示例 ### 倒计时器小部件 **请求：**“创建一个倒计时器小部件” **输出：** * 具有可配置标题、目标日期/时间、颜色和字体的小部件 * 设置面板带有日期选择器、时间输入、颜色选择器、字体选择器 * 实时倒计时显示日、时、分、秒 ### 产品展示小部件 **请求：**“创建一个显示集合中产品的小部件” **输出：** * 查询Wix数据收集的小部件 * 编辑器环境处理（在编辑器中显示占位符） * 用于集合选择、显示选项、样式的设置面板 * 带有产品卡的响应式网格布局 ### 交互式计算器小部件 **请求：**“创建具有可自定义颜色的计算器小部件” **输出：** * 功能计算器组件 * 用于颜色定制的设置面板（背景、按钮、文本） * 所有样式的内联样式 * 无外部依赖 ## 前端美学避免通用美学。使用独特的字体（避免 Inter、Roboto、Arial）、内聚的调色板、用于微交互的 CSS 动画以及特定于上下文的选择来创建独特的设计。不要使用陈词滥调的配色方案或可预测的布局。 ## 扩展注册 **扩展注册是强制性的，并且需要两个步骤。** ### 第 1 步：创建特定于小部件的扩展文件每个站点小部件在其文件夹中都需要一个“extensions.ts”文件：从“@wix/astro/builders”导入{扩展}；导出 const sitewidgetMyWidget = extensions.customElement({ id：“{{GENERATE_UUID}}”，名称：“我的小部件”，标签名称：“我的小部件”，元素：“./site/widgets/custom-elements/my-widget/widget.tsx”，设置：“./site/widgets/custom-elements/my-widget/panel.tsx”，安装：{ 自动添加：真， }, 宽度：{ 默认宽度：500，允许拉伸：真， }, 高度：{ 默认高度：500， }, }); **关键：UUID 生成** `id` 必须是唯一的静态 UUID v4 字符串。为每个扩展生成一个新的 UUID - 不要使用“randomUUID()”或从示例中复制 UUID。将“{{GENERATE_UUID}}”替换为新生成的 UUID，例如“a1b2c3d4-e5f6-7890-abcd-ef1234567890”。物业 |类型 |描述 ---|---|--- `id` |字符串|唯一静态UUID v4（新鲜生成） `名称` |字符串|在编辑器中显示名称 `标签名称` |字符串| HTML 自定义元素标签（kebab-case） `元素` |字符串| React 组件小部件的路径 `设置` |字符串|设置面板组件的路径 `安装` |对象|自动添加行为 `宽度` |对象|默认宽度和拉伸设置 `高度` |对象|默认高度设置 ### 步骤 2：在主扩展文件中注册 **关键：** 创建小部件特定的扩展文件后，您必须阅读 [wix-cli-extension-registration]() 并按照“应用程序注册”部分更新 `src/extensions.ts`。 **如果不完成步骤 2，站点小部件将无法在 Wix 编辑器中使用。** ## 代码质量要求 * 严格的 TypeScript（无“any”，显式返回类型） * 带钩子的函数式 React 组件 * 正确的错误处理和加载状态 * 没有“@ts-ignore”评论 * 仅内联样式（无 CSS 导入） * 使用 Wix Data API 时处理 Wix Editor 环境 *一致的道具命名（小部件中的camelCase，面板中的kebab-case） ## 验证实现完成后， **wix-cli-orchestrator** 将使用 [wix-cli-app-validation]() 运行验证。

Wix CLI 站点小工具

包含技能