# @hanzo/ui 中文文档

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

版本：8\.33\.4
npm 元数据更新时间：2026-11-13T19:02:41.741Z
中文译文更新时间：2026-11-17T08:33:50.304Z
软件包许可：Apache-2\.0 OR MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40hanzo/ui
原文对照：https://npmcn.com/package/%40hanzo/ui/?lang=original

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

- 包体积（解压后）：13.3 MB，4810 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：16 个
- peer 依赖：next \>=16\.3\.3，react \>=19\.2\.8，@hanzo/cd \>=0\.1\.2，react-dom \>=19\.2\.8，@hanzo/gui ^8\.3\.5，@hanzo/iam \>=0\.21\.26，@hanzo/pay \>=0\.1\.1，@hanzo/data \>=1\.2\.4，@hanzo/i18n \>=0\.4\.0，next-themes \>=0，@hanzo/event \>=0\.3\.63，@hanzo/plans \>=1\.8\.1，@hanzo/usage \>=0\.1\.13，@hanzo/voice \>=0\.1\.19，@hanzo/canvas \>=0\.2\.3，@hanzo/composer \>=0\.2\.0，@hanzogui/shell ^8\.3\.5，@hanzogui/toast ^8\.3\.5，react-hook-form \>=7，@hanzo/dashboard \>=0\.2\.0，@hanzogui/config ^8\.3\.5，@hanzogui/telemetry ^8\.3\.5，@hanzogui/next-theme ^8\.3\.5，@hanzogui/animations-css ^8\.3\.5，@hanzogui/lucide-icons-2 ^8\.3\.5
- 首次发布：2024-02-14T20:50:10.835Z
- 最新版本发布：2026-11-13T19:02:41.275Z
- 近 30 天下载量：34386（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：561（近 12 个月 393 个）

## 中文简介

汉藏UI——唯一可口的汉藏组件库,在@hanzo/gui + @hanzo/deign. 一个底盘:每个组件都通过@hanzo/gui原始来制作,所以同样导入的作品在网络,原生(expo)和桌面(Tauri)上. 自足(主题.cs),预告

## 安装

```sh
npm install @hanzo/ui
```

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

## README

# @hanzo/ui (英语)

这个 **一个** 韩佐组件库,基于 [`@hanzo/gui`](https://github.com/hanzoai/gui) (Tamagui) 所以每个组件运行 **网络、 本地( iOS) 和桌面**它统一了过去三所破碎的房屋—— `@hanzo/data`控制台的应用 `components/ui/*`,并临时复制——成一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一克一.

> **v8+** 一个底盘: 每个组件都通过 `@hanzo/gui`,所以在网络、本地和桌面上导入一个作品。 v5.x Radix + Tailwind 线条是不同的架构并退役——参见 `CONSOLIDATION.md` 在雷波根.

## 安装

```sh
bun add @hanzo/ui @hanzo/gui @hanzo/data
```

`@hanzo/gui`, (中文(简体) ), `@hanzo/data`,以及 `react` 是同龄人.

## 两个正交层, 一个包

```tsx
// product / app layer — charts, metrics, headers, status, empty states, combobox…
import { PageHeader, Sparkline, LineChart, EmptyState, StatusTag, ComboBox, tokens } from '@hanzo/ui'

// metadata-driven record layer — RecordsView & the typed field editors (@hanzo/data)
import { RecordsView, DataTable, BoardView, RecordDetail, registerField } from '@hanzo/ui/data'
```

-   **`@hanzo/ui`** 产品/应用组件层:
    -   **图表** (无依赖内含SVG): `Sparkline`, (中文(简体) ), `LineChart`, (中文(简体) ), `BarChart`, (中文(简体) ), `Donut`, (中文(简体) ), `BarRows` ——悬浮工具提示,轴勾,诚实 `null` 在两个真正的点.
    -   **度量衡** 瓷砖/平板: `MetricCard`, (中文(简体) ), `MiniBars`, (中文(简体) ), `UtilBar`, (中文(简体) ), `LegendDot`, (中文(简体) ), `Panel`, (中文(简体) ), `HintButton` (+ 数) `MetricSparkline`) (中文(简体) ).
    -   **颜色**数字 : `PageHeader`, (中文(简体) ), `StatusTag`, (中文(简体) ), `EmptyState` (DO/Vercel级首跑), `PrimaryButton`, (中文(简体) ), `HanzoMark`, (中文(简体) ), `ProductIcon`, (中文(简体) ), `ProviderLogo`。 。 。 .
    -   **身份三进制** -一行铬 三台开关: `OrgSwitcher` (工作空间, `direction` 上下两地, `footer` 内部的应用程序切换器 `AppHeader`,以及 `UserMenu` (我是谁). `AppHeader` 由所有三个组成;每个都单独可导入,所以不需要整条头的账户菜单的表面不会写出第六个.
    -   **设置**数字 : `Fieldset` - 具有任意破坏性的团体 `Field*` 排行而入. 没有 `Panel`: 这是一个仪表板平面砖.
    -   **互动**数字 : `ComboBox` (可打出,ReDoS安全过滤器), `SelectMenu`, (中文(简体) ), `SlideOver` (抽屉11), `Toast` (单位:千美元)`useToast`, (中文(简体) ), `Reorder` (指针 DnD), `Field*` 排队, `CopyButton`, (中文(简体) ), `SecretInput` (任务 ) 披露 —— 副本), `Pagination` (+纯度) `pages` 规则), `FadeIn`, (中文(简体) ), `ThemeToggle`常规 `DataTable<T>`。 。 。 .

