@ably/ui

中文文档

19.0.0发布于 2026/10/16Apache-2.0TypeScript近 30 天下载 7483

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

文档目录20 节

图书馆结构
安装
国家预防机制
设立 TailwindCSS
使用量
图标
字体
无障碍
发展
快速启动
手动设置
SWC 编译旗帜
发布审查应用程序的预发包
构成部分
正在格式化文件( L)
添加新组件
出版
《塔克公约》(摩纳哥)
审查应用程序
正在测试

聪明的

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

图书馆结构

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

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

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

安装

国家预防机制

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

pnpm add @ably/ui # Preferred

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

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

// AblyUi.Core is now available on window

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

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

将 JavaScript 导入为 Accordion 组件 :

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

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

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

设立 TailwindCSS

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

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

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,
    },
  },
}));

在 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:

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

使用量

图标

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

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

我们提供对收押地和第三方托管的当地定制资产的访问赫罗伊孔斯图书馆.

反应应用( 建议)

使用图标反应组件

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

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

反应组件如何工作

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

非反应应用程序

使用 SVG 打印表

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

<!-- 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 方法来进行高级使用, 如悬浮状态组类 :

<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 文件夹将 :

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

Heroicons 整合

系统自动回落到赫罗伊孔斯当找不到本地图标时, 使用此命名常规 :

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

何处 variant 可为:

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

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

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

字体

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

无障碍

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

- 使用正确的 HTML 元素: 导航锚地、互动按钮、列表列表等

使用屏幕读取器进行测试(例如) 用网络转子在Mac OSX上的声音(中文(简体) ) ——确认设计有适当的水龙头目标,形成对比 ——使用 aria 属性在 HTML 中达到极限 ——不要打破网络平台(即不要打破后键,滚动,页内链接等行为)

发展

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

快速启动

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

./bin/dev

此脚本将 :

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

手动设置

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

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

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

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

SWC 编译旗帜

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

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

// 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) .

您需要认证无将出版.

以上之后,你应该:

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

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

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

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

释放前:

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

更新发布前版本 :

在一个原子执行中提交所有更改(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 在堆放上下文和z-index上写得很好.

正在格式化文件( L)

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

添加新组件

增加一个新的组成部分:

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

在故事书中看到此组件:

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

出版

我们用语义版 2.0.0 用于版本不同的图书馆版本.

软件包将公布于 GitHub 私人登记处。。。 .

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

发布后,您可以手动触发 update-ably-ui 创建单一的 PR 草案的工作流程伏尔泰财务报告和审定财务报表网站与新的精通版本.

启动释放:

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

这将向国家防范机制公布该软件包,并部署一个新的故事书网站 https://hably.github.io/ably-ui/ 互联网档案馆的存檔,存档日期2013-12-02。为了更新消费应用程序,手动启动工作流程,该工作流程将为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

见根文件/磁盘完整的细节单列标注公约.

审查应用程序

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

要创建审查应用程序:

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

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

正在测试

ably-ui 用途测试与 Vitest 的故事书加词以自动将所有故事变成可执行测试。这意味着我们不必为故事写明确的测试尽管我们有能力写播放函数,这让我们可以测试更详细的相互作用.

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

您可以使用 :

pnpm test

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

版本与发布记录

@ably/ui 共发布 762 个版本，首次发布于 2021/10/18；过去 12 个月发布了 80 个版本。

版本	发布日期	距今
`19.0.0`latest	2026/10/16	20 天前
`18.5.0`	2026/08/13	2 个月前
`18.4.1`	2026/08/03	3 个月前
`18.4.0`	2026/08/03	3 个月前
`18.3.2`	2026/06/26	4 个月前
`18.3.1`	2026/06/17	4 个月前

其他发布通道：dev → 18.0.0-dev.dbc599e55b。

关于 @ably/ui 的常见问题

@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 和提交记录判断。

npm install @ably/ui

pnpmpnpm add @ably/ui
yarnyarn add @ably/ui
bunbun add @ably/ui

peer 依赖react ^18.2.0 || ^19.0.0react-dom ^18.2.0 || ^19.0.0posthog-js ^1.217.4 || <2mixpanel-browser ^2.60.0 || <3

npm 7+ 与 pnpm 8+ 会自动安装必需的 peer 依赖，Yarn 需手动安装。

在你的项目目录中运行此命令。

近 30 天下载

7,483

约 7483 次日均 249 次

统计周期 2026/10/05 – 2026/11/03
数据来自 npm 官方下载统计，1 天前更新

最新版本19.0.0发布于 20 天前

开源许可Apache-2.0宽松许可

包体积7.8 MB1,446 个文件 · 解压后

运行依赖22 个另有 4 个 peer 依赖

TypeScript自带类型

发布版本762 个近 12 个月 80 个

首次发布2021/10/185 年前

元数据更新2026/10/16

每一个软件包背后，
都有分享与创造的人。