# @choco-vanille/ui 中文文档
规范地址：https://npmcn.com/package/%40choco-vanille/ui/
版本：2\.2\.1
npm 元数据更新时间：2026-11-08T23:26:02.486Z
中文译文更新时间：2026-11-09T14:07:27.430Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40choco-vanille/ui
原文对照：https://npmcn.com/package/%40choco-vanille/ui/?lang=original
项目主页：https://github.com/LilianMrzt/choco-vanille-ui#readme
源码仓库：https://github.com/LilianMrzt/choco-vanille-ui
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：5.4 MB，2443 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：16 个
- peer 依赖：react ^19\.0\.0，react-dom ^19\.0\.0，@iconify/react ^5\.2\.1
- 首次发布：2026-07-19T20:48:46.291Z
- 最新版本发布：2026-11-08T23:26:02.291Z
- 近 30 天下载量：3232（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：75（近 12 个月 75 个）
## 中文简介
与"香草取出"和"基础UI"原始人相接而成的回放19UI套.
## 安装
```sh
npm install @choco-vanille/ui
```
也可以使用：`pnpm add @choco-vanille/ui`、`yarn add @choco-vanille/ui`、`bun add @choco-vanille/ui`
## README
# @choco-vanille/ui (英语)
> **个人项目通知:** 该图书馆主要为个人使用而建. 它作为方便而公开发表,但不能保证稳定性、长期维护或后向兼容性。 冒险用吧.
使用 **维特** (图书馆模式), **香草提取** (零运行时间,CSS-in-TS)和 **基础UI** 原始的 原始的 原始的 组成部分是: 预览用 **故事书**。 。 。 .
## 特征
- \* 反应19+类型脚本,船舶无害环境管理+CJS+类型申报
- QQ 香草提取设计系统——一个已完全打入的符号主题 (颜色,间隔,半径,字体大小/重量,阴影,z-index)
- 以 Vanilla 提取为样式的基 UI 组件 `recipe()` (类型) 替换为 `cva`)),编为: `clsx`
- 用于交互式组件的文件目录
- \+ ESLint 平面配置( 类型script- eslint, 反应- hooks, jsx- a11y, 故事本) + Pretier
## 安装
```bash
# npm
npm install @choco-vanille/ui @iconify/react@^5.2.1 react react-dom
# yarn
yarn add @choco-vanille/ui @iconify/react@^5.2.1 react react-dom
# pnpm
pnpm add @choco-vanille/ui @iconify/react@^5.2.1 react react-dom
```
软件包条目自动加载其样式表。 然后使用组件 :
```tsx
import { Typography } from '@choco-vanille/ui';
export function Example() {
return (
<>
Hello world
A typographic primitive.
@choco-vanille/ui
);
}
```
对于需要明确CSS加载的集成,样式表仍保留 可用时间 `@choco-vanille/ui/styles.css`。 。 。 .
## 构成部分
### 图标
所有图标道具接受信任的本地 `IconifyIcon` SVG 数据并通过 `@iconify/react/offline`,无需网络请求或全球登记. 为您选中的收藏安装数据包 :
```bash
pnpm add @iconify-icons/lucide
```
```tsx
// src/icons/index.ts
import type { IconifyIcon } from '@iconify/react/offline';
import searchIcon from '@iconify-icons/lucide/search';
export const IconRegistry = {
searchIcon,
} as const satisfies Readonly>;
```
消费者项目应界定一个 `IconRegistry` 导出所有使用的图标 由项目。 仅在登记册中导入单个图标数据模块, 并将其条目用于组件。 密钥使用骆驼 Case with the `Icon` 后缀, 例如 `searchIcon` 或者说 `warningIcon`; 不导入全部收藏.
```tsx
import { Button, Icon, IconButton } from '@choco-vanille/ui';
import { IconRegistry } from './icons';
const Example = () => (
<>
);
```
图标默认为装饰. 提供 `aria-label` 或者说 `aria-labelledby` 页:1 信息图标;仅由图标控件拥有其可访问名称. 大小(`xs` 结束 `2xl`默认值 `md`, (中文(简体) ), `spin`,包装样式和CSS颜色不变. 参考文献指向SVG. 单色图标继承 `currentColor`; 多颜色图标 可以保持他们的固定颜色。 图书馆的登记册是内部的;每个消费者 拥有其登记册。 公约不需要运行时间提供者或图标 全球登记。 图标不需要 SVG 到反应构建插件 . 只使用可信任的数据, 因为 SVG 天体是作为标记插入的 . 内部的SVG识别器是用于SSR和水合的示例. 已应用 SVG ID必须是非空的,在用下划线取代连字符后是独一无二的.
**中断更改 :** 替换 SVG 反应组件和前者 `IconComponent` 类型为 `IconifyIcon` 数据,包括主要/跟踪和自定义变量 图标。 字符串图标名称不被接受 . `SvgImage` 保留其单独的 SVG 反应组件合同.
### 方框和打字法
`Box` 默认为 a `div`· ; `Typography` 默认为 a `span`都推断出本地人 属性、事件和来自 `as`,包括自定义反应组件. 对于打字, `variant` 也选择元素当 `as` 缺席; `as` 优先,同时 `variant` 保持视觉预设.
```tsx
import { Box, Typography, vars, type BoxProps } from '@choco-vanille/ui';
const linkProps = {
as: 'a',
href: '/account',
padding: 16,
} satisfies BoxProps<'a'>;
export function AccountSummary() {
return (
Account
Open account
Account details and preferences.
);
}
```
框支持定位( E)`inset`,方向冲抵, `zIndex`),弹性和网格 安置、个人边界、, `background`, (中文(简体) ), `boxSizing`, (中文(简体) ), `aspectRatio` 财务报告和审定财务报表 `opacity`。类型学继承了 Box 的布局道具并添加了主题字体家族 (单位:千美元)`sans`, (中文(简体) ), `serif`, (中文(简体) ), `mono`, (中文(简体) ), `fontStyle`, (中文(简体) ), `lineHeight`, (中文(简体) ), `letterSpacing`, (中文(简体) ), `verticalAlign`包装和装饰 基于收件间隔,字体大小, 光度和阴影使用已公布的有限尺度;其他CSS道具接受CSS 数值. `style` 优先于样式道具并接受自定义属性.
限制宽度 `ellipsis`。 。 。 . `maxLines` 接受任何正整数,并 优先于 `ellipsis`; 明确 `style` 能够覆盖断线. 提供另一种读取被剪切的基本内容的方法.
**中断合同变更:** 参考文献和本地属性必须匹配 已变造元素; 明确的非违约通用要求 `as` 或匹配 类型 `variant` 在呼叫现场。 使用 `satisfies` 当编译道具到 保留这些文字选择器,或者在 展开。 无效的令牌、 非无限 CSS 数字和无效行限制 `TypeError`。公开的打字方法使用 `clamp: true` 多线 结构而不是编号 `maxLines` 变体;行数为动态. 边际造型现在为 Box 所拥有, 而非复制于 Typography 食谱。 仍保留构成部分名称 `Box` 财务报告和审定财务报表 `Typography`。 。 。 .
| 类别 | 构成部分 |
| --- | --- |
| **基金会** | `Icon`, (中文(简体) ), `Typography` |
| **版式** | `Box`, (中文(简体) ), `Flex`, (中文(简体) ), `Grid`, (中文(简体) ), `Inset`, (中文(简体) ), `Image`, (中文(简体) ), `Separator`, (中文(简体) ), `Form`, (中文(简体) ), `Fieldset` |
| **行动** | `Button`, (中文(简体) ), `IconButton`, (中文(简体) ), `Toggle`, (中文(简体) ), `ToggleGroup` |
| **表单** | `Autocomplete`, (中文(简体) ), `Calendar`, (中文(简体) ), `Checkbox`, (中文(简体) ), `CheckboxGroup`, (中文(简体) ), `DatePicker`, (中文(简体) ), `Legend`, (中文(简体) ), `RadioGroup`, (中文(简体) ), `RichTextEditor`, (中文(简体) ), `Select`, (中文(简体) ), `Slider`, (中文(简体) ), `Switch`, (中文(简体) ), `TextArea`, (中文(简体) ), `TextField`, (中文(简体) ), `NumberField` |
| **数据显示** | `Avatar`, (中文(简体) ), `AvatarGroup`, (中文(简体) ), `Badge`, (中文(简体) ), `RichTextRenderer`, (中文(简体) ), `Table` |
| **表面** | `Accordion`, (中文(简体) ), `Card`, (中文(简体) ), `Collapsible` |
| **导航** | `Tabs`, (中文(简体) ), `Link`, (中文(简体) ), `Pagination`, (中文(简体) ), `Breadcrumbs`, (中文(简体) ), `Stepper`, (中文(简体) ), `StepIndicator` |
| **重叠** | `Tooltip`, (中文(简体) ), `DropdownMenu`, (中文(简体) ), `ContextMenu`, (中文(简体) ), `Popover`, (中文(简体) ), `HoverCard`, (中文(简体) ), `Dialog`, (中文(简体) ), `AlertDialog`, (中文(简体) ), `Drawer`, (中文(简体) ), `Panel`, (中文(简体) ), `Command` |
| **反馈** | `Skeleton`, (中文(简体) ), `Callout`, (中文(简体) ), `NotificationCard`, (中文(简体) ), `ToasterProvider`, (中文(简体) ), `Toaster`, (中文(简体) ), `Progress`, (中文(简体) ), `EmptyState`, (中文(简体) ), `Spinner` |
| **主题** | `ThemeProvider`, (中文(简体) ), `useTheme` |
## 通知
`NotificationCard` 是独立的视觉复合体: `Header` 包含 `Icon`, (中文(简体) ), `Title` 财务报告和审定财务报表 `Close`, (中文(简体) ), `Body` 包含 `Description` 或自定义内容,以及 `Footer` 包含 `Actions`区域是可选的 `NotificationCard.Icon` 在使用复合内容时明确. `Header` 供给根 `onClose` 按钮,除非 `Close` 插槽已存在 。 方便道具仍然包括 变相图标. `ToasterProvider` 用同一张牌挂载两个频道 暂时的吐司和持续的通知。 一次包装应用程序 在所希望的主题范围内,外部转换或剪接容器:
```tsx
import { Button, ThemeProvider, ToasterProvider, useNotification, useToast } from '@choco-vanille/ui';
const Actions = () => {
const { showSuccess } = useToast();
const { show } = useNotification();
return (
<>