# Wix 嵌入式脚本生成器为 Wix CLI 应用程序创建嵌入式脚本扩展。嵌入式脚本是注入到 Wix 站点 DOM 中的 HTML 代码片段，支持与第三方服务、分析跟踪、广告和自定义 JavaScript 功能集成。 ## 快速入门清单创建嵌入脚本时请按顺序执行以下步骤： 1. 创建脚本文件夹： `src/site/embedded-scripts//` 2. 使用配置元素、样式和脚本逻辑创建“embedded.html” 3. 使用“extensions.embeddedScript()”和唯一的 UUID 创建“extensions.ts” 4. 创建仪表板配置页面： `src/dashboard/pages/-settings/` 5. 使用来自“@wix/app-management”的“embeddedScripts” API 实现配置页面 6. 更新 `src/extensions.ts` 以导入和使用这两个扩展 7. 在 Wix 开发中心添加 `SCOPE.DC-APPS.MANAGE-EMBEDDED-SCRIPTS` 权限（请参阅启用嵌入脚本权限） ## 脚本类型嵌入式脚本必须声明同意管理的类型：类型 |描述 |使用案例 ---|---|--- `基本` |对网站运营至关重要的核心功能 |身份验证、安全功能 `功能性` |记住用户选择以改善体验 |语言偏好、UI 定制 `分析` |提供有关访问者如何使用网站的统计数据 |谷歌分析、Hotjar、Mixpanel '广告' |提供访客数据用于营销目的 | Facebook Pixel、Google Ads、重定向 **选择规则：** 如果一个脚本分为多种类型，请选择最接近列表底部的选项（限制性最强）。例如，同时具有分析和广告方面的脚本应键入为“ADVERTISING”。 ## 放置选项安置|描述 |最适合 ---|---|--- `头` |在 `` 和 `` 标签之间 |分析、早期初始化 `BODY_START` |打开 `` 标签后立即 |关键功能，无脚本 `BODY_END` |紧接在关闭 `` 标记之前 |非阻塞脚本，性能 **选择指南：** * 分析/跟踪 → `HEAD`（提前初始化） * 广告像素→`BODY_END`（非阻塞） * 关键功能 → `HEAD` 或 `BODY_START` * 非关键功能 → `BODY_END`（更好的性能） ## 动态参数和仪表板配置 **每个嵌入式脚本都需要一个配套的仪表板页面**来配置其参数。网站所有者使用仪表板页面 UI 来设置值，然后将这些值作为模板变量传递到嵌入式脚本。 ### 架构流程仪表板页面（React UI） │ │ EmbeddedScripts.embedScript({ 参数: {...} }) ▼ Wix应用程序管理API │ │ 存储参数，作为模板变量注入 ▼ 嵌入脚本 (HTML) │ │ {{parameterKey}} → 实际值 ▼ 站点 DOM **相关技能：** 使用 `wix-cli-dashboard-page` 为您的嵌入式脚本创建配置 UI。 ### 参数类型类型 |描述 |仪表板组件 ---|---|--- `文本` |单行文本|输入 `数字` |数值|输入类型=“数字” `布尔值` |真/假切换 |切换开关、复选框 `图像` |图片来自媒体经理 |图像选择器 `日期` |仅限日期 |日期选择器 `日期时间` |日期与时间 |日期选择器 + 时间输入 `网址` |带有验证的 URL |输入 `选择` |下拉选项 |下拉菜单 `颜色` |颜值|颜色选择器 ### 模板变量语法嵌入式脚本支持使用模板变量语法“{{variableName}}”进行参数化。这些参数通过仪表板进行配置，并作为应在 HTML/JavaScript 代码中使用的模板变量传递。 **使用说明：** 1. **模板变量语法：** * 使用 `{{parameterKey}}` 语法将参数值插入 HTML * 模板变量在 HTML 属性中工作 * 注入脚本时，它们将被替换为实际值 2. **HTML 属性（必需）：** * 将所有参数值存储在配置元素的数据属性中 * 模板变量只能在这里使用，不能直接在 JavaScript 中使用 * 示例：`

