wix-cli-embedded-script

Wix 嵌入式脚本构建器

为 Wix CLI 应用创建嵌入式脚本扩展。嵌入式脚本是注入 Wix 网站 DOM 的 HTML 代码片段，可用于集成第三方服务、跟踪分析数据、投放广告以及实现自定义 JavaScript 功能。

快速入门清单

创建嵌入式脚本时，请按顺序执行以下步骤：

1. 创建脚本文件夹：src/extensions/site/embedded-scripts/<script-name>/
2. 创建 embedded.html，其中包含配置元素、样式和脚本逻辑
3. 创建 extensions.ts，使用 extensions.embeddedScript() 并指定唯一 UUID
4. 创建控制面板配置页面：src/extensions/dashboard/pages/<script-name>-settings/
5. 使用 @wix/app-management 中的 embeddedScripts API 实现配置页面
6. 更新 src/extensions.ts，导入并使用这两个扩展
7. 在 Wix Dev Center 中添加 SCOPE.DC-APPS.MANAGE-EMBEDDED-SCRIPTS 权限（参见启用嵌入式脚本权限）

脚本类型

嵌入式脚本必须声明类型，以便进行同意管理：

类型	说明	使用场景
ESSENTIAL	网站运行所必需的核心功能	身份验证、安全功能
FUNCTIONAL	记住用户选择，以改善使用体验	语言偏好、UI 自定义
ANALYTICS	提供访客使用网站情况的统计数据	Google Analytics、Hotjar、Mixpanel
ADVERTISING	提供访客数据，用于营销目的	Facebook Pixel、Google Ads、再营销

**选择规则：**如果脚本符合多个类型，请选择列表中最靠后的选项（限制最严格）。例如，同时涉及分析和广告的脚本应设为 ADVERTISING。

放置位置选项

放置位置	说明	最适用场景
HEAD	位于 <head> 和 </head> 标签之间	分析、尽早初始化
BODY_START	紧接在 <body> 开始标签之后	关键功能、noscript
BODY_END	紧靠 </body> 结束标签之前	非阻塞脚本、性能优化

选择指南：

• 分析/跟踪 → HEAD（尽早初始化）
• 广告像素 → BODY_END（非阻塞）
• 关键功能 → HEAD 或 BODY_START
• 非关键功能 → BODY_END（性能更佳）

动态参数和控制面板配置

每个嵌入式脚本都需要配套的控制面板页面来配置参数。网站所有者通过控制面板页面 UI 设置值，这些值随后会作为模板变量传递给嵌入式脚本。

架构流程

Dashboard Page (React UI)
    │
    │  embeddedScripts.embedScript({ parameters: {...} })
    ▼
Wix App Management API
    │
    │  Stores parameters, injects as template variables
    ▼
Embedded Script (HTML)
    │
    │  {{parameterKey}} → actual value
    ▼
Site DOM

**相关技能：**使用 wix-cli-dashboard-page 为嵌入式脚本创建配置 UI。

参数类型

类型	说明	控制面板组件
TEXT	单行文本	输入框
NUMBER	数值	类型为 number 的输入框
BOOLEAN	真/假切换	ToggleSwitch、Checkbox
IMAGE	来自媒体管理器的图片	ImagePicker
DATE	仅日期	DatePicker
DATETIME	日期和时间	DatePicker + TimeInput
URL	带验证的 URL	输入框
SELECT	下拉选项	Dropdown
COLOR	颜色值	ColorPicker

模板变量语法

嵌入式脚本支持使用模板变量语法 {{variableName}} 进行参数化。这些参数通过控制面板配置，并作为模板变量传入，供你在 HTML/JavaScript 代码中使用。

使用说明：

1. 模板变量语法：

   • 使用 {{parameterKey}} 语法将参数值插入 HTML
   • 模板变量可用于 HTML 属性
   • 注入脚本时，它们会被实际值替换

2. HTML 属性（必需）：

   • 将所有参数值存储在配置元素的数据属性中
   • 模板变量只能在此处使用，不能直接用于 JavaScript
   • 示例：<div id="config" data-headline="{{headline}}" data-text="{{text}}"></div>

3. JavaScript 访问方式：

   • JavaScript 必须从数据属性中读取参数值
   • 使用 getAttribute() 或 dataset 属性
   • 示例：

     const config = document.getElementById("config");
     const headline = config?.getAttribute("data-headline");
     // OR using dataset:
     const { headline, text } = config.dataset;
     

4. 类型安全：

   • 在 JavaScript 中使用参数时，请留意其类型
   • NUMBER 类型：使用 Number() 或 parseInt() 转换
   • BOOLEAN 类型：与 'true' 或 'false' 字符串进行比较
   • DATE/DATETIME：使用 new Date() 解析

5. 必填与可选参数：

   • 必填参数始终有值
   • 可选参数可能为空，请妥善处理
   • 为可选参数提供备用值

