# @cdx-ui/utils 中文文档

规范地址：https://npmcn.com/package/%40cdx-ui/utils/

版本：0\.3\.12
npm 元数据更新时间：2026-11-04T15:25:46.189Z
中文译文更新时间：2026-11-09T08:41:17.936Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：133 kB，127 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：react ^18\.2\.0 \|\| ^19\.0\.0，react-native \>=0\.76\.0，react-native-web \>=0\.19\.0
- 首次发布：2026-03-03T18:09:21.381Z
- 最新版本发布：2026-11-04T15:25:45.933Z
- 近 30 天下载量：3423（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：256（近 12 个月 256 个）

## 中文简介

![coverage](https://unpkg.com/@cdx-ui/utils/coverage.svg)

## 安装

```sh
npm install @cdx-ui/utils
```

也可以使用：`pnpm add @cdx-ui/utils`、`yarn add @cdx-ui/utils`、`bun add @cdx-ui/utils`

## README

# @cdx-ui/用户

![coverage](https://unpkg.com/@cdx-ui/utils/coverage.svg)

共有的公用设施,在财政发展服务包中使用.

提供常见的助手,用于样式、事件处理、状态管理和背景传播 [`@cdx-ui/primitives`](https://www.npmjs.com/package/@cdx-ui/primitives) 财务报告和审定财务报表 [`@cdx-ui/components`](https://www.npmjs.com/package/@cdx-ui/components)。 。 。 .

## 安装

```bash
pnpm add @cdx-ui/utils
```

## 出口

### 共同帮助者

| 导出 | 说明 |
| --- | --- |
| `cn(...inputs)` | 合并类名 `clsx` + 键 `tailwind-merge` ——有条件条件和冲突解决在一个呼吁中. |
| `composeEventHandlers(...handlers)` | 将多个事件召回到单个处理器中; 跳过 `null`编号 :`undefined` 条目. |
| `useControllableState(params)` | 既支持受控模式,又支持无控模式的钩子,用于单一值. 衍生物 `isControlled` 从道具是否 `undefined`。 。 。 . |
| `mergeRefs(...refs)` | 将多回调(召回或对象)合并为一回调. |
| `flattenChildren(children)` | 递归平地反应 `children` (包括分块)入入有重键元素的平面阵列. |
| `ariaAttr(condition)` | 回返 `true` (布尔)或 `undefined` ——布尔ARIA属性值的快手. |
| `cva(base, config)` | Class Difficience 管理局用于编写变量驱动的助手 `className` 建业者. `VariantProps<typeof fn>` 生成道具类型. |

### A. 背景情况

| 导出 | 说明 |
| --- | --- |
| `createContext(displayName)` | 环绕回放 `createContext` 返回一个 `[Provider, useHook]` tu. 如果在提供者之外调用, 钩子会丢入描述性错误 `undefined` 诸虫. |

### 样式上下文

内部使用 `@cdx-ui/components` 用于传播从复合根到子元件的变种道具(大小、颜色等).

| 导出 | 说明 |
| --- | --- |
| `ParentContext` | 反应上下文,用于将复合根的变体道具传播到子元件. 包装儿童 `<ParentContext.Provider value={...}>`。 。 。 . |
| `useStyleContext(scope?)` | 读取最近设置的样式背景 `ParentContext.Provider`。 。 。 . |
| `useParentContext()` | 读取全文 `StyleContextMap` 从最近的提供者. |

### 表格控制

低等窗体- 字段状态 `Field` 财务报告和审定财务报表 `Input` 原始的 原始的 原始的.

| 导出 | 说明 |
| --- | --- |
| `useFormControlRoot(props)` | 创建窗体字段( id 生成, 音轨) 的根态对象 `hasFeedbackText`编号 :`hasHelpText` 以便你们集合. |
| `useFormControl(props)` | 将组件级道具与继承的形式控制上下文合并. 组合 `aria-describedby` 从反馈/帮助文本 id. |
| `useFormControlContext()` | 从最近的提供者读取窗体控制状态 . |
| `useReportFormControlLabelFocus(isActive)` | 向父母报告重点/活动状态 `FormControlContext` 用于 `Input`编号 :`Select.Trigger` 触发 `isFocused` 关联标签上的样式 . |
| `useReportFormControlValidation(isInvalid, errorMessage)` | 报告自动验证控件的无效状态并给父信件 `Field` 用于 `DatePicker` 这样 `Field.Error` 编号 : `Field.Helper` 在野外的任何地方都反映出来. |
| `FormControlContext` | 形式控制状态传播的反应上下文对象 . |

## 导出类型

| 类型 | 来源 |
| --- | --- |
| `UseControllableStateParams` | 常见 |
| `VariantProps` | 常见 |
| `Focusable` | 窗体控件 |
| `FormControlContextValue` | 窗体控件 |
| `FormControlFieldProps` | 窗体控件 |
| `FormControlRootProps` | 窗体控件 |
| `FormControlRootReturn` | 窗体控件 |
| `FormControlState` | 窗体控件 |
| `FormControlValidation` | 窗体控件 |
| `StyleContextMap` | 样式 |

## 测试

测试在源文件相邻处( E)`*.test.{ts,tsx}`) (中文(简体) ). 运行在 `utils` 最佳项目:

```bash
pnpm nx run @cdx-ui/utils:test
```

所有运行时间出口都使用 `@testing-library/react-native` (单位:千美元)`renderHook`, (中文(简体) ), `act`) (中文(简体) ).

## 进一步阅读

这个 [Forge UI 文档站点](https://design.candescent.com/docs/getting-started) 盖设及用. 寄存器的内部编写指南涵盖了这些帮助者背后的规律—— `useControllableState` 财务报告和审定财务报表 `composeEventHandlers` 在国家指南中 `cn()` 和 CVA 变体作者在造型指南中.

## 许可证

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

麻省理工学院 2026 Digital First Holdings LLC. 包装的许可证全文 `LICENSE`。 。 。 .

## 常见问题

### 如何安装 @cdx-ui/utils？

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

### @cdx-ui/utils 支持 TypeScript 吗？

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

### @cdx-ui/utils 支持 ESM 还是 CommonJS？

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

### @cdx-ui/utils 可以商用吗？

@cdx-ui/utils 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cdx-ui/utils 的下载量有多少？

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

### @cdx-ui/utils 还在维护吗？

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