# Wix 网站插件生成器为 Wix CLI 应用程序创建站点插件扩展。网站插件是自定义元素，集成到 Wix 业务解决方案（如 Wix 商店、Wix 预订、Wix 电子商务）中预定义的**插槽**中，扩展其功能和用户体验。网站所有者可以使用 Wix 编辑器中的插件资源管理器将网站插件放置到 UI 插槽中。 ## 快速入门清单创建站点插件时请按顺序执行以下步骤： 1. 创建插件文件夹： `src/extensions/site/plugins//` 2. 创建使用 `observedAttributes` 扩展 `HTMLElement` 的 `.tsx` 3. 使用 WDS 组件和 `widget.getProp/setProp` 创建 `.panel.tsx` 4. 使用“extensions.sitePlugin()”和唯一的 UUID 创建“.extension.ts” 5.更新 `src/extensions.ts` 以导入并使用新扩展 ## 架构站点插件由**三个必需的文件**组成： ### 1\.插件组件（`<插件名称>.tsx`）使用本机 HTMLElement 在插槽中呈现的自定义元素组件： * 扩展`HTMLElement`类 * 为响应式属性定义`observedAttributes` * 实现`connectedCallback()`和`attributeChangedCallback()`用于渲染 * 通过模板字符串使用内联样式 * 属性使用 **kebab-case** （例如，`display-name`） ### 2\.设置面板（`<插件名称>.panel.tsx`） Wix 编辑器侧栏中显示的设置面板： * 使用 Wix 设计系统 (`@wix/design-system`) 组件 - 请参阅 [wds-docs]() 以获取组件参考 * 通过 `@wix/editor` 小部件 API 管理插件属性 * 使用 `widget.getProp('kebab-case-name')` 加载初始值 * 使用 `widget.setProp('kebab-case-name', value)` 更新属性 * 小部件属性绑定到自定义元素属性 - 任何属性更改都会自动更新相应的属性 * 包裹在 `WixDesignSystemProvider > SidePanel > SidePanel.Content` 中 ### 3\.扩展配置（`<插件名称>.extension.ts`）定义插件的放置配置： * 指定插件可以添加到哪些插槽 * 配置应用程序安装时的自动添加行为 * 设置标签名称和文件路径 ## 插件组件模式站点插件使用本机“HTMLElement”自定义元素： // 我的网站插件.tsx 类 MyElement 扩展 HTMLElement { 静态获取观察属性（）{ return ['显示名称']; } 构造函数（）{ 超级（）； } 连接回调() { this.render(); } 属性更改回调() { this.render(); } 渲染（）{ const displayName = this.getAttribute('显示名称') || “你的插件的标题”； this.innerHTML = `

${显示名称}

<小时/>

这是一个由 Wix CLI 生成的站点插件。
编辑元素的代码以更改此文本。

