# @salla\.sa/twilight-components 中文文档

规范地址：https://npmcn.com/package/%40salla.sa/twilight-components/

版本：3\.0\.21
npm 元数据更新时间：2026-11-02T09:10:25.202Z
中文译文更新时间：2026-11-02T09:48:33.109Z
软件包许可：GPL-3\.0

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40salla.sa/twilight-components
原文对照：https://npmcn.com/package/%40salla.sa/twilight-components/?lang=original
项目主页：https://salla.dev/
源码仓库：https://github.com/sallaapp/twilight-components

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：32.2 MB，2512 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：22 个
- 首次发布：2021-11-17T15:56:19.371Z
- 最新版本发布：2026-11-02T09:10:25.000Z
- 已发布版本数：1191（近 12 个月 326 个）

## 中文简介

萨拉Web组件

## 安装

```sh
npm install @salla.sa/twilight-components
```

也可以使用：`pnpm add @salla.sa/twilight-components`、`yarn add @salla.sa/twilight-components`、`bun add @salla.sa/twilight-components`

## README

  

[![Logo](https://salla.dev/wp-content/uploads/2023/03/1-Light.png)](https://salla.dev/)

# 暮光JS Web组件

为Salla商店设计的一套现成的js web组件。  
[**浏览我们的博客»**](https://salla.dev/)  
  
[报告错误](https://github.com/SallaApp/Salla-CLI/issues/new) · [请求功能](https://github.com/SallaApp/Salla-CLI/discussions/new) . [< /萨拉开发者>](https://t.me/salladev) . [官方文档](https://docs.salla.dev/doc-422053/?nav=01HNFTD5Y5ESFQS3P9MJ0721VM)

目录表

1.  [概述](https://npmcn.com/package/%40salla.sa/twilight-components/#readme-overview)
2.  [开始使用](https://npmcn.com/package/%40salla.sa/twilight-components/#readme-getting-started)
    -   [暮光JS Web组件列表](https://npmcn.com/package/%40salla.sa/twilight-components/#readme-benefits)
    -   [好处](https://npmcn.com/package/%40salla.sa/twilight-components/#readme-benefits)
3.  [安装](https://npmcn.com/package/%40salla.sa/twilight-components/#readme-installation)
4.  [使用](https://npmcn.com/package/%40salla.sa/twilight-components/#readme-usage)
5.  [事件](https://npmcn.com/package/%40salla.sa/twilight-components/#readme-events)
6.  [支持](https://npmcn.com/package/%40salla.sa/twilight-components/#readme-support)
7.  [贡献](https://npmcn.com/package/%40salla.sa/twilight-components/#readme-contributing)
8.  [学分](https://npmcn.com/package/%40salla.sa/twilight-components/#readme-credits)
9.  [许可证](https://npmcn.com/package/%40salla.sa/twilight-components/#readme-license)

## 概述

**《暮光之城》** 为Salla商店提供了一套现成的设计和风格的网络组件。例如，准备好显示登录表单、产品可用性部分、搜索栏、本地化菜单等的组件。 **暮光JS Web组件** 是高级构建块和可重用web组件的集合，可以一起构建，以快速开发自定义Salla主题的UI，由明确的指导方针管理。

  

## 开始使用

**JS Web组件** 我们从头开始构建，以简单的学习和使用，具有各种精心构建的用户界面组件。正如文档所解释的那样，它与主题的结构和体系结构的完全兼容性使其易于自定义。

### 暮光JS Web组件列表

下面是一个现成的暮光JS Web组件列表，可以很容易地使用。接下来，在文档的这一部分中，将详细解释每个组件。

每个web组件都附带一个列表 **属性和事件** 使组件可定制。此外，每个web组件使用 [**暮光JS SDK**](https://docs.salla.dev/doc-422610/?nav=01HNFTDZPB31Y2E120R84YXKCX) 从后端获取任何所需的数据。

| 组件 | 代码标记 | 描述 |
| --- | --- | --- |
| [广告](https://docs.salla.dev/doc-478502/?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-advertisement` | 显示产品广告的所有细节。 |
| [应用程序图标](https://docs.salla.dev/doc-478518/?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-apps-icons` | 显示b谷歌Play商店和苹果商店的应用程序的可点击标签。 |
| [添加产品](https://docs.salla.dev/doc-422692?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-add-product-button` | 允许基于产品状态和产品类型属性控制按钮文本标签和行为。 |
| [面包屑](https://docs.salla.dev/doc-482370/?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-breadcrumb` | 通过显示页面路径帮助用户导航，允许他们通过点击链接轻松返回。 |
| [按钮](https://docs.salla.dev/doc-422694?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-button` | 显示一个可自定义的按钮，包括大小、颜色、样式、状态、位置等。 |
| [车的总结](https://docs.salla.dev/doc-422695?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-cart-summary` | 显示购物车的图标，带有指示购物车中商品数量的小圆圈徽标。 |
| [颜色选择器](https://docs.salla.dev/doc-422696?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-color-picker` | 允许使用多种输入法选择颜色。 |
| [评论](https://docs.salla.dev/doc-422697?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-comments` | 显示特定产品或页面的评论表单。 |
| [联系人](https://docs.salla.dev/doc-478494/?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-contacts` | 显示商店的联系信息详细信息。 |
| [有条件的字段](https://docs.salla.dev/doc-422699?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-conditional-fields` | 允许隐藏/显示产品中的某些特性，例如尺寸。 |
| [有条件的报价](https://docs.salla.dev/doc-537931/?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-conditional-offer` | 支持基于客户购物车状态的优惠和折扣的动态表示。 |
| [倒计时](https://docs.salla.dev/doc-422701?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-count-down` | 显示距离给定日期还有多少时间。 |
| [日期时间选择器](https://docs.salla.dev/doc-422702?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-datetime-picker` | 允许用户使用相同的控件选择日期和时间。 |
| [文件上传](https://docs.salla.dev/doc-422703?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-file-upload` | 允许用户上传一个或多个文件。 |
| [过滤器](https://docs.salla.dev/doc-422704?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-filters` | 允许用户以多种方式过滤数据。 |
| [赠送](https://docs.salla.dev/doc-422705?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-gifting` | 显示作为礼物的项目，可以在客户完成购买后使用。 |
| [无限卷动](https://docs.salla.dev/doc-422706?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-infinite-scroll` | 允许无限滚动，以便在用户向下滚动页面时连续加载内容。 |
| [分期付款](https://docs.salla.dev/doc-422707?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-installment` | 显示为特定产品提供的可用分期付款选项的块区域。 |
| [列表瓷砖](https://docs.salla.dev/doc-422708?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-list-tile` | 用于在平铺形式中显示列表项。 |
| [加载](https://docs.salla.dev/doc-422709?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-loading` | 用于向用户传达当前正在加载的某些数据。 |
| [本地化](https://docs.salla.dev/doc-422710?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-localization-modal` | 显示商店可用语言和货币的菜单。 |
| [登录](https://docs.salla.dev/doc-422711?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-login-modal` | 显示登录表单，该表单提示用户输入凭据以便对其访问进行身份验证。 |
| [忠诚](https://docs.salla.dev/doc-422712?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-loyalty` | 显示一个代表忠诚度计划的弹出窗口。 |
| [地图](https://docs.salla.dev/doc-422713?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-map` | 显示具有多层和通过事件交互的各种来源的地理地图。 |
| [菜单](https://docs.salla.dev/doc-478492/?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-menu` | 显示出现在页眉部分或页脚部分的嵌套列表项。 |
| [元数据](https://docs.salla.dev/doc-464599/?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-metadata` | 显示产品的详细规格，显示一个或多个部分的信息，如链接和文本等。 |
| [模态](https://docs.salla.dev/doc-422714?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-modal` | 在当前页面顶部显示对话框或弹出窗口。 |
| [提供](https://docs.salla.dev/doc-440408?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-offer` | 显示优惠、类别、产品、银行和折扣信息。 |
| [提供模态](https://docs.salla.dev/doc-422715?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-offer-modal` | 显示商店管理员提供的产品列表。 |
| [订单](https://docs.salla.dev/doc-508225/?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-orders` | 显示一个包含订单详细信息的表，如订单ID、产品总数、订单状态等。 |
| [支付](https://docs.salla.dev/doc-478374/?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-payments` | 显示可用的付款选项作为标签页脚项目。 |
| [占位符](https://docs.salla.dev/doc-422716?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-placeholder` | 为即将出现在布局中的内容保留空间。 |
| [产品可用性](https://docs.salla.dev/doc-422717?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-product-availability` | 显示“通知可用性”选项作为注册客户的按钮。 |
| [产品牌](https://docs.salla.dev/doc-422718?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-product-card` | 包含卡片显示模式下关于单个主题的内容和操作。 |
| [产品列表](https://docs.salla.dev/doc-422719?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-product-list` | 以有组织的方式显示一组相关产品，其中包含一些信息，如产品名称、价格和其他相关信息。 |
| [产品的选择](https://docs.salla.dev/doc-422720?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-product-options` | 在继续订购之前显示可定制的产品字段。 |
| [产品尺寸指南](https://docs.salla.dev/doc-422721?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-product-size-guide` | 使商家能够添加产品测量的高度，重量，深度和其他指标。 |
| [产品滑块](https://docs.salla.dev/doc-422722?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-products-slider` | 在一组相关产品中水平导航。 |
| [进度条](https://docs.salla.dev/doc-422723?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-progress-bar` | 显示进度条，指示数据处理正在进行中。 |
| [量输入](https://docs.salla.dev/doc-422724?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-quantity-input` | 允许客户使用计数器来指定特定产品的所需数量。 |
| [快速购买](https://docs.salla.dev/doc-422725?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-quick-buy` | 允许放置快速购买按钮，以便快速结账和支付产品。 |
| [快速订单](https://docs.salla.dev/doc-422726?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-quick-order` | 允许客户快速结账和支付产品。 |
| [评级明星](https://docs.salla.dev/doc-422727?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-rating-stars` | 使用星形文字显示一种等级量表形式。 |
| [评级模态](https://docs.salla.dev/doc-422728?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-rating-modal` | 显示商店、产品或运输公司的评级等级。 |
| [评论](https://docs.salla.dev/doc-508226/?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-reviews` | 显示垂直可滚动的评论，这可以自定义其数据源。 |
| [回顾总结](https://docs.salla.dev/doc-602149/?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-reviews-summary` | 允许用户在产品详细信息页面上显示5星的一般评级。 |
| [范围(分支机构)](https://docs.salla.dev/doc-422729?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-scopes` | 显示商店拥有的范围（分支）列表。 |
| [搜索](https://docs.salla.dev/doc-422730?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-search` | 显示搜索框、字段或栏。 |
| [床单](https://docs.salla.dev/doc-422733?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-sheet` | 要设置的其他组件的基线布局基础。 |
| [骨架](https://docs.salla.dev/doc-422731?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-skeleton` | 向用户显示即将到来但尚未可用的指示。 |
| [滑块](https://docs.salla.dev/doc-422735?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-slider` | 通过沿条反映一系列值来收集数值用户数据。 |
| [社会](https://docs.salla.dev/doc-499802?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-social` | 显示商店的社交媒体帐户列表。 |
| [Social-share](https://docs.salla.dev/doc-422736?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-social-share` | 显示带有社交媒体平台的菜单。 |
| [偷窃者](https://docs.salla.dev/doc-422737?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-swiper` | 现代触摸滑块显示项目列表。 |
| [选项卡](https://docs.salla.dev/doc-422738?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-tabs` | 使在单个视图中有多个窗格成为可能。 |
| [电话号码输入](https://docs.salla.dev/doc-422739?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-tel-input` | 显示用于输入带有国家/地区密钥/代码前缀的电话号码的字段。 |
| [用户菜单](https://docs.salla.dev/doc-422740?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-user-menu` | 显示带有链接的导航菜单列表。 |
| [用户配置文件](https://docs.salla.dev/doc-482367/?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-userprofile` | 显示用户配置文件的详细信息。 |
| [用户设置](https://docs.salla.dev/doc-422741?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-user-settings` | 允许用户管理他们的帐户设置。 |
| [验证](https://docs.salla.dev/doc-422742?nav=01HNFTE06J4QC24T0D5BPRYKMD) | `salla-verify` | 显示通过发送OTP验证码验证用户邮件/手机的字段。 |

（[回到顶部](https://npmcn.com/package/%40salla.sa/twilight-components/#readme-top)）

### 好处

#### 干净、简单、标准化。

开发人员将遵循标准，让用户爱上现成组件和美丽（但多变）主题的用户体验。开发人员可以使用风格指南和功能设计来创建带有UI组件模块的大型主题。

#### 使用暮光JS SDK

暮光Web组件使用 [**暮光JS SDK**](https://salla.stoplight.io/docs/twilight-themes-documentation/3ac843cae76a2-overview)，它允许使用特定的REST API在前端和后端之间进行通信。

#### 生态系统

暮光Web组件由一个全职核心团队和一个由开发人员和贡献者组成的大型社区维护。这是因为《暮光之城》帮助开发者合作。

（[回到顶部](https://npmcn.com/package/%40salla.sa/twilight-components/#readme-top)）

> #### 注意事项：
> 
> 值得注意的是 [顺风CSS框架](https://tailwindcss.com/) 的默认基础是 **暮光网组件**．未来的计划可能会包括其他CSS框架。

## 安装

要使用这些组件，开发人员需要加载一个CSS文件和一些JavaScript。CSS文件包括字体和设计令牌。

#### 《暮光之城》的主题

在使用 **暮光网组件** 在《暮光之城》主题中，开发者不需要包含 **暮光网组件** 在你的bundle或html中， **暮光之城主题引擎** 会不会注入最新版本的 **暮光网组件** 在页面中

#### 打包机/ ES模块

开发人员需要安装这两个 [node . js](https://nodejs.org/) 和 [顺风CSS](https://tailwindcss.com/)，然后通过执行以下命令之一安装Twiligh web组件：

```npm
npm install @salla.sa/twilight-components --save
```

```yarn
yarn add @salla.sa/twilight-components
```

之后，在javascript代码库中，开发人员可以像下面这样导入：

```JS
import {
  applyPolyfills, 
  defineCustomElements as TwilightWebComponents
} from '@salla.sa/twilight-components/loader';

applyPolyfills().then(() => {
    TwilightWebComponents(window);
});
```

#### HTML / CDN

另一种加载暮光Web组件的方法是使用托管在CDN上的版本。组件可以通过 `<script>` 标记在HTML文档的头部

```html
<script
  type="module"
  src="https://unpkg.com/@salla.sa/twilight-components@latest/dist/twilight-components/twilight-components.esm.js"
></script>
```

### 启用了JIT的

**顺风** 增加了一个 [即时编译器](https://v2.tailwindcss.com/docs/just-in-time-mode)，它在开发人员编写主题时生成样式，而不是在初始构建时提前生成所有内容。

由于JIT模式通过扫描模板文件按需生成CSS，因此配置 `content` 选项。 `tailwind.config.d.ts` 否则你的CSS将是空的

```js
...
  content: [
    // theme views
    "views/**/*.twig",
    // list of classes which required by twilight web components
    "node_modules/@salla.sa/twilight-tailwind-theme/safe-list-css.txt"
  ],
...
```

> 以前, [提到](https://docs.salla.dev/doc-422053/?nav=01HNFTD5Y5ESFQS3P9MJ0721VM) 这个文件 `tailwind.config.d.ts` 已经与 **暮光之城启动主题** 文件。

（[回到顶部](https://npmcn.com/package/%40salla.sa/twilight-components/#readme-top)）

## 使用

安装完成后，可以很容易地将组件添加到基本的HTML标记中，如下所示：

```html
// Salla Button component
<salla-button fill="outline" color="dark">Hello World 👋</salla-button>

// Salla Telephone Input component
<salla-tel-input onclick="telInput.isValid()" country-code="sa"
   country-key="+966" mobile="555555555">

// Salla Product Availability component
<salla-product-availability channels="sms,mobile,email" is-subscribed="false">
</salla-product-availability>
```

## 事件

我们建议使用DOM事件，但我们也提供自定义事件来帮助处理特定的事件类型。所有自定义事件总是记录在每个组件各自的文档页面上。

```js
// Save reference to the modal component below
var modal = document.querySelector("salla-modal");

// Listen for open events
modal.addEventListener("modalVisibilityChanged", function (isOpened) {
    console.log("Modal Opened");
});
```

此外，开发人员可以检测组件何时被加载，因为Twilight使用标准Web组件API的CustomElementsRegistry对象注册它的组件。该对象还提供了一个 `whenDefined` 函数，它接受一个组件名并返回一个promise。当组件被定义时，承诺将被实现：

```js
window.customElements.whenDefined("salla-button").then(() => {
    console.log("Salla Button is defined!");
});
```

（[回到顶部](https://npmcn.com/package/%40salla.sa/twilight-components/#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-components/#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-components/#readme-top)）

## 学分

-   [萨拉](https://github.com/sallaApp)
-   [所有贡献者](https://npmcn.com/package/contributors)

（[回到顶部](https://npmcn.com/package/%40salla.sa/twilight-components/#readme-top)）

## 许可证

麻省理工学院许可证（MIT）。请参阅 [许可文件](https://npmcn.com/package/%40salla.sa/twilight-components/LICENSE.md) 了解更多信息。

（[回到顶部](https://npmcn.com/package/%40salla.sa/twilight-components/#readme-top)）

## 常见问题

### @salla\.sa/twilight-components 是什么？

萨拉Web组件

### 如何安装 @salla\.sa/twilight-components？

在项目目录运行 npm install @salla\.sa/twilight-components，或使用 pnpm add / yarn add / bun add。

### @salla\.sa/twilight-components 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @salla\.sa/twilight-components 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @salla\.sa/twilight-components 可以商用吗？

@salla\.sa/twilight-components 使用 GPL-3\.0 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以 GPL-3\.0 兼容许可开源，并附带专利与反锁定条款。仅内部使用不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。

### @salla\.sa/twilight-components 还在维护吗？

最新版本 3\.0\.21 发布于 2026/11/02（1 天前）；至今共发布 1191 个版本，其中过去 12 个月发布了 326 个；首次发布于 2021/11/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。