salla-embedded-ui

Salla 嵌入式界面

为嵌入式应用提供原生的外观与体验——在 Embedded SDK 设计系统中呈现的商家后台 iframe。本技能仅负责原生样式，其指导原则是必须遵循的指令，而非参考资料：以下每条规则都是硬性要求；遗漏任何一条，都会让商家后台中出现风格格格不入的 iframe。“能渲染”不是标准——“在两种主题和 RTL 下都看起来原生，并经实时截图验证”才是。

店面 UI 使用不同的设计系统 → salla-storefront-ui。 SDK 启动、页面注册和身份验证请参阅 → salla-embedded-app。

⛔ 后台审核拒绝通知 这是 Salla 官方设计指南。明显违反指南的应用可能会在后台审核期间被拒绝——请将以下每个检查关卡都视为后台审核检查项，而不是建议。

本技能的适用范围

后台 iframe 中的任何可见 UI。如果你正在接入 embedded.init()、注册页面或验证身份验证令牌，请参阅 salla-embedded-app——从开始绘制 UI 的那一刻起，就应回到本技能。不要依据通用知识先设计样式再补改：从第一行标记开始，就应围绕这些规则设计 UI。

身份验证不可妥协，且由其他技能负责。 所有面向商家的界面（iframe 及其调用的任何后端）都必须运行经过身份验证且由服务器验证的会话——绝不能仅信任 iframe 上下文。会话／令牌验证 → salla-embedded-app；OAuth／商家令牌 → salla-app-auth。本技能仅负责外观与体验。

---

步骤 0 — 加载权威设计指南（首先执行）

在编写任何标记之前，加载唯一权威的令牌／模式来源，并保持打开： ../salla-embedded-app/references/design-guidelines.md — 品牌颜色令牌（浅色／深色十六进制值 + HSL）、PingARLT 字体比例、4px 间距网格、Hugeicons、无镀铬规则、组件模式（卡片／按钮／页面）以及“应做／不应做”表格。不要自行编造令牌值、猜测品牌青绿色，也不要在上下文压缩后凭记忆沿用颜色——请从该文件中读取。 在线文档：https://docs.salla.dev/embedded-sdk/design-guidelines.md · 演练场：https://docs.salla.dev/embedded-sdk/playground.md

步骤编号说明： design-guidelines.md 是为 salla-embedded-app 编写的——该文件中任何“SKILL.md 第 N 步”的引用都指向_该技能_的步骤，而非本技能的步骤。 有关身份验证／会话，请参阅 salla-embedded-app 步骤 3；有关主题接入，请参阅本技能的步骤 1。

检查关卡： 已加载 design-guidelines.md，并使用其中的精确令牌／模式——而非凭记忆或临时编造的值？

---

步骤 1 — 根据 embedded.init() 设置主题、语言区域和方向

从 embedded.init() 的 layout 中读取主题／语言区域／dir（参见 salla-embedded-app 步骤 4）——绝不能使用自行解析的查询参数。在初始化时将 dir／lang／data-theme 设置到 <html> 上，并在 embedded.onThemeChange 触发时以及每次重新初始化／刷新时重新应用。

检查关卡： dir、lang 和 data-theme 是否都来自 layout，并会在实时主题切换时重新应用？

---

第 2 步 — 通过 SDK 模块使用原生界面框架（No-Chrome 规则）

iframe 位于仪表板自身的界面框架内。不要重复构建。所有主机级交互都使用 SDK 模块，而不是自定义 iframe 内界面：

• 标题 → embedded.page.setTitle()（不要在 iframe 内添加页面标题栏）。
• 主要操作 → embedded.nav.setAction()（不要在页面内重复添加“保存”按钮）。
• 反馈 → embedded.ui.toast / embedded.ui.confirm() / embedded.ui.loading.show() + .hide()（绝不要使用 window.confirm()、自定义 Toast 覆盖层或自定义加载动画）。
• 面包屑 → 对于聚焦/全屏流程，使用 embedded.ui.breadcrumbs.hide()； 退出时使用 embedded.ui.breadcrumbs.show() 恢复。不要在 iframe 内添加面包屑导航。
• 不要添加侧边栏或 iframe 内顶部导航栏 — 内容应铺满容器宽度。

调用 SDK 方法，绝不要直接使用 postMessage。模块参考 → ../salla-embedded-app/references/sdk-modules-guide.md。

**检查项：**没有自定义侧边栏/导航栏/面包屑/确认框/Toast — 所有这些功能都通过 page/nav/ui SDK 方法实现了吗？