6. 使用相关参数：

   • 仅使用与当前用例相关的动态参数
   • 忽略与所实现功能无关的参数
   • 使用的每个参数都应在脚本功能中发挥明确作用
   • 如果某些参数不适用，不使用它们也完全没问题

示例模式：

模式 1 - 在数据属性中配置：

<div
  id="script-config"
  data-api-key="{{apiKey}}"
  data-enabled="{{enabled}}"
  data-color="{{primaryColor}}"
></div>
<script>
  const config = document.getElementById("script-config");
  const apiKey = config.getAttribute("data-api-key");
  const enabled = config.getAttribute("data-enabled") === "true";
  const color = config.getAttribute("data-color");

  if (enabled && apiKey) {
    // Initialize with configuration
  }
</script>

模式 2 - 使用 dataset 属性：

<div
  id="script-config"
  data-headline="{{headline}}"
  data-message="{{message}}"
  data-image-url="{{imageUrl}}"
></div>
<script>
  const config = document.getElementById("script-config");
  const { headline, message, imageUrl } = config.dataset;

  // Use the variables in your script logic
  if (headline) {
    document.querySelector("#headline").textContent = headline;
  }
</script>

模式 3 - 条件逻辑：

<div
  id="config"
  data-mode="{{activationMode}}"
  data-start="{{startDate}}"
  data-end="{{endDate}}"
></div>
<script>
  const config = document.getElementById("config");
  const mode = config.getAttribute("data-mode");

  if (mode === "timed") {
    const startDate = new Date(config.getAttribute("data-start"));
    const endDate = new Date(config.getAttribute("data-end"));
    const now = new Date();

    if (now >= startDate && now <= endDate) {
      // Show content
    }
  } else if (mode === "active") {
    // Show content immediately
  }
</script>

验证要求：

• 仅使用与你的具体用例相关的动态参数
• 忽略与所实现功能无关的参数
• 模板变量 {{parameterKey}} 必须与参数定义中的键名完全一致
• 妥善处理必填参数和可选参数
• 当可选参数未设置时，提供合理的默认行为
• 确保使用方式符合参数类型（不要在未转换的情况下将 NUMBER 参数作为字符串使用）

常见参数

每个嵌入式脚本至少应包含一个启用/禁用开关参数：

参数	类型	用途
enabled	BOOLEAN	允许网站所有者启用或禁用
apiKey	TEXT	第三方服务凭据
trackingId	TEXT	分析/像素标识符
headline	TEXT	可自定义的显示文本
color	COLOR	UI 自定义

输出结构

完整的嵌入式脚本实现包含两部分：

1. 嵌入式脚本扩展

src/extensions/site/embedded-scripts/
└── {script-name}/
    ├── embedded.html     # HTML/JavaScript code to inject
    └── extensions.ts     # Metadata (scriptType, placement)

2. 控制面板配置页面（必需）

src/extensions/dashboard/
├── withProviders.tsx     # WDS provider wrapper (required)
└── pages/
    └── {script-name}-settings/
        ├── extensions.ts  # Extension registration (REQUIRED)
        └── page.tsx       # Configuration UI using embeddedScripts API

**注意：**控制面板页面需要自己的 extensions.ts 文件。没有此文件，控制面板页面就不会显示在 Wix 控制面板中。

**警告：**控制面板页面使用的字段名与嵌入式脚本不同：

• 控制面板页面使用 title、routePath、component
• 嵌入式脚本使用 name、source、placement、scriptType

不要将嵌入式脚本的字段名用于控制面板页面注册。

有关控制面板页面实现详情和扩展注册模式，请参阅 wix-cli-dashboard-page 技能。

实现模式

<div id="my-config" data-api-key="{{apiKey}}" data-enabled="{{enabled}}"></div>


<div id="my-container"></div>

<style>
  /* Scoped styles for the embedded content */
  #my-container {
    /* styles */
  }
</style>

<script type="module">
  // Get configuration from data attributes
  const config = document.getElementById("my-config");
  if (!config) throw new Error("Config element not found");

  const { apiKey, enabled } = config.dataset;

  // Exit early if disabled (use throw at module scope, not return)
  if (enabled !== "true") {
    throw new Error("Script disabled");
  }

  // Implement functionality in a named function (return is allowed here)
  async function initialize() {
    try {
      // Your implementation
    } catch (error) {
      console.error("Script error:", error);
    }
  }

  // Initialize when DOM is ready
  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", initialize);
  } else {
    initialize();
  }
</script>

示例

分析跟踪

请求：“在我的网站中添加 Google Analytics 跟踪”

输出：

• 脚本类型：ANALYTICS
• 放置位置：HEAD
• 模板变量：{{trackingId}}
• 实现内容：gtag.js 初始化、页面浏览跟踪

弹出窗口／模态框

请求：“创建一个购物车金额超过 $50 时显示的优惠券弹出窗口”

