# @cratis/components 中文文档 规范地址：https://npmcn.com/package/%40cratis/components/ 版本：4\.40\.0 npm 元数据更新时间：2026-11-04T10:40:41.883Z 中文译文更新时间：2026-11-10T23:19:46.237Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40cratis/components 原文对照：https://npmcn.com/package/%40cratis/components/?lang=original 项目主页：https://www.cratis.io/components/ 源码仓库：https://github.com/Cratis/Components ## 关键信息（来自 npm 元数据） - 包体积（解压后）：7.1 MB，2453 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：7 个 - peer 依赖：react ^19\.0\.0，pixi\.js ^8\.20\.0，tsyringe 4\.10\.0，react-dom ^19\.0\.0，@cratis/arc \>=20\.3\.1 \<23，reflect-metadata 0\.2\.2，@cratis/arc\.react \>=20\.3\.1 \<23，@cratis/fundamentals ^7\.10\.3 - 首次发布：2026-01-06T12:55:29.092Z - 最新版本发布：2026-11-04T10:40:41.436Z - 近 30 天下载量：26976（2026-10-11 至 2026-11-09，npm 官方下载统计） - 已发布版本数：162（近 12 个月 162 个） ## 中文简介 CQRS 和事件源代码应用程序的响应组件 – 命令对话框, 键入窗体, 以及 Cratis Arc 的基于查询的数据表格 ## 安装 ```sh npm install @cratis/components ``` 也可以使用：`pnpm add @cratis/components`、`yarn add @cratis/components`、`bun add @cratis/components` ## README # @ cratis/ 组件 反应 UI 组件 **克拉蒂斯平台**,作为 `@cratis/components`数字 : 命令对话框、打入的窗体、基于查询的表格,以及周围的应用程序表面 [克拉蒂斯弧](https://github.com/Cratis/Arc)。不需要纪事. 该软件包为Arc命令、查询、对话框提供反应组件, 表格和应用程序表面。 组件拥有其公共标记, TypeScript 合同、稳定的零件和设计标志。 选择反应 ARia 供应 内部交互原始;消费者不导入或样式React Aria. - [Canonical 组件文档](https://www.cratis.io/components/) - [渲染器适配器和共存](https://github.com/Cratis/Components/tree/main/Documentation/renderers) - [移徙指南](https://npmcn.com/package/%40cratis/components/MIGRATION.md) - [私营安保报告](mailto:oss@cratis.io?subject=Security%3A) ## 选择您的第一个表面 - **生成的命令或查询 :** 跟着 [开始](https://www.cratis.io/components/getting-started/) 面向同行,CSS,以及两个供应商. 礛 [构建库屏幕](https://www.cratis.io/components/tutorial/) 对抗链接的Arc后端并生成代理. 部件不提供这些合同. - **已装入行或本地 UI 状态 :** 选择 `DataTableCore` 或控制控制从 页:1 [决定指南](https://www.cratis.io/components/choosing-a-component/)。该表面不需要 调用Arc后端;下面所需的Arc软件包对等器不会成为可选的. - **现有的组件 3 应用程序 :** 使用该 [移徙指南](https://npmcn.com/package/%40cratis/components/MIGRATION.md) 复制前 构成部分4 进口. 教程从一个表格延续到一个添加作者对话框和一个被选中的作者的书籍. 命令成功关闭了对话框; 当查询提供更新数据时会出现一行 . 对于失败,请从 [症状指南](https://www.cratis.io/components/troubleshooting/)。 。 。 . ## 安装 ```bash npm install @cratis/components@^4 ``` 当前软件包显示声明这些对等依赖性 : - `@cratis/arc` 财务报告和审定财务报表 `@cratis/arc.react` `>=20.3.1 <23` - `@cratis/fundamentals` `^7.10.3` - 选项 `pixi.js` `^8.20.0` - `react` 财务报告和审定财务报表 `react-dom` `^19.0.0` - `reflect-metadata` `0.2.2` - 选项 `tsyringe` `4.10.0` (Arc React 安装它作为自己的依赖) 严格的安装器可以明确声明它们; 保留您生成的代理版本上的两个Arc包 。 此检查退出将它的Arc开发依赖性定在22.156.2; 使用匹配您生成的代理的版本 : ```bash ARC_VERSION=22.156.2 npm install @cratis/components@^4 \ "@cratis/arc@$ARC_VERSION" "@cratis/arc.react@$ARC_VERSION" \ @cratis/fundamentals@^7.19.2 react@^19 react-dom@^19 \ reflect-metadata@0.2.2 ``` 当前运算表不宣布PrimeReact,PrimeIcons,或PrimeUI软件包为依赖或对等. 保留直接依赖关系的应用程序保留自己的软件包、供应商、样式和许可证界限. 生成的相容性计划 v2 合同发布于 `@cratis/components/compat-manifest.json`它记录所支持的组件和工具 窗口, 授权的七包范围, 共享发布版本, 渲染器 ABI/ profile 范围, 和准确的下/当前适配器证据. `release.md` 在寄存器根处描述 标签驱动的出版政策. Render-adapter 作者可以导入公开的2020-12元数据计划草案 `@cratis/components/schemas/ui-adapter.schema.json`它验证了静态 `package.json#cratis` 对象; 运行时的行为仍然需要 `@cratis/components.conformance`见 [渲染器适应器文档](https://github.com/Cratis/Components/blob/16dd95b7c894f3275b03714ffdc676d2d3505fd8/Documentation/renderers/index.md#adapter-package-metadata-schema) 为边界和限制. **Yarn PnP 笔记 :** `@cratis/arc.react@22.6.2` 进口 `rxjs` 没有宣布。 安装该版本的严格 PnP 消费者 `rxjs@7.8.2` 添加一个 `packageExtensions` 条目 `@cratis/arc.react@22.6.2`; Arc React 22.16.0 不需要它. 峡谷 [正在启动指南](https://www.cratis.io/components/getting-started/) 包含准确的YAML. `pixi.js@^8.20.0` 是额外的 **选项** 端点,仅由 `Canvas` 财务报告和审定财务报表 `PivotViewer` (空间能力简介——见 [从明确的子路径导入](https://npmcn.com/package/%40cratis/components/#readme-import-from-explicit-subpaths) 页:1 所有其他的子路径除了上面的同龄人不需要任何东西: ```bash npm install pixi.js@^8.20.0 ``` 在整个应用程序和组件中保持一个完全相容的 Pixi 分辨率; 2 个安装的复制件产生标称的 TypeScript 不兼容 `PIXI.Container` 和指向事件类型,即使两者都满足 `^8.20.0`。以下的能力子路径表确定当前依赖 Pixi 的表面. ## 样式 ```css /* index.css */ @import '@cratis/components/tokens'; @import '@cratis/components/styles'; @import '@cratis/components/theme'; /* optional baseline appearance */ ``` 在应用程序入口处导入此文件一次, 例如 `import './index.css';`。从 CSS 而不是 TypeScript 导入样式表: 子路径船无类型声明,例如 TypeScript 6 默认检查副作用导入, `import '@cratis/components/tokens'` 在一个 `.tsx` tS2882 的文件失败。 虚拟项目类型检查 `import './index.css'` 通过其 `vite/client` 类型。 仍然从 TypeScript 导入样式表子路径的工程在环境中声明 `.d.ts` 文件 : ```ts declare module '@cratis/components/tokens'; declare module '@cratis/components/styles'; declare module '@cratis/components/styles/base'; declare module '@cratis/components/theme'; ``` `tokens` 提供保守的光默认值. `styles` 在低优先级级Cratis级层中包含结构规则和内部公用设施,没有 Tailwind Preflight/reflight 或象征性重复. `theme` 增加了自发/显暗模式,强迫颜色,和被子树. 也绘制了Arc的地图 `--color-error` 财务报告和审定财务报表 `--color-error-bg` 用于每一个光和暗的图案,所以一个自定义这些Arc符号的应用程序在导入后设置 `theme`。 。 。 . 自定义产品设计省略 `theme`后,进口产品 CSS `tokens` 财务报告和审定财务报表 `styles`,并直接将其条形值映射到 `--cratis-*`。 。 。 . `styles` 是每个组件的 CSS 在一个文件中。 为了只支付应用程序所挂起的表面, 导入共享的基数加上每个子路径的一个入站点 : ```css @import '@cratis/components/tokens'; @import '@cratis/components/styles/base'; @import '@cratis/components/Dialogs/styles'; @import '@cratis/components/DataTables/styles'; ``` 每个 JavaScript 子路径发布匹配 `/styles`自成一体的子路径. `styles/base` 装有内部公用事业和级联级订单,而且需要一次;总量中已经装有. ## 提供者 导入 `reflect-metadata` 一次在入口处,样式之前,然后在Arc's内部挂载组件提供者 `` 供养. `` 提供生成的代理所用的命令和查询运行时间; `CratisComponentsProvider` 不替换它: ```tsx import 'reflect-metadata'; import { Arc } from '@cratis/arc.react'; import { CratisComponentsProvider } from '@cratis/components'; export const App = () => ( ); ``` 提供商拥有本地语,组件专用标签,可选的渲染器选择和土司 区域。 默认渲染器不需要额外的包. 经认证的渲染器包 稳定,九相间 `stable-presentation/v1` 原始配置文件; 它们从未替换完整组件 目录. 它们共享组件寄存器的发布版本,并与提供者的 `library` 道具 : - `@cratis/components.mui` MUI 9.x / 情感 11.x 稳定显示槽; - `@cratis/components.primereact` ——PrimeReact 11.x 稳定的演示文稿插槽,并有 申请拥有的外部供应商和许可证钥匙; - `@cratis/components.primereact10` ——PrimeReact 10.9+ 稳定显示槽,并有其 独立的麻省理工学院时代提供商、全球主题和上游-主要边界. 适应器特定主题、提供者、安保部门改革设置、同行和许可证界限仍由 适配软件包。 内置渲染器的造型是CSS拥有的. 犬形变形器指南 限制原始适应、供应商直接共存、定制组成、无依据索赔,以及 许可证/钥匙所有权. ```tsx ``` ## 命令表单 ```tsx import { CommandDialog } from '@cratis/components/CommandDialog'; import { InputTextField } from '@cratis/components/CommandForm'; import { RegisterAuthor } from './RegisterAuthor'; export const RegisterAuthorDialog = () => ( command={RegisterAuthor} title='Register author' okLabel='Register' > value={(command) => command.name} title='Name' /> ); ``` 字段通过Arc命令-形式上下文直接绑定生成的命令属性和表面服务器验证. 用户不输入的必需命令值, 如生成的 id, 属于 `initialValues`· ; `onBeforeExecute` 在验证后运行,无法启用确认按钮. ## 查询支持的表格 ```tsx import { Column, DataTableForObservableQuery } from '@cratis/components/DataTables'; import { ObserveAuthors } from './ObserveAuthors'; ; ``` Arc拥有服务器呼号. 客户端过滤器只应用到已装入的页面;完整结果过滤器属于查询参数,在呼叫前运行在服务器上. ## 通知 ```tsx import { Toaster, toast } from '@cratis/components/Notifications'; ; toast.success({ title: 'Saved', description: 'Your changes were saved.', }); ``` 排队、承诺生命周期、计时器、调度替代、土司框架和区域是组件自主执行的表面. ## 自定义样式 有文件可定制的组件使用稳定 `data-cratis-part` 名称。 具有每一次定制的部件暴露出一个类型 `pt` 对象中含有其所记录部分的普通 HTML 属性. ```tsx import { Dialog } from '@cratis/components/Dialogs'; Content ; ``` ```css :root { --cratis-primary-color: var(--product-accent); --cratis-action-background: var(--product-action); --cratis-action-background-hover: var(--product-action-hover); --cratis-action-background-active: var(--product-action-active); --cratis-action-text: var(--product-on-action); --cratis-surface-card: var(--product-surface); --cratis-surface-overlay: var(--product-surface-raised); --cratis-surface-border: var(--product-border); --cratis-control-background: var(--product-control); --cratis-control-border: var(--product-control-border); --cratis-text-color: var(--product-text); --cratis-focus-ring: var(--product-focus-ring); } .product-dialog[data-cratis-part='root'] { border-radius: 1rem; } ``` 切勿瞄准 React Aria 类或内部 DOM 结构 . ## 从明确的子路径导入 教条: **包根只设置; 每一个组件船从自己的子路径.** 导入 `CratisComponentsProvider`, (中文(简体) ), `useCratisComponentsConfig`, (中文(简体) ), `cratisDefaults`,以及 `mergeCratisComponentsConfig` 从根; 从子路径导入其能力配置中的每个组件: | 子路径 | 能力简介 | | --- | --- | | `@cratis/components/Canvas` | 空间( 可选) `pixi.js` 端点) | | `@cratis/components/Chat` | 高级反应 | | `@cratis/components/CommandDialog` | 基金会 | | `@cratis/components/CommandStepper` | 基金会 | | `@cratis/components/CommandForm` | 基金会 | | `@cratis/components/CommandForm/fields` | 基金会 | | `@cratis/components/Common` | 基金会 | | `@cratis/components/DataPage` | 基金会 | | `@cratis/components/DataTables` | 基金会 | | `@cratis/components/Dialogs` | 基金会 | | `@cratis/components/Display` | 基金会 | | `@cratis/components/Dropdown` | 基金会 | | `@cratis/components/Filter` | 基金会 | | `@cratis/components/Notifications` | 基金会 | | `@cratis/components/ObjectContentEditor` | 高级反应 | | `@cratis/components/ObjectNavigationalBar` | 高级反应 | | `@cratis/components/PivotViewer` | 空间( 可选) `pixi.js` 端点) | | `@cratis/components/SchemaEditor` | 高级反应 | | `@cratis/components/TimeMachine` | 高级反应 | | `@cratis/components/Toolbar` | 高级反应 | | `@cratis/components/types` | 基金会 | 基础、高级反应和空间描述依赖和使用 边界,而不是稳定性、成熟度、可获取性、支持或质量等级. `Spatial` 识别需要可选 Pixi 端点的子路径. 组件 4 从根中去除组件-家族命名空间。 根为: 仅设置, 所以导入提供者不会穿行可选或不相关的 组件图. [移民.md](https://npmcn.com/package/%40cratis/components/MIGRATION.md) 包含当前 名称空间到子路径映射和迁移命令,用于现有根导入. ## 构成部分3 移徙 当前软件包的显示不宣布 PrimeReact 为必需的运行时间 或对等。 跟着 [第3至4部分 移徙指南](https://npmcn.com/package/%40cratis/components/MIGRATION.md) 用于消除依赖性、提供者变化、产品代号映射、稳定部分 名称、 DatePicker 更改、 表格行为、 通知、 直接导入 替换,边框组件 4 `@cratis/components.migrator` 命令,以及 `@cratis/eslint-plugin-components` 警卫 可选的移入是一种开发性CLI,仅用于 升级应用程序源; 其语法意识转换验证捆绑相容性 扫描前显示并安装组件支持窗口. `@cratis/components.conformance` 是对渲染器适配器作者的单独开发测试工具,而不是应用程序 运行时间依赖. 旧的 `@cratis/components/styled`, (中文(简体) ), `styledMode`, (中文(简体) ), `CratisPreset`,以及 `primeReactStyles` 制造器出口被移除。 升级前将样式移动到符号和稳定部件上. ## 许可证 软件包元数据声明麻省理工学院 `@cratis/components`A. 依赖和依赖 捆绑的资产保留自己的条件。 审查包装 `LICENSE`, (中文(简体) ), `THIRD_PARTY_NOTICES.md`,并包含精确软件包的字体许可文件 您使用的版本 . ## 常见问题 ### @cratis/components 是什么？ CQRS 和事件源代码应用程序的响应组件 – 命令对话框, 键入窗体, 以及 Cratis Arc 的基于查询的数据表格 ### 如何安装 @cratis/components？ 在项目目录运行 npm install @cratis/components，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）、react-dom（^19\.0\.0）、@cratis/arc（\>=20\.3\.1 \<23）、reflect-metadata（0\.2\.2）、@cratis/arc\.react（\>=20\.3\.1 \<23）、@cratis/fundamentals（^7\.10\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @cratis/components 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @cratis/components 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @cratis/components 可以商用吗？ @cratis/components 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @cratis/components 的下载量有多少？ 根据 npm 官方下载统计，@cratis/components 在 2026/10/11 – 2026/11/09 这 30 天内被下载 26,976 次，日均约 899 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @cratis/components 还在维护吗？ 最新版本 4\.40\.0 发布于 2026/11/04（6 天前）；至今共发布 162 个版本，其中过去 12 个月发布了 162 个；首次发布于 2026/01/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。