暮光JS api

用于Salla店面API的JavaScript SDK提供了助手方法或REST API端点，允许在前端和后端之间进行通信。
浏览我们的博客»

报告错误 · 请求功能 . < /萨拉开发者> . 官方文档

概述

暮光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的一些可能用途：

• 验证客户并允许他们编辑帐户详细信息。
• 将产品直接从产品列表添加到客户美术中。
• 返回产品的价格。
• 将产品添加到客户的愿望清单中。
• 评级负责交付订单的船运公司。
• 还有更多！

（回到顶部）

安装和初始化

暮光JS SDK 无需下载或安装即可使用；相反，它需要作为HTML中的一小段常规JavaScript包含在HTML中，以便异步地将SDK加载到Twilight主题中。 

《暮光之城》的主题

在使用 暮光JS SDK 在《暮光之城》主题中，开发者不需要包含 暮光JS SDK 在主题项目的bundle或html中， 暮光之城主题引擎 会不会注入最新版本的 暮光JS SDK 在页面上。

基本上，开发人员不需要调用该方法 salla.init() 用于暮光主题，因为它将在安装暮光主题引擎时自动调用。这多亏了 身体:端钩 {% hook 'body:end' %}.

HTML和CDN

的最常用方法 暮光JS SDK 是通过 <script> 在结束前 body HTML文档的标记。

<script src="https://cdn.jsdelivr.net/npm/@salla.sa/twilight@latest/dist/@salla.sa/twilight.min.js"></script>

下面的代码片段将给出SDK的基本版本，其中配置被设置为最低要求，例如，存储URL。该方法 salla.init() 用于设置和初始化SDK。 

<script>
  salla.init({
    debug: true, // disbale it in prod
    language_code: 'ar', // en
    store: {
      id: 1305146709, // The store id can found via store pages.
      url: "https://the-best-store-ever.sa"
    }
  });
</script>

打包机/ ES模块

开发人员还可以安装 暮光JS SDK 使用如下命令：

npm install @salla.sa/twilight --save

yarn add @salla.sa/twilight

最初，开发人员必须导入Salla JS Events库，如下所示：

import '@salla.sa/twilight';

类似于 HTML / CDN节，下面的代码片段将给出SDK的基本版本，其中配置被设置为其最低要求，其中方法 salla.init() 用于设置和初始化SDK。 

<script>
  salla.init({
    debug: true, // disbale it in prod
    language_code: 'ar', // en
    store: {
      id: 1305146709, // The store id can found via store pages.
      url: "https://the-best-store-ever.sa"
    }
  });
</script>

使用

作为SDK初始化的结果，开发人员将能够使用SDK的任何主要api。例如，方法 addItem 将商品添加到购物车中，开发人员可以调用该方法 addItem 如下:

salla.cart.addItem({
    id: 1234,
    quantity: 1,
    notes: "please i need to get the red color"
}).then((response) => {
    /* add your code here */
});

除了上面的例子，方法 addItem May在购物车中添加一个带有多个选项的商品，如下所示：

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 当将商品添加到购物车中而没有从后端返回任何错误时触发：

salla.cart.event.onItemAdded((response) => {
  console.log(response)
});

另一方面，事件 onItemAddedFailed 在未完成向购物车添加商品且发生错误时触发。例如，找不到要添加到购物车的产品的id。

salla.cart.event.onItemAddedFailed((errorMessage) => {
  console.log(errorMessage)
});

基本配置

除了调用api之外，开发人员还可以配置Twilight引擎以满足其主题的需求。可以在此找到可用配置的列表 文章。为此，方法 salla.config.get() 用于检索配置值，而 salla.config.set() 用于设置配置值。

设置配置值

开发人员可以将调试模式设置为激活。也就是说，主题将在调试器中运行。这意味着调试器跟踪主题运行时发生的所有事情。

salla.config.set('debug', true)

获取配置值

类似地，开发人员可以使用该方法 salla.config.get() 以从配置文件中获取任何值。要检索一个简单的值，如用户Id，可以遵循以下语法：

salla.config.get('user.id’)

此外，如果所需的值嵌套在内部值中，例如货币代码，则可以遵循以下语法：

salla.config.get('currencies.SAR.code’)

获取版本信息

暮光框架提供了对所有包的版本信息的简单访问 Salla.versions 对象:

// 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"

这对于调试、支持和确保框架不同部分之间的兼容性特别有用。

（回到顶部）

WebMCP（用于浏览器内AI代理的工具）

暮光可以注册 WebMCP 工具，这样在购物者浏览器中运行的人工智能代理就可以搜索、填充购物车并前往结账。这些工具调用常规SDK (salla.cart.*， salla.product.*)在购物者自己的标签中，所以他们触发正常的购物车事件，购物车徽章和迷你购物车更新，就像他们点击一样。他们从不打电话给 /mcp 工作人员，其购物车不是标签的购物车。

失败回来了 { isError: true, content: [...] } 使用API自己的消息。

默认为关闭。 通过传递给的配置存储opt in Salla.init：

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运行两次时）。

（回到顶部）

支持

团队总是在这里帮助你。碰巧遇到了问题？想要报告bug？你可以在GitHub上提交一个 问题跟踪器。如果您还有任何问题，请通过电子邮件与我们联系 电报机器人 或加入全球开发者社区 电报.

（回到顶部）

贡献

贡献使开源社区成为一个学习、启发和创造的神奇场所。 你做的任何贡献都是 极大的赞赏.

如果你有一个更好的建议，请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. 打开拉取请求

（回到顶部）

学分

• 萨拉
• 所有贡献者

（回到顶部）

许可证

麻省理工学院许可证（MIT）。请参阅 许可文件 了解更多信息。

（回到顶部）