salla-snippets

Salla 店面代码片段流程

通过执行操作与 Salla 店面事件集成。Device Mode 代码片段通过 Salla Partners MCP salla_snippets 工具注入；Cloud Mode 在 App Function 中运行。请按顺序完成这些步骤——完成每个关卡后再继续。

工具

工具	操作	功能
salla_snippets	list / parameters / create / update / delete	管理应用的店面代码片段

**前提条件：**必须已连接 Salla Partners MCP 服务，并且你需要应用的 app_id。Cloud Mode 作为 App Function 运行——编写和部署 → salla-app-functions。

---

Step 0 — 发现

开始前先询问：

1. 你想处理哪个店面事件？ （例如 cart::item.added、cart::updated、product::price.updated——Twilight 事件采用 :: 命名空间；请在目录中确认名称，参见 references/device-mode.md）
2. 事件触发时应该执行什么操作？ （跟踪分析数据、同步数据、触发自动化、个性化内容）

根据答案确定 Step 1 中的正确模式。

---

Step 0.5 — 检测旧版内容（仅限 Device Mode）

搭建框架前，检查收到的所有代码片段内容（粘贴的内容、从 Portal 导出的内容，或从现有代码片段中读取的内容）：

• 是否包含 HTML 标签（<script、<style、<div、<link、<iframe 等）？
• 是否包含 {{namespace.key}} 标记（Twig 风格的双大括号）？

如果任一项为是，则这是旧版服务端模板流水线中的内容——请在此停止。交由 salla-snippets-migration 将其转换为纯 JS，然后从下面的 Step 2 继续处理转换后的输出。不要尝试手动修补 HTML/Twig 内容，使其看起来像是可能可以解析的内容——转换遵循实际规则（参数模型、salla.onReady 时机），应由该技能负责。

**关卡：**继续执行 Step 2 前，确保内容不包含 HTML 标签和裸 {{...}} 标记。

---

Step 1 — 选择集成模式

模式	运行位置	最适用于
Device Mode	浏览器（tracker.js + Twilight SDK）	分析、个性化、营销归因
Cloud Mode	服务器（App Functions）	自动化、数据同步、可靠的后端交付

决策规则：

• 需要实时浏览器数据或营销像素 → Device Mode
• 需要保证交付、后端逻辑或 API 调用 → Cloud Mode

如果仍不明确，请询问："应该在浏览器还是在你的服务器上运行？"

关卡：“已确认模式。正在继续搭建框架。”

---

Step 2 — 搭建实现

设备模式

代码片段正文通过 Twilight SDK 在店面浏览器中运行。编写监听器， 然后使用工具将其注入为店面代码片段：

1. 将代码片段正文编写为纯 JavaScript——代码片段是 Salla 从 CDN 提供的纯 JS 文件， 通过 <script src> 加载到每个店面页面中。直接使用 salla、 salla.onReady、salla.event 和 salla.config.get(...)。（完整规则——不使用 Twig/HTML 包装、引导时机、部署防护 → references/device-mode.md。）

   代码片段承担两个不同的任务——请分开处理：

   • 监听店面事件（命名空间使用 ::；负载位于 e.data）。在模块顶层注册 监听器，以免错过初始化时触发的事件：

     salla.event.on("cart::item.added", (e) => {
       var productId = e.data.product_id; // 负载位于 e.data
     });
     

     事件目录和负载结构 → references/device-mode.md。

   • 读取应用的设置，使用 salla.config.get("app.<key>")——这是从店面代码片段 读取商家应用设置的唯一方式，且只有标记为 public: true 的设置才能在此处读取。 请在 salla.onReady 中执行店铺状态读取：

     salla.onReady(function () {
       var rewardsOn = salla.config.get("app.rewards_enabled") || false;
       var pointValue = salla.config.get("app.point_value_halalah") || 0;
     });
     

     设置代表商家如何配置应用；事件代表购物者正在做什么。请在 salla-app-settings 中定义这些键以及哪些键为 public。 店铺/会话配置（user.id、user.email——购物者，store.username、整个 store/user 对象）以及防御式读取模式 → references/device-mode.md 中的 店铺上下文和语言。禁止使用 customer.* 和 store.domain——这些字段已弃用/移除，切勿使用（完整规则见 references/device-mode.md）。

2. （可选）检查可用的模板变量：salla_snippets action=parameters、 app_id。

3. 注入代码片段：salla_snippets action=create、app_id、name（必填）、place （"before"——唯一可接受的值）、tag（仅限 "body"——代码片段会在 </body> 之前渲染）、content（纯 JS）。先去重： 调用 salla_snippets action=list， 在创建之前对该应用已有的代码片段执行 update/delete——叠加的重复代码片段会导致 UI 重复渲染、事件重复触发。使用 salla_snippets action=list / get 回读：它会返回包含 CDN url（.js 文件）和 path 的代码片段元数据。update 会重新验证完整的代码片段——请一并重新发送 name、place、tag 和 content（它不是部分补丁）。action=update 会返回确认信息 （{ snippet: { id, name, updated } }）；请使用 action=list 获取实时 CDN url。

   只能通过 salla_snippets MCP 工具管理代码片段——该工具负责字段映射 和验证（会将 content 映射到底层字段）。每项代码片段操作都必须通过它的某个操作完成。

