litium-developer

Litium 开发者

概述

在 Litium 平台上进行开发的合作伙伴开发者可使用此技能获取实施指导。此技能会将云部署相关工作交由 litium-cloud-cli 技能处理，并将将站点从 Litium 旧版云迁移到 Serverless Cloud 的工作交由 litium-cloud-migration 处理。对于其他所有 Litium 主题（包括 React Accelerator、MVC、数据建模和 API），此技能会按需加载参考文件。

在协助修改 Litium 平台文件之前，务必先阅读 references/partner-guidance.md。

委派

对于以下主题，请完全交由指定技能处理，不要在此处重复其内容：

主题	使用的技能
Litium Serverless Cloud 操作：部署、环境、应用和 YAML 清单、制品、密钥、访问控制、备份与还原、自定义域名、使用服务主体的 CI/CD	litium-cloud-cli
将现有站点从 Litium 旧版云（Windows/IIS、Web Deploy）迁移到 Serverless Cloud：评估、适配 Linux 的代码更改、使用旧版备份创建测试环境、转换流水线、演练和上线运行手册、MIGRATION.md	litium-cloud-migration

参考文件索引

仅当用户的任务涉及相应主题时，才阅读这些文件：

参考文件	用户询问以下内容时加载
references/partner-guidance.md	合作伙伴可以或不可以修改的内容、正确的扩展模式、内部 API 免责声明、受保护项目、NuGet 源、Elasticsearch 索引隔离
references/setup-empty-project.md	设置基础 Litium、空项目、安装基础平台、在本地下载 Litium、litemptyweb 模板
references/setup-mvc-accelerator.md	在本地安装 MVC Accelerator、litmvcacc 模板、yarn 构建、在后台部署 Accelerator
references/setup-react-accelerator.md	在本地安装 React Accelerator、litreactacc 模板、店面代理、.env.local、无头 Accelerator
references/setup-troubleshooting.md	设置错误、本地环境问题、安装失败、SQL 连接、证书、端口冲突、包还原
references/mvc-accelerator.md	MVC 开发、.NET 控制器、Razor 视图、视图模型、webpack 客户端构建、MVC + React 组件、Elasticsearch MVC
references/data-modelling.md	自定义字段类型、创建字段类型、字段模板、文件夹模板、产品模板、多字段、字段未包含在模板中、FieldTypeMetadataBase
references/cart-and-wishlist.md	购物车、结账、订单、愿望清单、addVariantToCart、createCheckoutSession、placeOrder、CartContext、BuyButton、支付小组件
references/apis.md	Admin Web API、Storefront GraphQL API、Connect ERP API、Payment API、Shipment API、Extension Management API、OpenAPI 规范
references/forum-api.md	搜索 forum.litium.com、社区解决方案、Discourse API、查找论坛帖子
references/react-accelerator/overview.md	React Accelerator 开发、Next.js 架构、服务端组件与客户端组件、GraphQL 模式、组件约定、测试
references/react-accelerator/template-routing.md	创建页面／产品／类别／区块模板、代理路由、[[...slug]] 捕获所有路由、模板命名约定
references/react-accelerator/code-patterns.md	React Accelerator 代码模式、queryServer、mutateClient、服务层、片段、Apollo Client 用法
references/react-accelerator/project-structure.md	React Accelerator 目录布局、app/、components/、services/、operations/ 文件夹
references/react-accelerator/graphql-sdl.md	获取 Storefront GraphQL SDL、下载架构、RUNTIME_LITIUM_SERVER_URL、可用操作
references/extension/cli-commands.md	搭建新扩展、create 命令、add 命令、dev 命令、@litiumab/platform-extension-sdk CLI
references/extension/manifest-reference.md	extension.manifest.json 字段、目标、common.web-component、admin.menu-item、admin.settings-page、api.proxy、customElementTag、bundleUrl
references/extension/bridge-api.md	window.litiumExtension、navigate()、replaceUrl()、showNotification()、getContext()、on()、off()、routeChanged、contextChanged
references/extension/framework-patterns.md	Custom Element 入口点、React 扩展、Vue 扩展、Angular 扩展、Vanilla 扩展、面板组件、Admin Web API 请求
references/extension/routing.md	子路径路由、MemoryRouter、createMemoryHistory、MemoryLocationStrategy、sub-path 属性、routeChanged、深层链接
references/extension/testing.md	扩展单元测试、模拟 window.litiumExtension、Vitest、Jest、@testing-library/react、@vue/test-utils
references/extension/deployment.md	安装扩展、启用扩展、Extension Management API、bundleUrl、HTTPS、CDN、Settings > Extensions、IIFE 包

文档搜索优先级

1. 主要来源：https://docs.litium.dev/ — 始终先查阅官方文档。
2. 社区来源：https://forum.litium.com/ — 查找实际解决方案；加载 references/forum-api.md 以通过程序搜索。

快速入门路由

步骤 0（始终执行）： 首先阅读 references/partner-guidance.md，了解合作伙伴可以和不可以修改的内容。

• “如何开发 React 店面？” → 首先阅读 references/react-accelerator/overview.md，然后根据需要加载特定参考文档（template-routing、code-patterns 等）。
• “如何部署／管理 Litium Cloud 环境？” → 委派给 litium-cloud-cli。
• “如何将网站从旧版云迁移到 Serverless Cloud？” → 委派给 litium-cloud-migration。
• “如何在本地设置 Litium？” → 加载匹配的设置参考文档（empty／MVC／React）。
• “如何添加购物车或愿望清单功能？” → 加载 references/cart-and-wishlist.md。
• “如何创建自定义字段类型或字段模板？” → 加载 references/data-modelling.md。
• “如何调用 Admin Web API 或 Connect API？” → 加载 references/apis.md。
• “如何构建后台 UI 扩展？” → 首先阅读 references/extension/cli-commands.md，然后根据需要加载特定参考文档（framework-patterns、bridge-api、routing 等）。
• “如何向扩展添加面板或设置页面？” → 加载 references/extension/cli-commands.md（始终使用 CLI，绝不手动创建文件）。
• “如何在扩展中导航或显示通知？” → 加载 references/extension/bridge-api.md。