` 3. **JavaScript 访问：** * JavaScript 必须从数据属性中读取参数值 * 使用 `getAttribute()` 或 `dataset` 属性 * 示例： const config = document.getElementById("config"); const header = config?.getAttribute("data-headline"); // 或者使用数据集： const { 标题, 文本 } = config.dataset; 4. **类型安全：** * 在 JavaScript 中使用参数类型时要注意它们 * NUMBER类型：使用`Number()`或`parseInt()`转换 * BOOLEAN 类型：与“true”或“false”字符串进行比较 * DATE/DATETIME: 用 `new Date()` 解析 5. **必需与可选：** * 必需的参数总是有值 * 可选参数可以为空——优雅地处理 * 为可选参数提供后备值 6. **相关参数使用：** * 仅使用与您当前用例相关的动态参数 * 忽略不适用于您正在实现的功能的参数 * 您使用的每个参数都应该在脚本的功能中有明确的用途 * 如果所有参数不适用，不使用它们也是完全可以的 **示例模式：** **模式 1 - 数据属性中的配置：**

<脚本> const config = document.getElementById("script-config"); const apiKey = config.getAttribute("data-api-key"); constenabled = config.getAttribute("data-enabled") === "true"; const color = config.getAttribute("数据颜色"); 如果（启用&& apiKey）{ // 使用配置进行初始化 } **模式 2 - 使用数据集属性：**

<脚本> const config = document.getElementById("script-config"); const { 标题、消息、imageUrl } = config.dataset; // 在脚本逻辑中使用变量如果（标题）{ document.querySelector("#headline").textContent = 标题; } **模式 3 - 条件逻辑：**

<脚本> const config = document.getElementById("config"); const mode = config.getAttribute("数据模式"); if (mode === "定时") { const startDate = new Date(config.getAttribute("data-start")); const endDate = new Date(config.getAttribute("data-end")); const now = new Date(); if (现在 >= 开始日期 && 现在 <= 结束日期) { // 显示内容 } } else if (mode === "active") { // 立即显示内容 } **验证要求：** * 仅使用与您的特定用例相关的动态参数 * 忽略不适用于正在实现的功能的参数 * 模板变量 `{{parameterKey}}` 必须与参数定义中的确切键名称匹配 * 适当处理必需参数和可选参数 * 在未设置可选参数时提供合理的默认行为 * 确保类型适当的使用（不要将 NUMBER 参数用作未经转换的字符串） ### 常用参数每个嵌入式脚本至少应该有一个**启用/禁用切换**参数：参数|类型 |目的 ---|---|--- `已启用` | `布尔值` |允许网站所有者激活/禁用 `apiKey` | `文本` |第三方服务凭证 `trackingId` | `文本` |分析/像素标识符 `标题` | `文本` |可定制的显示文本 `颜色` | `颜色` |用户界面定制 ## 输出结构完整的嵌入式脚本实现需要**两个部分**： ### 1\.嵌入式脚本扩展 src/site/embedded-scripts/ └── {脚本名称}/ ├──embedded.html#要注入的HTML/JavaScript代码 └──extensions.ts # 元数据（scriptType、placement） ### 2\.仪表板配置页（必填） src/仪表板/ ├── withProviders.tsx # WDS 提供程序包装器（必需） └── 页数/ └── {脚本名称}-设置/ ├── extensions.ts # 扩展注册（必需） └── page.tsx # 使用embeddedScripts API配置UI **注意：** 仪表板页面需要自己的“extensions.ts”文件。如果没有此文件，仪表板页面将不会出现在 Wix 仪表板中。 **警告：** 仪表板页面使用与嵌入脚本不同的字段名称： * 仪表板页面使用`title`、`routePath`、`component` * 嵌入脚本使用`name`、`source`、`placement`、`scriptType` 请勿将嵌入式脚本字段名称应用于仪表板页面注册。 **有关仪表板页面实现细节和扩展注册模式，请参阅`wix-cli-dashboard-page`技能**。 ## 实现模式

<风格> /* 嵌入内容的范围样式 */ #我的容器{ /* 样式 */ } <脚本类型=“模块”> // 从数据属性中获取配置 const config = document.getElementById("my-config"); if (!config) throw new Error("未找到配置元素"); const { apiKey, 启用 } = config.dataset; // 如果禁用则提前退出（在模块范围内使用 throw，而不是 return）如果（启用！==“真”）{ 抛出新错误（“脚本已禁用”）； } // 在命名函数中实现功能（此处允许返回）异步函数初始化() { 尝试{ // 你的实现 } 捕获（错误）{ console.error("脚本错误：", error); } } // 当 DOM 准备好时初始化 if (document.readyState === "正在加载") { document.addEventListener("DOMContentLoaded", 初始化); } 否则{ 初始化（）； } ## 示例 ### 分析跟踪 **请求：**“将 Google Analytics 跟踪添加到我的网站” **输出：** * 脚本类型：“分析” * 放置位置：`HEAD` * 模板变量：`{{trackingId}}` * 实现：gtag.js 初始化、页面浏览量跟踪 ### 弹出窗口/模态窗口 **请求：**“创建一个优惠券弹出窗口，当购物车价值超过 50 美元时显示” **输出：** * 脚本类型：`功能` * 位置：`BODY_END` * 模板变量：`{{couponCode}}`、`{{minimumCartValue}}`、`{{enablePopup}}` * 实现：购物车价值检测、弹出显示逻辑、“不再显示”的 localStorage ### 第三方聊天小部件 **请求：**“集成对讲聊天小部件” **输出：** * 脚本类型：`功能` * 位置：`BODY_END` * 模板变量：`{{appId}}`、`{{userEmail}}`、`{{userName}}` * 实现：对讲SDK初始化、用户识别 ## 最佳实践 * **始终创建仪表板页面：** 每个嵌入式脚本都需要一个配置 UI * **包括启用/禁用切换：** 让网站所有者控制激活而无需删除脚本 * **性能：** 最小化影响 - 脚本应该是轻量级且非阻塞的 * **安全性：** 避免内联事件处理程序、验证数据、转义用户输入 * **错误处理：** 在适当的时候静默失败 - 不要破坏网站 * **模块范围提前退出：** 使用 `throw new Error()` 在模块范围内提前退出，而不是 `return`。 Rollup（由 Astro 使用）不允许在模块范围内使用“return”语句。将主要逻辑包装在命名的异步函数中，其中“return”有效。 * **类型转换：** 参数始终是字符串 - 根据需要在 JavaScript 中进行转换 * **API 调用：** 仅创建对 API 规范中存在的 /api/* 端点的 fetch() 调用 * **范围：** 前缀CSS类和ID以避免与网站样式冲突 * **清理：** 在适当的时候删除事件侦听器和间隔 ## 完整示例：优惠券弹出窗口 ### 1\.定义参数 “购物车优惠券弹出”的参数： - couponCode (TEXT, required) - 要显示的优惠券代码 - popupHeadline (TEXT, 必需) - 标题文本 - popupDescription（文本，必需） - 描述文本 - 最小购物车价值（数字）- 显示弹出窗口的最小购物车价值 -enablePopup（布尔值，必需）-启用/禁用切换 ### 2\.嵌入脚本（`embedded.html`）

<脚本类型=“模块”> // 从数据属性中获取配置 const config = document.getElementById("popup-config"); if (!config) throw new Error("未找到配置元素"); const { 优惠券代码，popupHeadline，minimumCartValue，enablePopup } = 配置.数据集; // 如果禁用则提前退出（在模块范围内使用 throw，而不是 return） if (enablePopup !== "true") { 抛出新错误（“弹出窗口已禁用”）； } // 函数中的主要逻辑（此处允许返回）异步函数initializePopup() { const minValue = Number(minimumCartValue) || 0; // ... 弹出窗口实现 } // 当 DOM 准备好时初始化 if (document.readyState === "正在加载") { document.addEventListener("DOMContentLoaded",initializePopup); } 否则{ 初始化Popup(); } ### 3\.仪表板页面（参见 `wix-cli-dashboard-page` 技巧）使用来自“@wix/app-management”的“embeddedScripts” API：从“@wix/app-management”导入{embeddedScripts}； // 加载参数 const script =等待embeddedScripts.getEmbeddedScript(); const params = script.parameters; // { 优惠券代码: "...", ... } // 保存参数（所有值必须是字符串）等待嵌入脚本.embedScript({ 参数：{ 优惠券代码：“SAVE20”， minimumCartValue: "50", // 字符串形式的数字 enablePopup: "true", // 布尔值作为字符串 }, }); ## 扩展注册 **扩展注册是强制性的，并且需要两个步骤。** ### 第 1 步：创建特定于脚本的扩展文件每个嵌入脚本在其文件夹中都需要一个“extensions.ts”文件：从“@wix/astro/builders”导入{扩展}；导出 constEmbeddedScriptMyScript=extensions.embeddedScript({ id：“{{GENERATE_UUID}}”，名称：“我的脚本”，来源：“./site/embedded-scripts/my-script/embedded.html”，展示位置：“BODY_END”，脚本类型：“功能”， }); **关键：UUID 生成** `id` 必须是唯一的静态 UUID v4 字符串。为每个扩展生成一个新的 UUID - 不要使用“randomUUID()”或从示例中复制 UUID。将“{{GENERATE_UUID}}”替换为新生成的 UUID，例如“a1b2c3d4-e5f6-7890-abcd-ef1234567890”。物业 |类型 |描述 ---|---|--- `id` |字符串|唯一静态UUID v4（新鲜生成） `名称` |字符串|脚本的显示名称 `来源` |字符串| HTML 文件的相对路径 `放置` |枚举 | “HEAD”、“BODY_START”或“BODY_END” `脚本类型` |枚举 | “基本”、“功能”、“分析”、“广告” ### 步骤 2：在主扩展文件中注册 **关键：** 创建特定于脚本的扩展文件后，您必须阅读 [wix-cli-extension-registration]() 并按照“应用程序注册”部分更新 `src/extensions.ts`。 **如果不完成步骤 2，嵌入式脚本将不会部署到站点。** ## 启用嵌入脚本权限实施后，应用开发者必须手动启用嵌入脚本权限： 1. 转到 [https://manage.wix.com/apps/{app-id}/dev-center-permissions]()（将 `{app-id}` 替换为您的实际应用 ID） 2.添加`SCOPE.DC-APPS.MANAGE-EMBEDDED-SCRIPTS`权限 3. 保存更改 **注意：** 这是 Wix 开发中心中的手动步骤。如果没有此权限，嵌入式脚本将无法在网站上运行。

Wix Cli 嵌入脚本

包含技能