设备模式设置、完整事件目录、负载结构 → references/device-mode.md

每次创建／更新时都进行验证（闭环）

成功执行 salla_snippets create／update 是验证的开始，而不是结束——200 仅表示文件已部署，不代表它能正常运行。将**每次 create／update**都视为触发一次循环，并重复执行，直到全部通过：

1. 解析为 JS 检查（在执行 create／update 前完成）——确认 content 可解析为有效的 JavaScript，与 Portal 编辑器在允许保存前执行的检查相同：例如运行 node --check snippet.js，或在 try/catch 中执行 new Function(code)。要解析代码，不要进行模式匹配——<script> 标签、HTML 和 Twig（{{ … }}／{% … %}）都无法解析为 JS，因此会被自动检测到，因为代码片段会以 .js 文件形式提供。保存前修复所有语法错误；MCP 不再检查内容格式，因此作者有责任确保正文能被正确解析。→ references/device-mode.md。
2. 禁用参数检查——在内容中搜索 salla.config.get("customer／salla.config.get('customer 和 salla.config.get("store.domain／salla.config.get('store.domain。只要匹配任何一项就拒绝，不设例外——customer.* 和 store.domain 已弃用／移除，且没有可直接替代的参数（完整目录 → references/device-mode.md中的 Store context & language）。user.* 是不同的概念（指购物者），并非一对一的重命名目标——重写前，请根据该目录检查代码片段实际需要哪些数据；如果文档中 user.*／store.* 没有提供所需的确切数据，那么这些数据在客户端不可用，不要凭空编造路径。
3. 配置键检查——对于代码片段读取的每个 salla.config.get("app.<key>")，确认 <key> 是应用设置中已定义且标记为 public: true 的设置。缺失或未标记为 public 的键，在商店前台读取时会返回 undefined。设置定义了契约 → 与 salla-app-settings 交叉核对。
4. 浏览器测试——运行下方的 DevTools 控制台操作步骤（加载标记、无错误、符合预期的 e.data 和配置值）。
5. 修复 → 通过工具再次执行 update → 再次验证，直到以上四项全部通过。

在浏览器中测试代码片段

代码片段在购物者的浏览器中运行，因此 salla_snippets 返回 200 只能证明它已部署——请通过 DevTools Console 在真实浏览器中证明它确实在运行。

1. 打开店铺前台。 先将应用安装到演示店铺（→ salla-live-testing），然后打开该店铺的 url 并 导航到代码片段运行的页面。如果可以，使用无头浏览器 （Playwright/Puppeteer）操作；否则，请逐步引导用户打开该页面和 DevTools Console（以及 Network 标签页）。

2. 添加调试日志。 为代码片段添加检测代码，以便查看执行情况和数据——包括加载标记、读取的设置以及每个事件负载：

   (function () {
     console.log("[myapp] snippet loaded");
     salla.event.on("cart::item.added", function (e) {
       console.log("[myapp] cart::item.added", e.data); // real payload shape
     });
     salla.onReady(function () {
       console.log(
         "[myapp] rewards_on",
         salla.config.get("app.rewards_enabled"),
       );
     });
   })();
   

3. 触发并验证。 执行相应操作（例如，将商品加入购物车），然后在控制台中确认：已记录加载标记、没有红色错误、处理程序记录了预期的 e.data，且 salla.config.get("app.<key>") 的值符合预期。

4. 根据控制台诊断问题：

   你看到的情况	含义	处理方法
   没有任何日志	代码片段未在此店铺启用 / 页面未重新加载 / 页面上没有 SDK	确认它已部署到此店铺，重新加载，并在触发 salla.onReady 的页面上运行
   salla.config.get("app.<key>") 的值为 undefined	设置不是 public，或键名错误	将其标记为 public: true（salla-app-settings）/ 修正键名
   处理程序从未触发	事件名称错误	检查 references/device-mode.md 中的 :: 目录

5. 发布前： 移除调试用的 console.log，或为其添加保护，并确保日志中不包含机密信息/PII（该文件会提供给每位购物者）。

Twilight JS SDK（用于应用代码片段）

Twilight 主题引擎会在每个店铺前台页面（body:end 钩子）自动注入 Twilight Storefront JS SDK（window.salla）。你的代码片段在同一页面中运行，因此可以调用相同的运行时 API——auth、cart、wishlist、product、order、rating、currency、loyalty、comment、profile、booking、salla.api.component.*、salla.config、salla.event、salla.storage、salla.notify、salla.lang、salla.helpers、metadata。

方法目录（签名、各模块文档链接、应用代码片段与主题的边界、salla.init() 规则）→ references/twilight-js-sdk.md。 事件（:: 目录、product::fetch.succeeded 陷阱、价格编码）→ references/device-mode.md。

衔接： 此技能对应购物者的浏览器（通过代码片段处理客户端操作/事件）。如需对同一活动进行服务端响应，请遵循可挂接规则——若是带有 App Function 触发器的服务端事件 → App Function （salla-app-functions，服务端 V8 isolate，优先使用）；否则 → webhook （salla-webhooks）。原生可见 UI → salla-storefront-ui。

店面 UI 合规性（代码片段渲染可见 UI 时）

当代码片段在页面上绘制内容时，请使用 Salla 原生 UI 组件 （Twilight <salla-*> Web 组件）构建 UI，并通过 Storefront JS SDK 驱动，而不是手写 HTML。原生组件会自动继承主题的设计令牌、RTL 和语言区域设置，因此看起来就像商店的一部分，而不是独立的 SaaS 徽章。

• 使用 <salla-*> 组件进行渲染。 插入文档中列出的标签并设置其属性 /属性值，例如 <salla-button>、<salla-modal>、<salla-rating-stars>、 <salla-quantity-input>、<salla-products-slider>。在 UI 组件目录中确认准确的标签和属性 （组件系列见下文）。主题会在每个店面页面上注册这些组件；如果目标商店缺少某个组件，请在使用前从 CDN 在运行时加载 loader（@salla.sa/twilight-components ESM loader）。
• 通过 SDK 接入行为逻辑——使用 salla.config.get(...) 读取状态，通过 salla.event.on(...) 响应事件，调用 salla.cart.* / salla.product.* 等。（方法目录 → references/twilight-js-sdk.md）。
• **对于仍需编写的自定义标记，**继承 Twilight CSS 变量 （--color-primary、--color-text、--font-main、间距/圆角），使用 Salla Icons （sicon-* 类），匹配周围的间距/密度，并遵循 dir/lang（优先考虑阿拉伯语/RTL）。 硬编码的字体/颜色/边框/阴影仅作为后备方案。
• 进行线上验证——打开一个已安装应用的演示商店（salla_apps action=demo_stores → url），并截取商品页面。代码能“运行”并不能证明页面显示正确。

salla-storefront-ui 负责“使用原生组件 + 原生外观”规则（以及线上验证门槛）——请遵循其中的完整指南： salla-storefront-ui。

UI 组件系列（均为 <salla-*>；完整目录见文档）：

系列	示例
商品	salla-product-card、salla-products-slider、salla-add-product-button
购物 / 购物车	salla-quantity-input、salla-quick-buy、salla-cart-summary
用户 / 身份验证	salla-login-modal、salla-userprofile、salla-verify
表单 / 输入	salla-tel-input、salla-datetime-picker、salla-file-upload
元素 / 布局	salla-button、salla-modal、salla-rating-stars、salla-tabs

文档：UI Components 概览 https://docs.salla.dev/422688m0.md · 用法 https://docs.salla.dev/422689m0.md · 自定义 https://docs.salla.dev/422690m0.md · Storefront JS SDK https://docs.salla.dev/422610m0.md · 主题 https://docs.salla.dev/421877m0.md · CSS 变量 https://docs.salla.dev/421945m0.md · Salla Icons https://docs.salla.dev/422550m0.md · 单商品页面 https://docs.salla.dev/422561m0.md。

云模式

云模式属于 App Function——将店面事件设为触发器来编写处理程序，并从头到尾遵循 salla-app-functions 技能（模板、Resp API、类型化上下文、部署）。请勿在此处重复其模板。

门槛：“测试事件：从演示商店触发事件，并确认处理程序正确触发。”

---

危险信号

容易产生的想法	为什么这是错的
“我只要去掉 HTML 标签继续处理就行了，内容大多已经是 JS 了”	旧版内容有实际的转换规则（参数模型、salla.onReady 时序）——手动修补会跳过这些规则，导致部署后读取错误或未定义。请转交给 salla-snippets-migration。
“我的测试中 customer.email 能正常读取，直接发布吧”	无论调用是否恰好能解析，customer.* 都是禁止使用的——它已弃用或移除，而非风格选择。请使用 user.*（购物者）。
“只有一个旧版 {{store.id}} 标记，先留着，其他的我会修好”	内容必须能解析为有效的 JS 才能部署——{{ }} 会以字面文本的形式发布并破坏脚本（或导致 salla_snippets 保存失败）。请在保存前转换所有标记。

---

资源

主题	链接
设备模式用法	https://docs.salla.dev/1724504m0.md
云模式用法	https://docs.salla.dev/1724667m0.md
应用函数概览	https://docs.salla.dev/1726814m0.md
应用函数事件	https://docs.salla.dev/1726818m0.md
应用代码片段概览	https://docs.salla.dev/2220706m0.md
HTML→JS 迁移指南	https://docs.salla.dev/2247590m0.md