后台 UI 扩展架构

扩展是作为 IIFE 包加载的 Web Components（自定义元素）。它们与 Angular 20 管理后台宿主完全隔离运行，可使用 React、Vue、Angular 或 Vanilla JavaScript。宿主只通过 window.litiumExtension 与扩展通信。

┌───────────────────────────────────────────────────────────┐
│  Litium Admin (Angular 20 host)                           │
│                                                           │
│  ┌─────────────────────────────┐                         │
│  │  <litium-ext-my-widget>     │  ← Custom Element       │
│  │                             │    (your extension)     │
│  │  ┌─────────────────────┐   │                         │
│  │  │   Your framework    │   │                         │
│  │  │   (React / Vue /    │   │                         │
│  │  │    Angular / Vanilla│   │                         │
│  │  └─────────────────────┘   │                         │
│  │            │               │                         │
│  │            ▼               │                         │
│  │  window.litiumExtension     │  ← Bridge API           │
│  └─────────────────────────────┘                         │
│              │                                            │
│  navigate() · showNotification() · getContext()           │
│  on('routeChanged') · on('contextChanged') · off()        │
└───────────────────────────────────────────────────────────┘

扩展关键规则

每个扩展都必须遵守这些规则。违反规则会导致运行时故障。

始终使用 CLI — 绝不手动创建文件

搭建新项目、添加面板或添加设置页面时，必须使用 @litiumab/platform-extension-sdk CLI（参见 references/extension/cli-commands.md）。不要手动创建组件文件、清单条目或索引导入 — CLI 会正确处理这三项。

只能在生成的组件文件中手动编写代码（实现 UI 逻辑）。

自定义元素标签命名

• 所有标签都必须以 litium-ext- 开头
• 主元素的模式：litium-ext-{extension-id}
• 面板：litium-ext-{extension-id}-panel-{slug}
• 必须匹配正则表达式：/^litium-ext-[a-z][a-z0-9-]*$/

添加 customElements.define 防护

if (!customElements.get('litium-ext-my-extension')) {
  customElements.define('litium-ext-my-extension', MyElement);
}

清理事件订阅

始终在 disconnectedCallback / onUnmounted / ngOnDestroy 中取消订阅 window.litiumExtension.on()。否则会导致内存泄漏。

绝不要在 routeChanged 处理程序中调用 navigate()

这会造成无限循环。只能响应用户操作调用 navigate()。

使用基于内存的路由

扩展不得直接调用 history.pushState。请使用 MemoryRouter（React）、createMemoryHistory（Vue）或 MemoryLocationStrategy（Angular）。

NPM 注册表配置

# .npmrc
@litiumab:registry=https://registry.npmjs.org/

扩展快速工作流

创建新扩展

1. 阅读 references/extension/cli-commands.md
2. 询问用户选择哪种框架：react、vue、angular 或 vanilla
3. 运行：npx @litiumab/platform-extension-sdk create <name> --framework <framework>
4. cd <name> && npm install
5. 阅读所选框架对应的 references/extension/framework-patterns.md
6. 启动开发服务器：npm run dev
7. 在 Litium 中注册：Settings > Extensions（参见 references/extension/deployment.md）

添加面板 / 设置页面

1. 阅读 references/extension/cli-commands.md
2. 在扩展项目根目录运行 npx @litiumab/platform-extension-sdk add panel 或 add settings-page
3. CLI 会生成组件文件、更新清单并注入导入语句
4. 对于设置页面：在框架路由器中添加路由（参见 references/extension/routing.md）

构建和部署

1. 阅读 references/extension/deployment.md
2. npm run build — 生成 dist/extension.js
3. 上传到 CDN 或托管服务（生产环境需要 HTTPS）
4. 更新 extension.manifest.json 中的 bundleUrl
5. 通过“设置 > 扩展”安装，或向 Extension Management API 发送 POST 请求

扩展常见错误

症状	根本原因	修复方法
管理 API 调用返回 403 Forbidden	在没有有效 bearer token 的情况下调用 /Litium/api/admin/	使用 VITE_LITIUM_CLIENT_ID 和 VITE_LITIUM_CLIENT_SECRET 请求 OAuth token，然后在 Authorization 标头中发送该 token
扩展空白 / 未渲染	清单与代码中的自定义元素标签不匹配	确保 customElements.define() 中的标签与清单中的 customElementTag 一致
返回按钮不起作用	使用框架路由器，而不是桥接 API	调用 window.litiumExtension.navigate() 进行跨边界导航
无限次重新渲染	在 routeChanged 处理程序中调用 navigate()	仅在响应用户操作时调用 navigate()
热重载错误：元素已定义	缺少 customElements.get() 防护	使用防护模式包装 customElements.define()
SDK 出现 npm ERR! 404 Not Found	缺少 .npmrc 注册表配置	将 @litiumab:registry=https://registry.npmjs.org/ 添加到 .npmrc
深层链接加载的是根页面	首次渲染时未读取 sub-path 属性	在 connectedCallback 中读取 getAttribute('sub-path')
切换频道后上下文过时	永久缓存 getContext() 的结果	订阅 contextChanged 事件
卸载时出现内存泄漏警告	未取消订阅事件	在 disconnectedCallback / 清理钩子中调用取消订阅函数