输出：

• 脚本类型：FUNCTIONAL
• 放置位置：BODY_END
• 模板变量：{{couponCode}}、{{minimumCartValue}}、{{enablePopup}}
• 实现内容：购物车金额检测、弹出窗口显示逻辑、用于“不要再次显示”的 localStorage

第三方聊天工具

请求：“集成 Intercom 聊天工具”

输出：

• 脚本类型：FUNCTIONAL
• 放置位置：BODY_END
• 模板变量：{{appId}}、{{userEmail}}、{{userName}}
• 实现内容：Intercom SDK 初始化、用户识别

最佳实践

• 始终创建一个仪表板页面： 每个嵌入式脚本都需要配置界面
• 包含启用／停用开关： 让网站所有者无需移除脚本即可控制是否启用
• 性能： 尽量降低影响——脚本应轻量且不阻塞
• 安全性： 避免使用内联事件处理程序，验证数据并转义用户输入
• 错误处理： 适当情况下静默失败——不要破坏网站
• 模块作用域的提前退出： 在模块作用域中使用 throw new Error() 提前退出，而不要使用 return。Rollup（Astro 使用的工具）不允许在模块作用域中使用 return 语句。将主要逻辑包装在命名的异步函数中，以便在有效的位置使用 return。
• 类型转换： 参数始终是字符串——根据需要在 JavaScript 中转换
• API 调用： 仅对 API 规范中存在的 /api/* 端点创建 fetch() 调用
• 作用域： 为 CSS 类和 ID 添加前缀，避免与网站样式冲突
• 清理： 适当情况下移除事件监听器和间隔定时器

完整示例：优惠券弹出窗口

1. 定义参数

Parameters for "cart-coupon-popup":
- couponCode (TEXT, required) - The coupon code to display
- popupHeadline (TEXT, required) - Headline text
- popupDescription (TEXT, required) - Description text
- minimumCartValue (NUMBER) - Minimum cart value to show popup
- enablePopup (BOOLEAN, required) - Enable/disable toggle

2. 嵌入式脚本（embedded.html）

<div
  id="popup-config"
  data-coupon-code="{{couponCode}}"
  data-popup-headline="{{popupHeadline}}"
  data-minimum-cart-value="{{minimumCartValue}}"
  data-enable-popup="{{enablePopup}}"
></div>
<div id="popup-container"></div>

<script type="module">
  // Get configuration from data attributes
  const config = document.getElementById("popup-config");
  if (!config) throw new Error("Config element not found");

  const { couponCode, popupHeadline, minimumCartValue, enablePopup } =
    config.dataset;

  // Exit early if disabled (use throw at module scope, not return)
  if (enablePopup !== "true") {
    throw new Error("Popup disabled");
  }

  // Main logic in a function (return is allowed here)
  async function initializePopup() {
    const minValue = Number(minimumCartValue) || 0;
    // ... popup implementation
  }

  // Initialize when DOM is ready
  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", initializePopup);
  } else {
    initializePopup();
  }
</script>

3. 仪表板页面（参见 wix-cli-dashboard-page 技能）

使用来自 @wix/app-management 的 embeddedScripts API：

import { embeddedScripts } from "@wix/app-management";

// Load parameters
const script = await embeddedScripts.getEmbeddedScript();
const params = script.parameters; // { couponCode: "...", ... }

// Save parameters (all values must be strings)
await embeddedScripts.embedScript({
  parameters: {
    couponCode: "SAVE20",
    minimumCartValue: "50", // Number as string
    enablePopup: "true", // Boolean as string
  },
});

扩展注册

扩展注册是强制要求，且必须完成两个步骤。

步骤 1：创建特定于脚本的扩展文件

每个嵌入式脚本都需要在其文件夹中包含一个 extensions.ts 文件：

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

export const embeddedscriptMyScript = extensions.embeddedScript({
  id: "{{GENERATE_UUID}}",
  name: "My Script",
  source: "./extensions/site/embedded-scripts/my-script/embedded.html",
  placement: "BODY_END",
  scriptType: "FUNCTIONAL",
});

重要：生成 UUID

id 必须是唯一且固定的 UUID v4 字符串。为每个扩展生成一个全新的 UUID——不要使用 randomUUID()，也不要复制示例中的 UUID。将 {{GENERATE_UUID}} 替换为新生成的 UUID，例如 "a1b2c3d4-e5f6-7890-abcd-ef1234567890"。

属性	类型	说明
id	string	唯一且固定的 UUID v4（生成全新的 UUID）
name	string	脚本的显示名称
source	string	HTML 文件的相对路径
placement	enum	HEAD、BODY_START 或 BODY_END
scriptType	enum	ESSENTIAL、FUNCTIONAL、ANALYTICS、ADVERTISING

步骤 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 Dev Center 中的手动操作。没有此权限，嵌入式脚本将无法在网站上运行。