---

第 3 步 — 匹配仪表板：设计令牌、字体、间距、图标

使用设计指南中的设计令牌，让应用与原生仪表板区块无法区分：

• 颜色 — 使用仪表板品牌令牌（--color-primary 青绿色、--color-danger 等）；必须同时定义浅色和深色主题。不要使用与品牌不符的硬编码颜色。
• 字体 — PingARLT 字体栈、14px 基准字号，以及 text-xs…text-xl 字号比例。
• 间距 — 使用 4px 网格（space-1…space-8）。
• 图标 — 仅使用 Hugeicons（hgi hgi-stroke hgi-*）；描边粗细保持一致；使用与 SDK 的 nav.setAction 预期相符的类名。
• 组件 — 使用 design-guidelines.md 中的卡片/按钮/页面模式；border-radius、border 和阴影必须完全匹配 — 不要设计专属形状。
• 文案 — 所有可见标签都必须提供 ar 和 en 两种语言；绝不能只提供英文，让阿拉伯语商户无法使用。

**检查项：**每种颜色/字体/间距/图标都能对应到设计指南中的令牌，每个组件的形状都符合设计指南中的模式，浅色和深色主题均清晰易读，并且每个可见标签都有 ar 和 en 两种文案吗？

---

第 4 步 — 确保 RTL 正确性（阿拉伯语优先）

大多数商户使用阿拉伯语 — RTL 是默认情况，不是边缘情况。到处使用 CSS 逻辑属性 （margin-inline-start、padding-inline、border-inline-start）；绝不要使用 left/right 或全局 text-align: left。使用 dir="rtl" 验证，而不仅仅是验证 LTR。

**检查项：**在 dir="rtl" 下，布局能否正确镜像，且没有 left/right 物理属性，也没有全局 text-align: left？

---

第 5 步 — 在已安装的演示商店中进行 LIVE 验证（必需）

代码能够运行，并不能证明页面显示正确。在声称完成之前：

1. 执行 salla_apps action=demo_stores，打开某个商店的 install_url，然后打开其 dashboard_url。
2. 截取你构建的嵌入式页面在真实仪表板中的截图。
3. 根据该截图填写合规报告模板进行确认。

检查项（最终项）：“是否已在已安装的演示商店中截取此嵌入式页面的 LIVE 截图，并确认原生 SDK 界面框架 + Hugeicons + 仪表板设计令牌 + 正确的 RTL 在浅色和深色主题下均正常 — 而不只是确认代码运行了？”

使用 references/compliance-report-template.md 中的模板输出合规报告 — 根据 LIVE 截图为每个检查项填写 ✅/❌，并交还给开发者。

常见误区

容易产生的想法	错在哪里
“能渲染、代码也能运行——这就完成了。”	能渲染 ≠ 原生。只有步骤 5 中的实时截图才能证明这一点。
“我足够了解 Salla 的蓝绿色，可以直接写出来。”	猜测或凭记忆写出的十六进制颜色会偏离品牌规范，在深色模式下也会出问题。请从 design-guidelines.md 中读取每个令牌（步骤 0）。
“我会在 iframe 中加个小标题栏或保存按钮。”	这是嵌套仪表板的反模式。标题 → page.setTitle，操作 → nav.setAction——必须遵循无 Chrome 界面原则（步骤 2）。
“暂时用 window.confirm() / 自己做的 Toast 也可以。”	体验会变得零散。请使用 ui.confirm() / ui.toast / ui.loading.show()——始终使用 SDK 方法（步骤 2）。
“等英语版本可用后，我再处理 RTL。”	RTL 是商家的默认情况。从一开始就使用逻辑属性（步骤 4）。
“浅色模式看起来没问题，可以发布了。”	深色模式可实时切换。完成前必须确保两种主题都清晰易读（步骤 3 + 步骤 5）。
“英语标签对阿拉伯语商家来说足够清楚了。”	阿拉伯语是默认语言。每个标签都需要 ar 文案——仅提供英语无法通过双语检查（步骤 3）。

---

资源

主题	链接
权威令牌/模式（先加载）	../salla-embedded-app/references/design-guidelines.md
SDK 模块（page/nav/ui）	../salla-embedded-app/references/sdk-modules-guide.md
设计指南（实时版）	https://docs.salla.dev/embedded-sdk/design-guidelines.md
Playground / 测试	https://docs.salla.dev/embedded-sdk/playground.md