`; } } 导出默认的 MyElement； **要点：** * 直接扩展`HTMLElement`类 * 定义 `observedAttributes` 静态 getter 来列出反应性属性 * 属性使用 **kebab-case** （例如，`display-name`、`bg-color`） * 为初始渲染实现“connectedCallback()” * 实现 `attributeChangedCallback()` 以在属性更改时重新渲染 * 通过模板字符串使用内联样式 * 使用 `this.getAttribute('attribute-name')` 读取属性值 * Wix 为您处理 `define()` — 不要在代码中调用 `customElements.define()` ## 设置面板图案 // my-site-plugin.panel.tsx 导入 React, { type FC, useState, useEffect, useCallback } from 'react'; 从'@wix/editor'导入{widget}；导入{ 侧面板， WixDesignSystemProvider, 输入，表单字段，来自“@wix/design-system”；导入'@wix/design-system/styles.global.css'; 常量面板： FC = () => { const [displayName, setDisplayName] = useState(''); 使用效果（（）=> { widget.getProp('显示名称') .then(displayName => setDisplayName(displayName || "您的插件标题")) .catch(error => console.error('无法获取显示名称：', error)); }, [设置显示名称]); const handleDisplayNameChange = useCallback((事件: React.ChangeEvent) => { const newDisplayName = event.target.value; 设置显示名称（新显示名称）； widget.setProp('显示名称', newDisplayName); }, [设置显示名称]); 返回（ <侧面板宽度=“300”高度=“100vh”> <侧面板.字段> <输入类型=“文本” 值={显示名称} onChange={handleDisplayNameChange} aria-label="显示名称" /> ）； }; 导出默认面板； **要点：** * `widget.getProp()` 和 `widget.setProp()` 中的 Prop 名称使用 **kebab-case** （例如，`"display-name"`） * 始终更新 onChange 处理程序中的本地状态和 widget 属性 * 小部件属性绑定到自定义元素属性 - 更改会自动更新相应的属性 * 将内容包裹在 `WixDesignSystemProvider > SidePanel > SidePanel.Content` 中 * 使用来自`@wix/design-system`的WDS组件 * 导入 `@wix/design-system/styles.global.css` 样式 * 包含“aria-label”以实现可访问性 ## 颜色和字体选择器字段站点插件设置面板可以使用“@wix/editor”中的“inputs.selectColor()”和“inputs.selectFont()”来打开本机Wix编辑器颜色和字体选择器对话框。 ### ColorPickerField 打开包含主题颜色、渐变等的 Wix 颜色选择器 — **不是**基本的 HTML ``。导入 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); } })} /> ）； ### FontPickerField 打开 Wix 字体选择器，其中包含字体系列、大小、粗体、斜体和其他排版功能。导入 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 || "" }) })} 全宽 > 更改字体）； **重要：** * 始终使用 `@wix/editor` 中的 `inputs.selectColor()` 和 `FillPreview` — 不要使用 `` * 始终使用 `@wix/editor` 中的 `inputs.selectFont()` 以及回调模式 `inputs.selectFont(value, { onChange })` * 从“@wix/editor”导入“inputs”（而不是从“@wix/sdk”） ## 属性命名约定站点插件对 HTML 属性一致使用 **kebab-case**：文件|大会 |示例 ---|---|--- `<插件>.tsx` (getAttribute) |烤肉串盒 | `this.getAttribute('显示名称')` `<插件>.tsx` (observedAttributes) |烤肉串盒 | `['显示名称','背景颜色']` `.panel.tsx`（小部件 API）|烤肉串盒 | `widget.getProp('显示名称')` ## 输出结构站点插件位于“src/extensions/site/plugins”下。每个插件都有自己的文件夹，其中包含以插件命名的文件。 src/扩展/站点/插件/ └── {插件名称}/ ├── {plugin-name}.tsx # 主要插件组件(HTMLElement) ├── {plugin-name}.panel.tsx # 设置面板组件 └── {plugin-name}.extension.ts # 扩展注册公共/ └── {plugin-name}-logo.svg # 插件徽标（可选） ## 参考文献主题 |参考 ---|--- 完整示例 | [示例.md]() 插槽（应用程序 ID、多个展示位置、查找插槽）| [SLOTS.md]() WDS 组件 | [wds-docs]() ## 可用插槽站点插件集成到 Wix 业务解决方案中的预定义插槽中。每个插槽通过以下方式标识： * **appDefinitionId** ：Wix 应用程序的 ID（例如，商店、预订） * **widgetId** : 包含槽的页面的ID * **slotId** : 特定槽位标识符常见的放置区域包括产品页面（Wix Stores）、结帐和侧边购物车（Wix eCommerce）、预订页面（Wix Bookings）、服务页面、活动页面和博客文章页面。有关支持的页面、常见的 Wix 应用程序 ID 以及如何查找插槽 ID，请参阅 [SLOTS.md]()。 ## 扩展注册 **扩展注册是强制性的，并且需要两个步骤。** ### 第 1 步：创建特定于插件的扩展文件每个站点插件都需要在其文件夹中包含一个扩展文件： // my-site-plugin.extension.ts 从'@wix/astro/builders'导入{扩展}；导出默认扩展.sitePlugin({ id: '{{GENERATE_UUID}}', name: '我的网站插件', 市场数据：{ name: '我的网站插件', 描述：“营销描述”， logoUrl: '{{BASE_URL}}/my-site-plugin-logo.svg', }, 展示位置：[{ appDefinitionId: 'a0c68605-c2e7-4c8d-9ea1-767f9770e087', widgetId: '6a25b678-53ec-4b37-a190-65fcd1ca1a63', slotId: '产品页面详细信息-6', }], 安装：{ autoAdd：true }， tagName: '我的网站插件', 元素：'./extensions/site/plugins/my-site-plugin/my-site-plugin.tsx'，设置：'./extensions/site/plugins/my-site-plugin/my-site-plugin.panel.tsx', }); **关键：UUID 生成** `id` 必须是唯一的静态 UUID v4 字符串。为每个扩展生成一个新的 UUID - 不要使用“randomUUID()”或从示例中复制 UUID。将“{{GENERATE_UUID}}”替换为新生成的 UUID，例如“95a28afd-7df1-4e09-9ec1-ce710b0389a0”。物业 |类型 |描述 ---|---|--- `id` |字符串|唯一静态UUID v4（新鲜生成） `名称` |字符串|插件的内部名称 `marketData.name` |字符串|在插件资源管理器和应用程序仪表板中显示名称 `marketData.description` |字符串|插件资源管理器和应用程序仪表板中显示的说明 `marketData.logoUrl` |字符串|徽标文件的路径（“{{BASE_URL}}”解析为公共文件夹） `展示位置` |数组|可以添加插件的插槽位置数组 `placements.appDefinitionId` |字符串|包含插槽的 Wix 应用程序的 ID `placements.widgetId` |字符串|包含槽位的页面ID `placements.slotId` |字符串|特定槽位的ID `安装.autoAdd` |布尔 |是否在应用程序安装时自动将插件添加到插槽 `标签名称` |字符串| HTML 自定义元素标签（短横线大小写，必须包含连字符） `元素` |字符串|插件组件的相对路径 `设置` |字符串|设置面板组件的相对路径 ### 步骤 2：在主扩展文件中注册 **关键：** 创建插件特定的扩展文件后，您必须阅读 [wix-cli-extension-registration]() 并按照“应用程序注册”部分更新 `src/extensions.ts`。 **如果不完成步骤 2，站点插件将无法在插件资源管理器中使用。** ## 检查插件如果您正在为 **结账页面** 构建插件，它可能不支持安装时自动添加。您必须创建一个仪表板页面，以便为用户提供将插件添加到其站点的方法。有关仪表板页面模式，请参阅 [EXAMPLES.md]()。 ## 示例有关所有三个必需文件（插件组件、设置面板、扩展配置）的完整示例，请参阅 [EXAMPLES.md]()。 **用例示例：** * **畅销徽章** \- 产品页面上的可自定义徽章，带有文本和颜色设置 * **预订确认** \- 预订页面的自定义确认消息 * **产品评论摘要** \- 星级和评论计数显示 * **数据驱动插件** \- 具有 Wix 数据 API 集成和编辑器环境处理的插件 ## 最佳实践 ### 实施指南 * **使用内联样式** \- 自定义元素不支持 CSS 导入 * **处理编辑器环境** \- 在数据相关插件的编辑器模式下显示占位符 * **不要调用 `define()`** \- Wix 会自动为您处理 `customElements.define()` * **验证所有输入** \- 检查所需的道具是否存在 * **遵循命名约定** \- 所有属性和小部件 API 均采用短横线大小写 * **保持插件专注** \- 每个插件应该做好一件事 * **在多个插槽中测试** \- 如果支持多个放置，请测试每个位置 * **支持两个商店版本** \- 包括新旧 Wix 商店产品页面的展示位置，以实现最大兼容性 ### 编辑器沙箱站点插件在编辑器中呈现时会被沙箱化。这意味着它们被视为来自不同的域，这会影响对浏览器存储 API 的访问。 **编辑器中受限的 API：** * `localStorage` 和 `sessionStorage` (Web 存储 API) * `document.cookie`（Cookie 存储 API） * 索引数据库API * 缓存API **如何处理沙箱：** 在访问受限 API 之前，使用 @wix/site-window 中的 viewMode() 函数检查当前模式：从 '@wix/site-window' 导入 { window as wixWindow } ； const viewMode = 等待 wixWindow.viewMode(); if (viewMode === '站点') { const item = localStorage.getItem('myKey'); } 否则{ // 模拟存储或修改编辑器模式的 API 使用 } ### 在站点插件中使用 Wix SDK 模块站点插件可以直接导入和使用 Wix SDK 模块 - 您不需要`createClient()`。 Wix 运行时自动提供客户端上下文。 // ✅ 正确 — 直接导入 SDK 模块从“@wix/data”导入{items}；从“@wix/ecom”导入{ currentCart }；从“@wix/stores”导入{产品}；类 MyPlugin 扩展 HTMLElement { 异步加载数据() { // 直接调用 SDK 方法 — 无需 createClient const result = wait items.query("MyCollection").find(); const cart = 等待 currentCart.getCurrentCart(); const ProductList =等待产品.queryProducts().limit(10).find(); } } // ❌ 错误 — 不要在站点插件中使用 createClient 从“@wix/sdk”导入{createClient}； const wixClient = createClient({ 模块: { 项目, 产品 } }); 等待 wixClient.items.query(...); // 错误 — API 界面因客户端而异 ### 性能考虑因素 * 保持包大小较小 - 插件加载到面向用户的页面上 * 避免初始渲染时的繁重计算 * 尽可能延迟加载数据 * 使用高效的重新渲染模式

Wix CLI 站点插件

包含技能