# @ably/ui 中文文档

规范地址：https://npmcn.com/package/%40ably/ui/

版本：19\.0\.0
npm 元数据更新时间：2026-10-16T10:59:53.192Z
中文译文更新时间：2026-11-06T01:05:57.526Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40ably/ui
原文对照：https://npmcn.com/package/%40ably/ui/?lang=original
项目主页：https://github.com/ably/ably-ui#readme
源码仓库：https://github.com/ably/ably-ui

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

- 包体积（解压后）：7.8 MB，1446 个文件
- TypeScript 类型：包内自带
- 运行依赖：22 个
- peer 依赖：react ^18\.2\.0 \|\| ^19\.0\.0，react-dom ^18\.2\.0 \|\| ^19\.0\.0，posthog-js ^1\.217\.4 \|\| \<2，mixpanel-browser ^2\.60\.0 \|\| \<3
- 首次发布：2021-10-18T13:37:50.373Z
- 最新版本发布：2026-10-16T10:59:53.002Z
- 近 30 天下载量：7483（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：762（近 12 个月 80 个）

## 中文简介

Ably设计系统库的所在地([设计. able.com](https://design.ably.com/)) (中文(简体) ). 它提供了一个展示、开发/测试环境以及不同可分配产品的出版管道.

## 安装

```sh
npm install @ably/ui
```

也可以使用：`pnpm add @ably/ui`、`yarn add @ably/ui`、`bun add @ably/ui`

## README

# 聪明的

`ably-ui` 是Ably设计系统库的所在地([https://hably-ui.herokuapp.com/ 页面存档备份,存于互联网档案馆](https://ably-ui.herokuapp.com/)) (中文(简体) ). 它提供了一个展示、开发/测试环境以及不同可分配产品的出版管道.

### 图书馆结构

库由模块,资产,和JavaScript组件所建. 一个模块是所有这些的容器.

例如 `core` 模块提供了可以构建基于网络的界面的“色调”的最一般要素——打字、颜色、间隔(即容器)等。 模块中的组件支持我们最常见的构建"色调"的需要,如导航元素,脚印,英雄部分,代码样本等. 资产,和JavaScript都由模块中的组件共享.

部件并不直接要求资产——相反,由消费者来装入资产并传递给部件. 这确保了URL的灵活性.

### 安装

### 国家预防机制

这类安装使您可以访问模块/组件资产以及反应组件.

```bash
pnpm add @ably/ui # Preferred
```

附加自“% 1” 导入的 JavaScript `Core` 模块 `window` 对象 :

```js
import "@ably/ui/core/scripts";

// AblyUi.Core is now available on window
```

要导入 Es6 `core` 模块并显示任何窗口 :

```js
import ablyUiCore from "@ably/ui/core/scripts";
```

将 JavaScript 导入为 `Accordion` 组件 :

```js
import Accordion from "@ably/ui/core/accordion/component";
```

如果您的捆绑器支持 CSS 导入, 您也可以导入 :

```js
import "@ably/ui/core/styles.css";
```

### 设立 TailwindCSS

目前,AblyUI CSS的建设是为了与TailwindCSS合作. 要融入您的应用程序:

1.  在您的工程中添加 AblyUI
2.  在您的工程中添加 TailwindCSS
    1.  按项目类型:
        1.  单位 [HTML 语言](https://tailwindcss.com/docs/installation#installing-tailwind-css-as-a-post-css-plugin)
        2.  单位 [盖茨比](https://tailwindcss.com/docs/guides/gatsby)
            1.  添加后 CSS 导入方式 `npm install postcss-import`
    2.  如果安装时间超过5分钟或有问题,请尝试一次安装一个库
    3.  确保您正在安装 v2 `npm install -D tailwindcss@2.X`
3.  确定您使用的格式 `@import 'tailwindcss/base';...` 在你身边 `global.css` 文件而不是 `@tailwind/base` 来自 Tailwind v3 的格式
4.  在您的 `tailwind.config.js`。注意不同的配置属性总是由 `ablyUIConfig`数字 :

```js
const extendConfig = require("@ably/ui/tailwind.extend.js");

module.exports = extendConfig((ablyUIConfig) => ({
  ...ablyUIConfig,
  purge: {
    content: [
      ...(relative - globbed - paths - to - your - templates),
      ...ablyUIConfig.purge.content,
    ],
    options: {
      ...ablyUIConfig.purge.options,
    },
  },
}));
```

1.  在 CSS 文件中, 您添加了您的尾风声明, 导入 CSS 用于您需要的模块和组件 :

```css
@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";

@import "@ably/ui/reset/styles.css"; /* needed as we disable the default Tailwind reset */
@import "@ably/ui/core/styles.css"; /* styles for core module components and more */
@import "@ably/ui/core/Flash/component.css";
```

#### 导入反应组件

请注意,根据组成部分的不同,你可能需要包括CSS和JS:

```js
import Meganav from "@ably/ui/core/Meganav";
```

## 使用量

### 图标

图标有两种格式支持不同的应用程序类型:

1.  **反应组件导入** (推荐React Apps) (中文(简体) )
2.  **SVG 打印表** (非反应应用程序的倒置)

我们提供对收押地和第三方托管的当地定制资产的访问 [赫罗伊孔斯](https://heroicons.com/) 图书馆.

#### 反应应用( 建议)

**使用图标反应组件**

这个 `Icon` 组件是反应应用程序的首选方法,提供自动回落和一致的大小:

```tsx
// Local custom icon
<Icon name="icon-display-live-chat" size="3rem" additionalCSS="block mb-16" />

// Heroicon with explicit variant
<Icon name="icon-gui-arrow-long-right-outline" size="2rem" />

// Heroicon using variant prop (appends variant to name)
<Icon name="icon-gui-chevron-down" variant="solid" size="1.5rem" />
```

**反应组件如何工作**

1.  **第一届**: 尝试加载您自定义 SVG 生成的本地反应组件
2.  **倒计时**: 如果不存在本地组件, 则动态导入相应的英雄
3.  **严重退化**: 如果两者均不存在, 返回为无效( 没有显示图标)

#### 非反应应用程序

**使用 SVG 打印表**

对于不使用React的应用程序,图标作为SVG图案可以直接引用:

```html
<!-- The width and height are required for correct sizing. The actual color class might depend on the svg and whether it uses strokes, fills etc. Note as well xlink:href, which is xlinkHref in react. -->
<svg class="w-12 h-12 text-cool-black">
  <use xlink:href="#sprite-disclosure-arrow" />
</svg>
```

即使在 React 应用程序中,您也可以使用 Sprite 方法来进行高级使用, 如悬浮状态 [组](https://tailwindcss.com/docs/hover-focus-and-other-states#group-hover) 类 :

```tsx
<a
  href="{url}"
  className="text-gui-default hover:text-gui-hover focus:text-gui-focus group"
>
  {children}
  <svg className="w-12 h-12 transform -rotate-90 align-top ui-icon-dark-grey group-hover:icon-gui-hover group-focus:icon-gui-focus ml-4">
    <use xlinkHref="#sprite-disclosure-arrow" />
  </svg>
</a>
```

种子文件可以装入 `loadSprites` 可用的助手 `core` 模块或直接包含在页面中.

#### 图标来源

**本地自定义图标**

将 SVG 文件放入 a `src/core/icons` 文件夹将 :

1.  生成可动态导入的反动组件
2.  将它们添加到每个组的 Sprites 文件(例如, `core/sprites-gui.svg`用于非反应使用

**Heroicons 整合**

系统自动回落到 [赫罗伊孔斯](https://heroicons.com/) 当找不到本地图标时, 使用此命名常规 :

-   `icon-gui-{heroicon-name}-{variant}`

何处 `variant` 可为:

-   `outline` — 24px 大纲图标
-   `solid` — 24px 固态图标
-   `mini` — 20px 固态图标
-   `micro` — 16px 固态图标

这种混合方式允许您使用自定义品牌图标,同时可以访问整个英雄文库作为后退.

见 [https://hably-ui.herokuapp.com/组件/icon 互联网档案馆的存檔,存档日期2013-12-22](https://ably-ui.herokuapp.com/components/icon) 更多细节.

### 字体

字体资产不自动包含,而是属于repo的一部分,以及字体面文件的示例;参见 `src/core/fonts` 用于实例。 确保将许可证文件申报纳入使用.

### 无障碍

能力-自来水的一个重要部分是,确保尽可能多的用户能够使用所生产的UI。 所有组件都应至少遵守AA无障碍标准。 在大多数情况下,这可以通过遵循一些简单的规则来实现:

\- 使用正确的 [HTML 元素](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/HTML): 导航锚地、互动按钮、列表列表等

-   使用屏幕读取器进行测试(例如) [用网络转子在Mac OSX上的声音](https://support.apple.com/en-gb/guide/voiceover/welcome/mac)(中文(简体) ) ——确认设计有适当的水龙头目标,形成对比 ——使用 [aria 属性](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) 在 HTML 中达到极限 ——不要打破网络平台(即不要打破后键,滚动,页内链接等行为)

## 发展

将资产直观化为 `ably-ui`,有一个故事书的例子,它既是展示,又是发展环境.

### 快速启动

最容易开始的方法就是使用开发脚本:

```bash
./bin/dev
```

此脚本将 :

-   检查所有需要的工具(Node.js, pnpm)是否通过 mise 安装在正确的版本中
-   安装所有项目依赖性
-   自动启动故事本

### 手动设置

如果您喜欢手动运行命令 :

首先,通过运行确保您拥有所有所需的项目依赖性 `pnpm install` 在项目根中.

然后,运行故事书,运行 `pnpm storybook` 在工程根中 - 它应该在浏览器中自动打开.

将故事书建设成一个静态的站点(即部署时的样子),运行 `pnpm build-storybook` 从工程根,转到生成的目录 `cd preview`,然后运行 `npx http-server` (如果还没有完成,则接受安装该软件包的提示). 建成的站点将在列出的本地URL中提供.

### SWC 编译旗帜

我们有一个动态的 SWC 配置, 允许我们在库中支持编译时间特征标记 。 这使得我们在编译时间(不是运行时间)中可以改变某些代码路径的行为,这在开发模式中大多有用.

例如,在我们代码的某处可能会有一面旗子,在开发中记录额外的调试信息,在发布的版本中是无用的. 它可能看起来像这样:

```ts
// Example usage in api-client.ts
declare const __DEBUG_MODE__: boolean;

const api = createApiClient();
if (__DEBUG_MODE__) {
  console.log("Debug mode enabled");
}
```

旗帜可以添加到列表中 `swc.config.ts`,并启用环境变量:

```
$ DEBUG_MODE=true pnpm build
```

### 发布审查应用程序的预发包

在这样做之前确保您承诺并推进您的工作( P) .

您需要认证 [无](https://docs.npmjs.com/creating-and-viewing-access-tokens) 将出版.

以上之后,你应该:

-   设置在您环境中的 NPU TOKEN
-   您的用户级别 `~/.npmrc` (不是这个包裹) `.npmrc`)读之:
    
    ```
    //registry.npmjs.org/:_authToken=${NPM_TOKEN}
    ```
    
    pnpm 忽略了任务项目中环境可变的证书 `.npmrc`。 。 。 .

要使用您在建的代码部署审查应用程序,您可以使用 `pre-release` 脚本 :

```bash
# in packages/ui directory
./scripts/pre-release.sh
```

此脚本实现以下步骤的自动化 :

1.  释放前:

-   更新当地对能动设备的依赖性,并运行一个生产大楼
-   释放一个带有您当前 SemVer 构建的版本的 NPA 套件, 但根据您总部承诺的简短 SHA 添加一个释放前标签
-   等待在国家预防机制登记册上提供这套资料(手提传播延迟)
-   自动更新两者 `apps/website` 财务报告和审定财务报表 `apps/voltaire` 与新 dev 版本连接

2.  更新发布前版本 :

-   在一个原子执行中提交所有更改(UI package.json,app package.json文件,以及锁文件)
-   将承诺并标记到原产地

这将启动一个编审应用的构建,同时安装在两个消耗性应用中的预发版本.

### 构成部分

组件和模块包含JS和CSS文件,但没有模板. 相反,对于一个特定组件支持的每个框架,都会创建一个单独的"框架模板". 一个组件仍然可以在任何其他框架中使用,只需使用它所需要的资产.

所有组件都居住在 `src` 并遵循目录和文件名公约:

-   模块目录(TitleCase)
    -   模块资产文件 : `scripts.js` 用于 Java 脚本和 `styles.css` 支助科
    -   组件目录( TitleCase)
        -   `component.js` - 支持联署文件(遗产)
        -   `component.css` - 补充支助科(后勤)
        -   `[ComponentName].stories.tsx` - 如果反应, 故事书演示文件
    -   如果反应, `[ComponentName].tsx` 在兄弟级到组件目录

例如:

```
- Core
  - script.js
  - styles.css
  - Accordion
    - component.js
    - component.css
    - Accordion.stories.tsx
  - Accordion.tsx
```

#### 支助科

##### z指数和定位

如果使用静态以外的定位,请注意创建堆叠上下文. 单位 `properties.css` 你会找到 `z-index` hTML 堆放上下文的值(被像巨型导航这样的组件所使用)。 在您组件内创建新元件时, 将 Z 索引值提升到创建堆叠上下文并定义的选中器 `z-index` 易于扫描的值(参见 [https://www.oreilly.com/library/view/developing-web-组件/9781491905685/ch04.html 互联网档案馆的存檔,存档日期2013-12-21](https://www.oreilly.com/library/view/developing-web-components/9781491905685/ch04.html) 在堆放上下文和z-index上写得很好.

### 正在格式化文件( L)

默认, [高级](https://prettier.io/) 打开 [奥克林特](https://oxc.rs/docs/guide/usage/linter) (外加一个用于故事本和评论规则的小ESLint)将处理大部分前端文件. 您可以通过编辑器( 编辑器应该取取相关的配置文件) 或命令行( 见 `scripts` (原始内容存档于2018-09-21). in package.json.

### 添加新组件

#### 增加一个新的组成部分:

添加一个 `[ComponentName].tsx` 文件输入 `src`,在您选择的模块中(最有可能) `core`) (中文(简体) ). 任何辅助文件,即样式表,都应被放入与组件同名的目录.

#### 在故事书中看到此组件:

创建一个 `[ComponentName].stories.tsx` 文档与您的 `component` 资产,遵循其他故事故事的例子,或其在线文档以提供指导。 运行"故事本"时,故事应该被取出并自动地被制作出来.

### 出版

我们用 [语义版 2.0.0](https://semver.org/) 用于版本不同的图书馆版本.

软件包将公布于 [GitHub 私人登记处](https://github.com/features/packages)。 。 。 .

出版是通过在 GitHub 中标记一个发布来完成的. 这引发了 " GitHub " 行动,将行动推向国家防范机制登记册,并将 " 童话 " 部署到国家防范机制登记册 [能力/能力 - ui](https://github.com/ably/ably-ui) 寄存器,其版本取自 GitHub 发行的标签.

发布后,您可以手动触发 `update-ably-ui` 创建单一的 PR 草案的工作流程 [伏尔泰](http://github.com/ably/voltaire) 财务报告和审定财务报表 [网站](http://github.com/ably/website) 与新的精通版本.

**启动释放:**

-   确定您已经运行了预发布脚本 `./scripts/pre-release.sh` (此更新 npm 软件包版本, 用于在 `package.json` 并更新两个消费应用程序.
-   合并您的 PR 到 `main` 经批准后.
-   在基图布 [Ably -UI (英语)](http://github.com/ably/ably-ui) 重击, [创建新发行](https://github.com/ably/ably-ui/releases/new) 标签.
-   为发行创建有新版本号的新标签.
    -   _不在标签上加前缀 `v`_
-   为"发行"增加一个有意义的标题.
-   单击自动生成器释放注释按钮.
-   发布发布.
-   检查Github `Actions` 选项卡,以确保发行为绿色.
-   成功发布后,将使用汇编版的《故事书》网站 [能力/能力 - ui](https://github.com/ably/ably-ui) 仓库的 gh- pages 分支 .
-   手动触发 `update-ably-ui` 从 Action 选项卡创建两个应用程序的 PR 更新草稿的工作流程 .

这将向国家防范机制公布该软件包,并部署一个新的故事书网站 [https://hably.github.io/ably-ui/ 互联网档案馆的存檔,存档日期2013-12-02](https://ably.github.io/ably-ui/)。为了更新消费应用程序,手动启动工作流程,该工作流程将为Voltaire和Webast创建一个单一的PR草案,在合并前需要审查.

### 《塔克公约》(摩纳哥)

在单体中,精通使用 **组件前缀标签** 实现独立释放:

**释放标签 :** `ui-<version>` (例如, `ui-17.13.2`(中文(简体) )

-   用于生产国家预防机制的释放
-   通过 GitHub 发布创建
-   不包含 `v` 前缀

**释放前标记 :** `ui-v<version>-dev.<sha>` (例如, `ui-v17.13.2-dev.a1b2c3d`(中文(简体) )

-   自动创建于 `./scripts/pre-release.sh`
-   向国家预防机制公布 `dev` 标签
-   包括 `v` 前缀并输入 SHA

见 [根文件/磁盘](https://npmcn.com/package/docs/TAGGING.md) 完整的细节 单列标注公约.

### 审查应用程序

审阅应用允许您创建"故事书"的临时部署,用于与利益攸关方共享UI变化而无需本地开发设置.

要创建审查应用程序:

1.  使用修改创建拉动请求
2.  添加数据 `review-app` 标签到您的 PR
3.  将自动创建和部署一个 Heroku 评论应用程序
4.  部署将出现在您的 PR 的部署部分( 基本授权已启用 -- -- 需要时请其他贡献者提供证书)

在PR关闭或标签被去掉时,审查应用会自动被清理. 只有寄存器贡献者可以创建审查应用程序.

### 正在测试

`ably-ui` 用途 [测试](https://vitest.dev/) 与 [Vitest 的故事书加词](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon) 以自动将所有故事变成可执行测试。 这意味着我们不必为故事写明确的测试 尽管我们有能力写 [播放函数](https://storybook.js.org/docs/writing-stories/play-function),这让我们可以测试更详细的相互作用.

测试使用Playwright在浏览器环境中运行,提供了全面的视觉回归测试和交互测试能力.

您可以使用 :

```bash
pnpm test
```

这将在无头浏览器环境中使用vitest运行所有的故事测试.

## 常见问题

### @ably/ui 是什么？

Ably设计系统库的所在地\(设计\. able\.com\) \(中文\(简体\) \)\. 它提供了一个展示、开发/测试环境以及不同可分配产品的出版管道\.

### 如何安装 @ably/ui？

在项目目录运行 npm install @ably/ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.2\.0 \|\| ^19\.0\.0）、react-dom（^18\.2\.0 \|\| ^19\.0\.0）、posthog-js（^1\.217\.4 \|\| \<2）、mixpanel-browser（^2\.60\.0 \|\| \<3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ably/ui 支持 TypeScript 吗？

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

### @ably/ui 可以商用吗？

@ably/ui 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @ably/ui 的下载量有多少？

根据 npm 官方下载统计，@ably/ui 在 2026/10/05 – 2026/11/03 这 30 天内被下载 7,483 次，日均约 249 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ably/ui 还在维护吗？

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