# @ctrl-ui/react 中文文档 规范地址：https://npmcn.com/package/%40ctrl-ui/react/ 版本：0\.10\.0 npm 元数据更新时间：2026-11-10T16:11:48.975Z 中文译文更新时间：2026-11-11T04:04:43.345Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40ctrl-ui/react 原文对照：https://npmcn.com/package/%40ctrl-ui/react/?lang=original 项目主页：https://control-ui.dev/ 源码仓库：https://github.com/damien-schneider/control-ui ## 关键信息（来自 npm 元数据） - 包体积（解压后）：2.6 MB，736 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：0 个 - peer 依赖：zod ^4\.6\.5，clsx ^2\.1\.1，cmdk ^1\.1\.1，diff ^9\.0\.0，react ^19\.2\.8，shiki ^4\.4\.3，frimousse ^0\.4\.0，react-dom ^19\.2\.8，@tiptap/pm 3\.31\.4，streamdown ^2\.6\.0，react-email ^6\.9\.5，@tiptap/core 3\.31\.4，lucide-react ^1\.47\.0，@tiptap/react 3\.31\.4，@xyflow/react ^12\.12\.0，@base-ui/react ^1\.9\.0，@biomejs/biome \>=2\.5\.0，tailwind-merge ^3\.7\.0，@tanstack/charts ^1\.1\.0，@tiptap/markdown 3\.31\.4，prosemirror-view ^1\.42\.3，react-day-picker ^10\.0\.1，libphonenumber-js ^1\.13\.13，prosemirror-model ^1\.25\.11，prosemirror-state ^1\.4\.4，prosemirror-keymap ^1\.2\.3，@tiptap/starter-kit 3\.31\.4，prosemirror-history ^1\.5\.0，prosemirror-commands ^1\.7\.2，@tiptap/extension-list 3\.31\.4，react-resizable-panels ^4\.12\.4，@tanstack/react-virtual ^3\.14\.13，@tiptap/extension-image 3\.31\.4，@tiptap/extension-table 3\.31\.4，class-variance-authority ^0\.7\.1，react-phone-number-input ^3\.4\.18，@tiptap/extension-paragraph 3\.31\.4 - 首次发布：2026-09-05T22:46:09.226Z - 最新版本发布：2026-11-10T16:11:48.558Z - 近 30 天下载量：3346（2026-10-11 至 2026-11-09，npm 官方下载统计） - 已发布版本数：41（近 12 个月 41 个） ## 中文简介 100+ 用于 Tailwind CSS 和 Shadcn/ui 的回放组件:取取取器,树,编辑器,画布,应用模板,以及 AI 聊天表面,具有中性默认和消费者拥有的主题. ## 安装 ```sh npm install @ctrl-ui/react ``` 也可以使用：`pnpm add @ctrl-ui/react`、`yarn add @ctrl-ui/react`、`bun add @ctrl-ui/react` ## README # @ctrl-ui/反应 每个控制UI组件,块和原始有中性默认. 包内没有皮肤预设,不需要提供者或皮肤配置. 使用 [登记](https://control-ui.dev/get-started) 当您想要拥有和编辑组件源时. ## 安装 ```bash bun add @ctrl-ui/react ``` 需要反应19和Tailwind CSS v4. 在您的全球 CSS 中连接样式一次 : ```css @import "tailwindcss"; @import "@ctrl-ui/react/styles/index.css"; @source "../node_modules/@ctrl-ui/react/dist"; ``` ## 使用 ```tsx import { Button } from "@ctrl-ui/react/ui/button"; ``` 导入路径映射注册树 。 运送更少的CSS,导入 `styles/theme.css` 只有配方 和效果 您的组件使用. ## 文本和类名称 文本为 `Text` 财务报告和审定财务报表 `Heading`尺寸、语气和重量是道具; `className` 只携带布局 : ```tsx import { Text } from "@ctrl-ui/react/ui/typography"; Saved ``` 将类名称与软件包合并 `cn`。一个赤裸的 `twMerge` 读取 `text-micro` 作为文本颜色,默默地将其放在旁边 `text-muted-foreground`。在顶部添加您自己的类型 `withControlUiMerge` 而不是开始第二次合并: ```ts import { withControlUiMerge } from "@ctrl-ui/react/lib/cn"; import { extendTailwindMerge } from "tailwind-merge"; const twMerge = extendTailwindMerge({ extend: { classGroups: { "font-size": [{ text: ["hero"] }] } } }, withControlUiMerge); ``` 控件大小: 选择控件的 `size`,或设置其 `--cui-*-font-size` 在您的主题中按键, 而不是将标签包装为 `text-*` 间距. ## 林特规则 这些规则让网站保持诚实。 它们来自一项政策(`lint/class-policy.mjs`)和飞船为Biome,ESLint,和克克林特,除了样式表规则,它只是Biome: - `no-component-style-classes` 错误当 `className` 的组件 `@ctrl-ui/react` (或 a 个) `components/control-ui` 目录)设定组件拥有的:颜色,类型,编目,边框,半径,阴影,过滤器,状态样式等 `hover:` 财务报告和审定财务报表 `data-[…]:`涂料的任意属性(`[background:…]`),或 `!important`每一个 `text-*` 分类计数,但对齐和包接除外(`text-center`, (中文(简体) ), `text-pretty`, (中文(简体) ), `text-ellipsis`(......) (中文(简体) ). 该规则还读取字符串常数 `className` 在同一文件中的引用,以及 `className` 转移给该部分的 `render` 道具 (英语). 在任何其他要素上,它错误地将类误入一个组件的部分,例如: `[&_[data-slot=trigger]]:` 或者说 `*:data-[slot=icon]:`组合类`flex`, (中文(简体) ), `gap-*`,宽度,高度,边距,位置)允许保留. 通过组件的道具或它的 `--cui-*` 转而取道把手. - `no-component-style-props` 将同一边界适用于 `style`数字 : `--cui-*` knobs和布局密钥通过,而涂装密钥出错(`color`, (中文(简体) ), `background`, (中文(简体) ), `font*`, (中文(简体) ), `padding*`, (中文(简体) ), `border*`, (中文(简体) ), `boxShadow`, (中文(简体) ), `opacity`, (中文(简体) ), `filter`(......) (中文(简体) ). 它还检查同一文件的常数对象和传递给 `render`当涂料是数据时,如用户选取的填充,将其放入自己的平面元素上,让组件继承. - `no-component-part-css` 样式表绘制组件部分时出错:其主体为规则 `[data-slot]`, (中文(简体) ), `[data-control-family]`,或另一个 `[data-control…]` 属性,包括嵌入式 `&` 规则和规则 `@apply`设定该部分 `--cui-*` 手势和布局是允许的。 预设跳过已安装控制 UI 源 `components/control-ui`。 。 。 . - 无漆组件没有外观,所以两个组件规则都把它们当作平面元素: `RevealScope` 可以是所绘行或牌本身,通过 `className`, (中文(简体) ), `style`时,或 `render` 键。 部分选择器仍然错误,以及 `Reveal` 保持完整的规则,因为它的食谱 拥有不透明. - `no-raw-type-classes` 任意文本大小出错 `className`: 类型 rungs, Tailwind's `text-xs`.`text-9xl`和任意性 `text-[13px]`。它超出了控制UI的范围,所以在您迁移时按文件夹通过它. Biome 规则需要 Biome 2. 5.0 或 后期: 预设范围 : 带有插件的样式表规则 `includes`。 。 。 . Biome, 扩展已运出预设, 因此添加的规则随软件包更新而到达 : ```json { "extends": ["@ctrl-ui/react/biome"], "overrides": [{ "includes": ["src/features/**"], "plugins": ["./node_modules/@ctrl-ui/react/lint/no-raw-type-classes.grit"] }] } ``` ESLint 平面配置 : ```js import controlUi from "@ctrl-ui/react/eslint-plugin"; export default [ { plugins: { "control-ui": controlUi }, rules: { "control-ui/no-component-style-classes": "error", "control-ui/no-component-style-props": "error" }, }, ]; ``` 校对:Soup ```json { "jsPlugins": ["@ctrl-ui/react/eslint-plugin"], "rules": { "control-ui/no-component-style-classes": "error", "control-ui/no-component-style-props": "error" } } ``` 当您的应用程序通过自己的包装包或文件夹导入组件时, 声明路径, 规则也遵循这些导入 : ```js const options = { importSources: ["@acme/ui/components/"] }; rules: { "control-ui/no-component-style-classes": ["error", options], "control-ui/no-component-style-props": ["error", options] } ``` Biome 的 Grit 插件没有选择, 所以包船 `control-ui-grit` 写规则与路径。 在安装时运行它, 这样一个软件包更新它们, gitignore `.control-ui`,并列出生成的 `no-component-style-classes.grit`, (中文(简体) ), `no-component-style-props.grit`,以及 `no-component-part-css.grit` 从 `./.control-ui/` 下级 `plugins` 替换预设 : ```json { "scripts": { "postinstall": "control-ui-grit --import-source=@acme/ui/components/ --out=.control-ui" } } ``` ## 自定义 您的应用程序拥有它的主题 。 覆盖您的 CSS 中库的中性默认值 : ```css :root { --primary: oklch(0.45 0.18 260); --radius: 4px; } .dark { --primary: oklch(0.78 0.1 260); } ``` 组件节点自定义一个实例 : ```tsx ``` 对于范围化的主题,行为选择,或花饰,通过自己的 `ControlUiSkin` 给可选提供者。 定义客户端模块中包含渲染函数的配置 : ```tsx "use client"; import type { ReactNode } from "react"; import type { ControlUiSkin } from "@ctrl-ui/react/skin"; import { SkinProvider } from "@ctrl-ui/react/skin-provider"; const skin: ControlUiSkin = { id: "acme", indicators: { sidebar: "hover" } }; export function AppTheme({ children }: { children: ReactNode }) { return
{children}
; } ``` 相应的CSS范围为 `[data-skin="acme"]`. Portalled surfaces 承载了提供者的ID,因此它们得到相同的主题. 由于没有提供者,门户继承了根主题. 每个供应商拥有其子树;没有全球的皮肤单子. ## 可选同伴 仅在导入需要的组件时安装对等端 . | 构成部分 | 端点 | | --- | --- | | `ui/calendar` | `react-day-picker` | | `ui/chart` | `@tanstack/charts` | | `ui/code`, (中文(简体) ), `ui/code-diff` | `@tanstack/react-virtual`, (中文(简体) ), `diff`, (中文(简体) ), `shiki` | | `ui/command` | `cmdk` | | `ui/flow` | `@xyflow/react` | | `ui/markdown` | `streamdown` | | `ui/phone-input` | `react-phone-number-input`, (中文(简体) ), `libphonenumber-js`, (中文(简体) ), `zod` | | `ui/resizable` | `react-resizable-panels` | | `chat-composer` | `prosemirror-*` | | `email/email`, (中文(简体) ), `email/templates` | `react-email` | `ui/flow` 还需要在食谱下加载的回放流结构样式表: ```css @import "@xyflow/react/dist/base.css" layer(base); ``` ## 常见问题 ### @ctrl-ui/react 是什么？ 100\+ 用于 Tailwind CSS 和 Shadcn/ui 的回放组件:取取取器,树,编辑器,画布,应用模板,以及 AI 聊天表面,具有中性默认和消费者拥有的主题\. ### 如何安装 @ctrl-ui/react？ 在项目目录运行 npm install @ctrl-ui/react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：clsx（^2\.1\.1）、react（^19\.2\.8）、react-dom（^19\.2\.8）、lucide-react（^1\.47\.0）、@base-ui/react（^1\.9\.0）、tailwind-merge（^3\.7\.0）、class-variance-authority（^0\.7\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 control-ui-grit，可以用 npx control-ui-grit 直接运行。 ### @ctrl-ui/react 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @ctrl-ui/react 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @ctrl-ui/react 可以商用吗？ @ctrl-ui/react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @ctrl-ui/react 的下载量有多少？ 根据 npm 官方下载统计，@ctrl-ui/react 在 2026/10/11 – 2026/11/09 这 30 天内被下载 3,346 次，日均约 112 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @ctrl-ui/react 还在维护吗？ 最新版本 0\.10\.0 发布于 2026/11/11（今天）；至今共发布 41 个版本，其中过去 12 个月发布了 41 个；首次发布于 2026/09/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。