> **面具需要两种拼写.** `secureTextEntry` 反应原生和克来 **丢入网络**,所以一个只携带道具的输入可以使该道具在纯文本中成为秘密; `type="password"` 是网络之一 本地人忽略它. `masked(on)` 两者兼而有之 `SecretInput` 财务报告和审定财务报表 `<FieldText secure>` 使用时。 永远不要通过 `secureTextEntry` 一个人.

-   **键**数字 : `tokens`, (中文(简体) ), `TAG_TONES`, (中文(简体) ), `tagTone` ——平稳地,暗地先行地,取出"锌与黑"的身份.
-   **`@hanzo/ui/data`** ——由元数据驱动的记录层(真相来源: `@hanzo/data`: `RecordsView` (表 qq 板, 过滤器/ sort/ 搜索/ 组, 内置编辑, 保存视图), 记录网格 `DataTable`, (中文(简体) ), `BoardView`, (中文(简体) ), `RecordDetail`编号 :`RecordForm`,每个键入的字段编辑器,字段注册,以及纯视图/sort/filter逻辑.

两层都是 **演示文稿 + 数据输入**:主机供应行和持续回调;组件只拥有交互状态. 没有任何东西进口一个应用程序 `~/lib`。 。 。 .

> 每层都有一个 `DataTable` - 产品是通用型的 `<T>` 列表; 数据是字段驱动的记录网格。 保持记录层 `./data` 子路径保持每个名称的清晰性.

## DocType 渲染器 – 每个商务应用程序一个用户界面

`@hanzo/ui/framework` 使 **半藏框架** DocType 引擎 (`hanzoai/cloud clients/framework`,住在这里 `/v1/framework/*`; 也作为 [`hanzoai/framework`](https://github.com/hanzoai/framework) 结束 [`hanzoai/doctype`](https://github.com/hanzoai/doctype)) (中文(简体) ). 发动机是 元数据驱动:CMS Page、ERP销售令、服务台票和客户关系管理 公司是同类的——有打字场的多克Type. 所以他们得到 同样的渲染器。 一个 **app道是一个 `module` 过滤器** 在 DocType 登记簿上加 其副本; 没有可漂移的每行列表、形式、细节或构建者.

```tsx
import { createFrameworkClient } from '@hanzo/ui/framework/core'      // transport only
import { CollectionsBrowser, DocTypeRecords, DocTypeDetail } from '@hanzo/ui/framework'

// The HOST owns transport: paths are relative to the framework root, so the app
// decides the origin + the credential. Nothing in the library picks a URL.
const client = createFrameworkClient({
  get: (p) => api.get(`/v1/framework/${p}`),
  post: (p, b) => api.post(`/v1/framework/${p}`, b),
  put: (p, b) => api.put(`/v1/framework/${p}`, b),
  del: (p) => api.del(`/v1/framework/${p}`),
})

<CollectionsBrowser client={client} module="erp" label="ERP" … onOpen={openCollection} />
<DocTypeRecords client={client} doctype="erp-sales" onOpen={…} onCreate={…} />
<DocTypeDetail  client={client} doctype="erp-sales" name={name} onBack={…} onView={…} />
```

**先移动——规则,不是倒置.** 版式由 容器的测量宽度(`onLayout`宽屏幕上的狭长窗子仍然 一个电话),"尚未测量"的答案是电话. 所以第一张画.. 包含——是堆叠式 **纸牌** 每个记录 `@hanzo/data` 表格为 一旦盒子证明它能握住它,就应用了增强。 每个控制器都满足 44px自制地板(WCAG 2.5.5),电话宽度,桌子尊崇DocType自己的 `inListView` 投影到十二字段文档不会变成水平 卷轴墙.

**两个条目,因为它们是两个不同的事物.** `./framework/core` 这是 合同 — 有线类型、 客户端、 元数据%%%% 映射、 构建者 投影,媒体模型。 它不进口反应和不进口 `@hanzo/gui`数据 层、服务器路由或纯节点测试可以绑定引擎而无需加载 组件树. `./framework` 全部再出口 加上视图.

**港口,没有约束.** 客户要一个 `FrameworkTransport`; DAM 需要一个 `MediaStore` (确保-桶/预签/放/删除)和a **桶参数**, (中文(简体) ), 因此,ERP附件 从来没有降落在一个桶 以CMS命名。 运行是 `onOpen`编号 :`onCreate`编号 :`onBack`编号 :`onView` 回调 —— 任何路由器都不导入 .

**一个入口,不是两个.** 8.0.24 第一次发货 `./framework` 同样的升起 `createFrameworkClient(Transport)` 形状但无建构器,没有DAM和移动 布局, 插入 `renderBuilder`编号 :`renderMedia` 换句话说 8.0.25是趋同之处: 同一个条目,一个超级集执行, 每8.0.24个名字仍然解决—— `Transport` 别名 `FrameworkTransport`, (中文(简体) ), `Loader` 别名流入 `Loading`, (中文(简体) ), `setupDescription`编号 :`setupBullets` 保留可选内容( 它们现在倒回复制 DERIVED ) 从LANE, 即实际的修补—— 旧的默认是单行道的单行道词),以及 `renderBuilder`编号 :`renderMedia` 仍然赢得当供应。 一个没有经过的东道主 现在得到真正的内置 `CollectionBuilder`编号 :`MediaGrid` 而不是什么都没有.

## 动议

平稳运动词汇表(`FadeIn`,抽屉/回放过渡, 骨架发光,活脉冲) 船作为一个样式表。 在应用根导入一次 :

```ts
import '@hanzo/ui/styles/motion.css'
```

每个动画的荣誉 `prefers-reduced-motion`。 。 。 .

## 扩展记录层

```tsx
import { registerField } from '@hanzo/ui/data'
registerField('rating', { Display: MyStars, Input: MyStarPicker })
```

## 分析——一面旗帜,各组成部分自报

```tsx
import { Hanzo } from '@hanzo/ui'

<Hanzo analytics={{ product: 'console', ingestKey: process.env.NEXT_PUBLIC_PUBLISHABLE_KEY }}>
  <App />
</Hanzo>
```

这就是整个线路。 每次点击、格式更改、提交和路由更改 树内到达一个入口(`POST /v1/event`(注: 发生于 `onClick` 管理者在任何地方报告任何事, 且不更改呼叫站点 :

```jsonc
{
  "event": "$click",
  "$el": "card/button[Save]",      // the significant-node trail, root→leaf
  "$role": "button",
  "$component": "button",          // from the data-slot every primitive carries
  "$name": "Save"
}
```

组件名称是真实的 **生产**。每个原始的在这里邮票 `data-slot` 通过一名助手(`slot()`),捕捉引擎读取它——所以 归属不取决于反应纤维所有者,生产就是建立这种结构的 缩小范围 一个想要一个更好的名字的部件 比它的插槽说一次, 本身: `data-hz-name="SaveButton"` 排名高于一切.

### 它的构成—— 每一个

| 关切 | 软件包 | 只有一个 |
| --- | --- | --- |
| 客户端 + 有线 | [`@hanzo/event`](https://npmcn.com/package/%40hanzo/event) | 结束点 `POST /v1/event`,批发,卸载信标 |
| 捕获引擎 | [`@hanzo/observe`](https://npmcn.com/package/%40hanzo/observe) | 授权听众、语义注释、编辑 |
| 提供者+同意 | `@hanzogui/telemetry` | `<TelemetryProvider/>`,哪个 `analytics` 调制 |

`analytics` 是一个 **道具,不是默认**。挂载组件库必须 从未启动网络对话, 应用程序没有要求: 没有它 `<Hanzo>` 使不提供商、不安装听众、不发送任何信息.

### 不能重复计算

已经挂载的应用程序 `<TelemetryProvider/>` 自己离开 `analytics` 关闭——但如果两者同时挂起,事件仍然没有翻一番. 抓获 引擎安装 _授权_ 听众在根上,所以两个引擎在一个根上 (a) 报告每一次互动`Symbol.for`这样 复制一个捆绑中的包复制件仍相见)给出 根到第一个引擎,然后留下任何后一个惰性。 两个供应商也提供 解析同一个客户端, 所以无论用哪种方式都有一个会话和一个流 .

### 隐私

同意决定是否运行其中任何一项: 全球隐私控制, 不跟踪, 和存储的选择 一个同意横幅记录 —— 排在浏览器信号之后 内 **两者** 方向,因为这是明确的含义。 除此之外:

-   **输入值被扣.** `$input`编号 :`$change` 携带田野的种类 值长度,永远不要输入文本.
-   **敏感领域从不捕捉** - 密码,电子邮件,卡片,cvv, 表示,ssn——甚至没有长度.
-   **`data-hz-private`** 任何元素都排除了整个树下.

### 一个摄入键

`ingestKey` 是一个可出版的 `pk-…` ——只写作,安全地装入捆绑,每件薄荷 带 `POST /v1/keys {"type":"publishable"}`关闭它,客户端读 `NEXT_PUBLIC_PUBLISHABLE_KEY` 从建筑洞,即拼写 舰队已经随行结束( KMS holds) `deploy/PUBLISHABLE_KEY`; 数据 Dockerfile 把它当作一个建构弧并用它再出口 `NEXT_PUBLIC_` 前缀 Next 需要插入它。 表面没有关键报告 只为任何人 - 边缘拒绝 在所有人无法读取的情况下,不提交不可归属的书写文件.

对于一个没有建设步骤的页面, 同样的铁丝船作为主机标签,服务 其地址为: `<script defer src="https://api.hanzo.ai/v1/event/tag.js" data-key="pk-…">`。 。 。 . 它是一个还是另一个——一个同时运行的页面两次计算每个页面视图.

### 命名无法看到组件的瞬间

自动抓取报告所点击的内容; 它不知道点击 _曾经_ (单位:千美元) 结账 被证实的事件现场直播 `@hanzo/ui/product`,一个封闭动词设置 一个事件名称,在同一客户端和同一流上:

```tsx
import { useEmit, InstrumentSurface } from '@hanzo/ui/product'

const emit = useEmit()
emit({ component: 'PlanCard', action: 'select', id: 'pro' })
```

## 设计原则

-   **一个家,没有重复** ——组件被取出,从不复制. 记录层的真相来源 `@hanzo/data`· ; `@hanzo/ui` 作是说已.
-   **主机不可知论** ——数据+效应被注入;与任何应用程序相接为零.
-   **清洁间** 我们自己在@hanzo/gui上的代码;麻省理工学院衍生的部件记入NOTICE.
-   **跨平台** ——网络+本土+桌面,因为它只是 `@hanzo/gui`。 。 。 .

Hanzo AI, Inc——特许经营 [阿帕奇 - 2.0](https://npmcn.com/package/%40hanzo/ui/LICENSE-APACHE) 或 [麻省理工学院](https://npmcn.com/package/%40hanzo/ui/LICENSE-MIT)在你身边 选项。 HIP-0137 (英语:`hanzoai/hips`) (中文(简体) ).

## 常见问题

### @hanzo/ui 是什么？

汉藏UI——唯一可口的汉藏组件库,在@hanzo/gui \+ @hanzo/deign\. 一个底盘:每个组件都通过@hanzo/gui原始来制作,所以同样导入的作品在网络,原生\(expo\)和桌面\(Tauri\)上\. 自足\(主题\.cs\),预告

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

在项目目录运行 npm install @hanzo/ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19\.2\.8）、react-dom（\>=19\.2\.8）、@hanzo/gui（^8\.3\.5）、@hanzo/data（\>=1\.2\.4）、@hanzo/event（\>=0\.3\.63）、@hanzo/voice（\>=0\.1\.19）、@hanzo/composer（\>=0\.2\.0）、@hanzogui/toast（^8\.3\.5）、react-hook-form（\>=7）、@hanzogui/config（^8\.3\.5）、@hanzogui/telemetry（^8\.3\.5）、@hanzogui/animations-css（^8\.3\.5）、@hanzogui/lucide-icons-2（^8\.3\.5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

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

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

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

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

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

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

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

