# @serenis/ui 中文文档

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

版本：6\.94\.0
npm 元数据更新时间：2026-11-02T10:55:41.552Z
中文译文更新时间：2026-11-02T11:08:44.599Z
软件包许可：LicenseRef-PolyForm-Noncommercial-1\.0\.0

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

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

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

- 包体积（解压后）：857 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：6 个
- peer 依赖：react \>=19\.0\.0，@serenis/cdk \*，@types/react \>=19\.0\.0，@serenis/hooks \*，@serenis/icons \*，@serenis/numbers \*，@serenis/strings \*，styled-components \>=6\.0\.0，@serenis/design-tokens \*
- 首次发布：2026-07-03T11:44:46.170Z
- 最新版本发布：2026-11-02T10:55:41.373Z
- 已发布版本数：48（近 12 个月 48 个）

## 中文简介

Serenis设计系统的主UI组件库。提供可重用的React组件，包括故事书文档、设计令牌集成和可访问性支持。组件的样式与CSS模块和 `@serenis/design-tokens`.

## 安装

```sh
npm install @serenis/ui
```

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

## README

# @serenis / ui

Serenis设计系统的主UI组件库。提供可重用的React组件，包括故事书文档、设计令牌集成和可访问性支持。组件的样式与CSS模块和 `@serenis/design-tokens`.

## 安装

```bash
npm install @serenis/ui
```

## 快速启动

```bash
# Build
yarn workspace @serenis/ui build

# Dev (watch mode)
yarn workspace @serenis/ui dev

# Test
yarn workspace @serenis/ui test

# Typecheck
yarn workspace @serenis/ui typecheck

# Lint
yarn workspace @serenis/ui lint
yarn workspace @serenis/ui lint:css
```

当从npm中使用已发布的包时，只需加载一次组件CSS模块 `import '@serenis/ui/css'`。这是单船 `dist/index.css` 用于所有css模块组件。Monorepo应用程序解决 `@serenis/ui` To source不能导入它（应用捆绑器处理） `*.module.css`）. 每个组件的CSS加载可能会在以后取代它。

```tsx
import '@serenis/ui/css'
```

```tsx
import { cx } from '@serenis/design-tokens'
import { Button, Card } from '@serenis/ui'
;<Card>
  <div className={cx('flex', 'flex-col', 'gap-sm')}>
    <h2 className={cx('typography-h2')}>Session details</h2>
    <p className={cx('typography-paragraph', 'text-neutral-80')}>Your next session is scheduled for tomorrow.</p>
    <Button kind="primary">Confirm</Button>
  </div>
</Card>
```

## 目录结构

```text
libraries/ui/
├── src/
│   ├── {ComponentName}/
│   │   ├── index.tsx               # Main component (or {ComponentName}.tsx)
│   │   ├── index.test.tsx          # Tests
│   │   ├── Playground.stories.tsx  # Primary Storybook story
│   │   ├── Overview.mdx            # Component documentation
│   │   └── types.ts                # Type definitions (if complex)
│   ├── Form/                       # Composite form module
│   │   ├── TextField/
│   │   ├── TextAreaField/
│   │   ├── SelectField/
│   │   ├── PasswordField/
│   │   ├── PhoneNumberField/
│   │   ├── PinCodeField/
│   │   ├── Autocomplete/
│   │   ├── MultiSelect/
│   │   ├── Checkbox/
│   │   ├── CheckboxButton/
│   │   ├── Radio/
│   │   ├── RadioButton/
│   │   ├── SliderField/
│   │   ├── Switch/
│   │   ├── SwitchField/
│   │   ├── FileUploadField/
│   │   ├── internal/               # Shared internal chrome and styles
│   ├── utils/                      # Shared utilities (shouldForwardProp)
│   └── index.ts                    # Public API barrel
├── dist/                           # Built output (gitignored)
├── tsup.config.ts                  # Bundle config
└── package.json
```

## 组件目录

类别匹配故事书(`*.stories.tsx` / `Overview.mdx` `<Meta title>`): **一般**， **数据显示**， **反馈**， **形式**， **导航**， **布局**.

### 一般

| 组件 | 描述 |
| --- | --- |
| 按钮 | 主要的交互元素——动作、提交、导航 |
| 文本 | **弃用。** 排版原始 |

### 数据显示

| 组件 | 描述 |
| --- | --- |
| 手风琴 | 具有触发器和可折叠内容的可扩展部分 |
| AccordionList | 呈现多个accordion的方便包装器 |
| 《阿凡达》 | 带有基于名称的首字母缩略词的圆形图像 |
| 徽章 | 用于计数和呈现的角指示器（数字或自定义内容） |
| 卡 | 具有标高、轮廓和背景变体的基础表面 |
| 芯片 | 紧凑的状态标签与图标和种类为基础的颜色 |
| 报价 | 带有左边框重音的语义blockquote |
| 建议 | 带有role="note"和特定类型背景的上下文注释 |
| 选项卡 | 带有WAI-ARIA选项卡模式和溢出的选项卡界面 |
| SegmentedControl中 | 分段式标签切换2-5个选项 |
| 瓷砖 | 带有图标、标题、描述和动作槽的卡片 |
| 模态 | 以拖放为中心的对话框，焦点陷阱，复合API |
| 抽屉里 | 滑入面板（手机底部，桌面右侧），复合API |
| BottomSheet | 具有多步高度的移动底板，可拖动调整大小 |
| 弹出窗口 | 锚定到参考元素的点击触发的浮动内容 |
| 工具提示 | 悬停/聚焦触发的浮动信息锚定到参考元素 |

