# @salla\.sa/twilight 中文文档 规范地址：https://npmcn.com/package/%40salla.sa/twilight/ 版本：3\.0\.21 npm 元数据更新时间：2026-11-02T09:08:19.678Z 中文译文更新时间：2026-11-02T09:59:48.653Z 软件包许可：GPL-3\.0 本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40salla.sa/twilight 原文对照：https://npmcn.com/package/%40salla.sa/twilight/?lang=original 项目主页：https://salla.dev/ 源码仓库：https://github.com/SallaApp/twilight ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.2 MB，67 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：8 个 - peer 依赖：webpack ^4 \|\| ^5 - 首次发布：2021-11-23T10:33:27.450Z - 最新版本发布：2026-11-02T09:08:19.459Z - 已发布版本数：1332（近 12 个月 326 个） ## 中文简介 Salla主题工具包，web组件，事件，请求，Utils ## 安装 ```sh npm install @salla.sa/twilight ``` 也可以使用：`pnpm add @salla.sa/twilight`、`yarn add @salla.sa/twilight`、`bun add @salla.sa/twilight` ## README [![Logo](https://salla.dev/wp-content/uploads/2023/03/1-Light.png)](https://salla.dev/) # 暮光JS api 用于Salla店面API的JavaScript SDK提供了助手方法或REST API端点，允许在前端和后端之间进行通信。 [**浏览我们的博客»**](https://salla.dev/) [报告错误](https://github.com/SallaApp/Salla-CLI/issues/new) · [请求功能](https://github.com/SallaApp/Salla-CLI/discussions/new) . [< /萨拉开发者>](https://t.me/salladev) . [官方文档](https://salla.stoplight.io/docs/twilight-themes-documentation/3ac843cae76a2-overview) 目录表 1. [概述](https://npmcn.com/package/%40salla.sa/twilight/#readme-overview) 2. [开始使用](https://npmcn.com/package/%40salla.sa/twilight/#readme-getting-started) - [SDK的主要api](https://npmcn.com/package/%40salla.sa/twilight/#readme-sdks-main-apis) - [用例](https://npmcn.com/package/%40salla.sa/twilight/#readme-use-cases) 3. [安装和初始化](https://npmcn.com/package/%40salla.sa/twilight/#readme-installation-and-initialization) 4. [使用](https://npmcn.com/package/%40salla.sa/twilight/#readme-usage) - [基本配置](https://npmcn.com/package/%40salla.sa/twilight/#readme-basic-configuration) 6. [支持](https://npmcn.com/package/%40salla.sa/twilight/#readme-support) 7. [贡献](https://npmcn.com/package/%40salla.sa/twilight/#readme-contributing) 8. [学分](https://npmcn.com/package/%40salla.sa/twilight/#readme-credits) 9. [许可证](https://npmcn.com/package/%40salla.sa/twilight/#readme-license) ## 概述 暮光JS SDK (`@salla.sa/twilight`)是Twilight框架的核心包，为Salla的店面api提供了一个全面的JavaScript接口。它使主题开发人员能够轻松地与Salla的后端服务进行通信，处理事件，管理状态，并构建交互式电子商务体验。 ### 体系结构 暮光框架由几个一起工作的包组成： 1. **@salla.sa /基地**：具有核心实用程序和服务的基础层 2. **@salla.sa /暮光之城** （此包）：用于Salla主题的主SDK 3. **@salla.sa / twilight-components**：用于Salla主题的Web组件 4. **@salla.sa / twilight-tailwind-theme**：顺风CSS主题的Salla主题 5. **@salla.sa / applepay**：为sala集成Apple Pay 这种模块化体系结构允许更好地分离关注点、更易于维护的代码，以及仅使用特定应用程序所需的框架部分的能力。 ### 关键特性 - **API集成**：所有Salla API端点的预构建方法 - **事件系统**强大的事件处理实时更新 - **身份验证**：无缝用户认证和会话管理 - **购物车管理**：完整的购物车功能 - **多语言支持**内置本地化功能 - **版本管理**：通过 `Salla.versions` - **优化的包**：用于最小生产构建的可摇树模块 ## 开始使用 **SDK** 代表“软件开发工具包”，它指的是使用JavaScript与特定REST API交互的库。 ### SDK的主要api 的主要部分 **暮光JS SDK** 包括REST API端点，简化与API请求相关的操作，例如： - **授权api:** 用于客户登录、注销等的多个端点。 - **购物车api:** 客户的购物车端点列表。 - **评论api:** 与产品或页面上的客户评论或反馈相关的一组端点。 - **货币api:** 与商店货币列表相关的一组端点。 - **api:** 客户订单相关的端点。 - **产品的api**：产品相关的端点。 - **概要文件api:** 客户的概要文件端点。 - **评级api:** 与商店、产品、订单、发货等级相关的端点。 - **愿望列表api:** 客户的愿望清单端点。 ### 用例 以下是Twilight JS SDK的一些可能用途： - 验证客户并允许他们编辑帐户详细信息。 - 将产品直接从产品列表添加到客户美术中。 - 返回产品的价格。 - 将产品添加到客户的愿望清单中。 - 评级负责交付订单的船运公司。 - 还有更多！ （[回到顶部](https://npmcn.com/package/%40salla.sa/twilight/#readme-top)） ## 安装和初始化 **暮光JS SDK** 无需下载或安装即可使用；相反，它需要作为HTML中的一小段常规JavaScript包含在HTML中，以便异步地将SDK加载到Twilight主题中。  #### 《暮光之城》的主题 在使用 **暮光JS SDK** 在《暮光之城》主题中，开发者不需要包含 **暮光JS SDK** 在主题项目的bundle或html中， **暮光之城主题引擎** 会不会注入最新版本的 **暮光JS SDK** 在页面上。 基本上，开发人员不需要调用该方法 `salla.init()` 用于暮光主题，因为它将在安装暮光主题引擎时自动调用。这多亏了 [身体:端钩](https://salla.stoplight.io/studio/twilight-themes-documentation?#bodyend-hook) `{% hook 'body:end' %}`. #### HTML和CDN 的最常用方法 **暮光JS SDK** 是通过 ` ``` 下面的代码片段将给出SDK的基本版本，其中配置被设置为最低要求，例如，存储URL。该方法 `salla.init()` 用于设置和初始化SDK。  ```js ``` #### 打包机/ ES模块 开发人员还可以安装 **暮光JS SDK** 使用如下命令： ```npm npm install @salla.sa/twilight --save ``` ```yarn yarn add @salla.sa/twilight ``` 最初，开发人员必须导入Salla JS Events库，如下所示： ```js import '@salla.sa/twilight'; ``` 类似于 [HTML / CDN节](https://github.com/SallaApp/twilight/blob/master/packages/twilight/README.md#html-and-cdn)，下面的代码片段将给出SDK的基本版本，其中配置被设置为其最低要求，其中方法 `salla.init()` 用于设置和初始化SDK。  ```js ``` ## 使用 作为SDK初始化的结果，开发人员将能够使用SDK的任何主要api。例如，方法 `addItem` 将商品添加到购物车中，开发人员可以调用该方法 `addItem` 如下: ```js salla.cart.addItem({ id: 1234, quantity: 1, notes: "please i need to get the red color" }).then((response) => { /* add your code here */ }); ``` 除了上面的例子，方法 `addItem` May在购物车中添加一个带有多个选项的商品，如下所示： ```js salla.cart.addItem({ id: 1234, quantity: 1, options: { 117414452: 11232214, // option value id (select choice) 117416632: "http://option-value-as-url-of-image.com", 117411132: "option value as string" }, notes: "please i need to get the red color" }).then((response) => { /* add your code here */ }); ``` 此外，将有大量的存储事件可供使用。因此，开发人员的主题可以配置为自动响应各种活动，例如： - 用户请求访问码来执行登录，但是没有发送该代码。对于这个场景，使用方法 `salla.event.auth.onCodeNotSent()` 可以使用。 - 控件将一个新项目添加到购物车中 `salla.cart.event.onItemAdded()` 方法。 - 用户使用方法向Wishlist添加了一个新项目 `salla.event.wishlist.onAdded()`. 一个完整的例子就是事件 `onItemAdded` 当将商品添加到购物车中而没有从后端返回任何错误时触发： ```js salla.cart.event.onItemAdded((response) => { console.log(response) }); ``` 另一方面，事件 `onItemAddedFailed` 在未完成向购物车添加商品且发生错误时触发。例如，找不到要添加到购物车的产品的id。 ```js salla.cart.event.onItemAddedFailed((errorMessage) => { console.log(errorMessage) }); ``` ### 基本配置 除了调用api之外，开发人员还可以配置Twilight引擎以满足其主题的需求。可以在此找到可用配置的列表 [文章](https://salla.stoplight.io/docs/twilight-themes-documentation/ZG9jOjQ4OTE2NDQ5-configuration)。为此，方法 `salla.config.get()` 用于检索配置值，而 `salla.config.set()` 用于设置配置值。 #### 设置配置值 开发人员可以将调试模式设置为激活。也就是说，主题将在调试器中运行。这意味着调试器跟踪主题运行时发生的所有事情。 ```js salla.config.set('debug', true) ``` #### 获取配置值 类似地，开发人员可以使用该方法 `salla.config.get()` 以从配置文件中获取任何值。要检索一个简单的值，如用户Id，可以遵循以下语法： ```js salla.config.get('user.id’) ``` 此外，如果所需的值嵌套在内部值中，例如货币代码，则可以遵循以下语法： ```js salla.config.get('currencies.SAR.code’) ``` #### 获取版本信息 暮光框架提供了对所有包的版本信息的简单访问 `Salla.versions` 对象: ```js // Get the version of the core package console.log(Salla.versions.twilight); // e.g., "v2.14.145" // Get the version of the base package console.log(Salla.versions.base); // e.g., "v2.14.143" ``` 这对于调试、支持和确保框架不同部分之间的兼容性特别有用。 （[回到顶部](https://npmcn.com/package/%40salla.sa/twilight/#readme-top)） ### WebMCP（用于浏览器内AI代理的工具） 暮光可以注册 [WebMCP](https://webmachinelearning.github.io/webmcp/) 工具，这样在购物者浏览器中运行的人工智能代理就可以搜索、填充购物车并前往结账。这些工具调用常规SDK (`salla.cart.*`， `salla.product.*`)在购物者自己的标签中，所以他们触发正常的购物车事件，购物车徽章和迷你购物车更新，就像他们点击一样。他们从不打电话给 `/mcp` 工作人员，其购物车不是标签的购物车。 | 工具 | 只读 | 它是做什么的 | | --- | --- | --- | | `search_products` | 是 | 按关键字(`query`、可选 `limit`）。 | | `get_product` | 是 | 产品详情按 `product_id`. | | `get_cart` | 是 | 购物者的当前购物车：商品、总数、优惠券。 | | `add_to_cart` | 否 | 添加 `product_id` （`quantity`, `options` 对于需要它们的产品，按选项id进行键控)。 | | `update_cart_item` | 否 | 更改购物车项目的数量。 | | `remove_cart_item` | 否 | 移除购物车项目。 | | `apply_coupon` | 否 | 申请优惠券代码。 | | `go_to_checkout` | 否 | 导航到结帐（客人先登录）。它只能导航； **它从不下订单**，购物者在结账页面付款。 | 失败回来了 `{ isError: true, content: [...] }` 使用API自己的消息。 **默认为关闭。** 通过传递给的配置存储opt in `Salla.init`： ```js Salla.init({ store: { id: 1234 }, webmcp: { enabled: true } }); ``` 只有布尔值 `true` (或 `'true'` / `1`)把它打开。Salla Store为您呈现这个值 `TWILIGHT_WEBMCP_ENABLED` （所有商店）或 `themes::webmcp.enabled` 保存设置;把它设回 `false` 关掉工具。不涉及暮光之城版本。 **浏览器的支持。** 需要实现WebMCP的浏览器和HTTPS页面。它寻找 `document.modelContext` 首先,然后 `navigator.modelContext`，如果两者都不存在（所有其他浏览器，包括当前的Firefox和Safari）或HTTP，则不执行任何操作。在Chrome 146+的API背后 `chrome://flags/#enable-webmcp-testing` 标志（“WebMCP用于测试”）。允许两次注册相同的工具（例如当init运行两次时）。 （[回到顶部](https://npmcn.com/package/%40salla.sa/twilight/#readme-top)） ## 支持 团队总是在这里帮助你。碰巧遇到了问题？想要报告bug？你可以在GitHub上提交一个 [问题跟踪器](https://github.com/SallaApp/twilight-vscode-extension/issues/new)。如果您还有任何问题，请通过电子邮件与我们联系 [电报机器人](https://t.me/SallaSupportBot) 或加入全球开发者社区 [电报](https://t.me/salladev). （[回到顶部](https://npmcn.com/package/%40salla.sa/twilight/#readme-top)） ## 贡献 贡献使开源社区成为一个学习、启发和创造的神奇场所。 你做的任何贡献都是 **极大的赞赏**. 如果你有一个更好的建议，请fork repo并创建一个pull request。 你也可以简单地打开一个带有“增强”标签的问题。别忘了给这个项目打个星！再次感谢! 1. 分岔项目 2. 创建特性分支(`git checkout -b feature/AmazingFeature`） 3. 提交更改(`git commit -m 'Add some AmazingFeature'`） 4. 推至分行(`git push origin feature/AmazingFeature`） 5. 打开拉取请求 （[回到顶部](https://npmcn.com/package/%40salla.sa/twilight/#readme-top)） ## 学分 - [萨拉](https://github.com/sallaApp) - [所有贡献者](https://npmcn.com/package/contributors) （[回到顶部](https://npmcn.com/package/%40salla.sa/twilight/#readme-top)） ## 许可证 麻省理工学院许可证（MIT）。请参阅 [许可文件](https://npmcn.com/package/%40salla.sa/twilight/LICENSE.md) 了解更多信息。 （[回到顶部](https://npmcn.com/package/%40salla.sa/twilight/#readme-top)） ## 常见问题 ### @salla\.sa/twilight 是什么？ Salla主题工具包，web组件，事件，请求，Utils ### 如何安装 @salla\.sa/twilight？ 在项目目录运行 npm install @salla\.sa/twilight，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：webpack（^4 \|\| ^5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @salla\.sa/twilight 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @salla\.sa/twilight 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @salla\.sa/twilight 可以商用吗？ @salla\.sa/twilight 使用 GPL-3\.0 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以 GPL-3\.0 兼容许可开源，并附带专利与反锁定条款。仅内部使用不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。 ### @salla\.sa/twilight 还在维护吗？ 最新版本 3\.0\.21 发布于 2026/11/02（1 天前）；至今共发布 1332 个版本，其中过去 12 个月发布了 326 个；首次发布于 2021/11/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。