### 反馈

| 组件 | 描述 |
| --- | --- |
| 警报 | 带有role="alert"、图标和动作槽的状态横幅 |
| 加载程序 | 支持preferences -reduce -motion的SVG旋转器 |
| 骨架 | 加载带有闪烁动画和排版对齐的占位符 |

### 形式

该桶还输出低级原语(`TextInput`， `TextArea`， `Select`， `Checkbox`， `Radio`， `Switch`， `Hint`， `Label`)用于高级使用-首选产品代码中下面的字段组件。

| 组件 | 描述 |
| --- | --- |
| 文本框 | 文本输入与浮动标签，提示/错误，ARIA接线 |
| TextAreaField | TextField的多行变体 |
| SelectField | 带有浮动标签和提示/错误的本机选择 |
| PasswordField | 文本字段与可见性切换 |
| PhoneNumberField | 带有手机特定输入默认值的TextField （type, inputMode, autoComplete） |
| PinCodeField | 分段OTP输入 |
| 自动完成 | TextField与浮动建议下拉 |
| 多选 | 多选择组合框与芯片和复选框列表框 |
| CheckboxButton | 带有标签和提示的卡片式复选框 |
| RadioButton | 带有标签和提示的卡片式收音机 |
| SliderField | 在有序的比例上选择一个选项，用拇指画出一条轨迹 |
| SwitchField | 内联开关标签，提示，和标签位置 |
| FileUploadField | 使用react-dropzone上传拖放文件 |

### 导航

| 组件 | 描述 |
| --- | --- |
| 链接 | 内联文本链接的样式锚 |
| NavigationButton | 用于菜单和操作列表的列表项按钮 |
| BottomBar | 固定位置移动底部导航条 |
| 面包屑 | 带雪佛龙分隔符的导航面包屑路径 |
| 导航条 | 带有滑动活动指示器的主导航 |
| NavBarGroup | NavBar项目在NavBar中的胶囊 |
| NavBarItem | NavBarGroup的图标和标签项，通过as多态 |
| 侧边栏 | 可折叠的侧边栏导航 |
| SideBarItem | 侧边栏的导航项（包裹NavigationButton） |
| SideBarUser | 用户头像+姓名/电子邮件显示侧边栏底部槽 |
| TopBar | 带有徽标和背面导航的粘性页眉 |
| TopBarBack | 背面链接与雪佛龙图标的TopBar的背面槽 |

### 布局

| 组件 | 描述 |
| --- | --- |
| 分频器 | 水平/垂直分隔线 |

## 依赖关系

| 依赖 | 角色 |
| --- | --- |
| `@serenis/cdk` | 交互原语（可按压、可扩展） |
| `@serenis/design-tokens` | 颜色，间距，排版，高度，边界半径 |
| `@serenis/icons` | 按钮，警报，手风琴等图标组件。 |
| `@serenis/hooks` | 共享React钩子 |
| `@serenis/numbers`， `@serenis/strings` | 格式化工具 |
| `styled-components` | CSS-in-JS(使用 `@sanity/styled-components` 叉) |
| `@floating-ui/react` | 定位弹出窗口，工具提示，模态，抽屉，底部表，自动完成 |
| `framer-motion` | 动画模式，底部表单 |
| `react-dropzone` | FileUploadField的文件上传 |

## 样式约定

-   **CSS模块**：每个组件在一个colocation中拥有自己的样式 `index.module.css`;组件源中没有实用程序类。看到 [文档/代理/ styling.md](https://npmcn.com/package/docs/agents/styling.md).
-   **设计令牌** 对于所有视觉值-永远不要硬编码十六进制颜色，像素大小或字体值。

## 文档

-   **故事书**每个组件都有一个 `Playground.stories.tsx` 和一个 `Overview.mdx` 它的来源在 `libraries/ui/src/{ComponentName}/`
-   **Overview.mdx**：包含道具、模式、做/不做和已知异常的全面文档
-   **AGENTS.md**：面向代理的API参考-参见 [AGENTS.md](https://npmcn.com/package/%40serenis/ui/AGENTS.md)

## 消费者

-   **应用程序**： `apps/web` (初级) `apps/blog`， `apps/nutrition-blog`， `apps/website`， `apps/design-system` (故事书主机)
-   **库**： `libraries/shared-components` （`@serenis/shared-components`)， `libraries/ui-deprecated` （遗产-首选） `@serenis/ui`）

## 构建

捆绑与 [tsup](https://tsup.egoist.dev/) 转化为ESM + CJS + TypeScript声明。工作空间依赖是外部化的。

## 许可证

PolyForm非商业1.0.0 -参见 [许可证](https://npmcn.com/package/%40serenis/ui/LICENSE) 查看全文。

## 常见问题

### @serenis/ui 是什么？

Serenis设计系统的主UI组件库。提供可重用的React组件，包括故事书文档、设计令牌集成和可访问性支持。组件的样式与CSS模块和 @serenis/design-tokens\.

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

在项目目录运行 npm install @serenis/ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19\.0\.0）、@serenis/cdk（\*）、@serenis/hooks（\*）、@serenis/icons（\*）、@serenis/numbers（\*）、@serenis/strings（\*）、styled-components（\>=6\.0\.0）、@serenis/design-tokens（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

### @serenis/ui 支持 ESM 还是 CommonJS？

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

### @serenis/ui 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

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

@serenis/ui 使用 LicenseRef-PolyForm-Noncommercial-1\.0\.0 许可。声明的许可为 LicenseRef-PolyForm-Noncommercial-1\.0\.0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

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

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