# @cratis/scene\.components 中文文档

规范地址：https://npmcn.com/package/%40cratis/scene.components/

版本：5\.2\.0
npm 元数据更新时间：2026-11-10T16:50:54.458Z
中文译文更新时间：2026-11-10T23:22:47.665Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cratis/scene.components
原文对照：https://npmcn.com/package/%40cratis/scene.components/?lang=original
项目主页：https://www.cratis.io/screenplay/
源码仓库：https://github.com/Cratis/Scene

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

- 包体积（解压后）：1.8 MB，622 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：react ^19\.0\.0，react-dom ^19\.0\.0，@cratis/arc ^22\.19\.1，@cratis/arc\.react ^22\.19\.1，@cratis/components ^4\.13\.0，@cratis/fundamentals ^7\.19\.2
- 首次发布：2026-08-16T10:56:17.860Z
- 最新版本发布：2026-11-10T16:50:53.949Z
- 近 30 天下载量：20784（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：137（近 12 个月 137 个）

## 中文简介

Cratis 组件适配器用于 Cratis Scene : 将来自 @cratis/ 组件的Arc- 绑定数据, 形式和对话框复合材料曝光为 Scene 组件 .

## 安装

```sh
npm install @cratis/scene.components
```

也可以使用：`pnpm add @cratis/scene.components`、`yarn add @cratis/scene.components`、`bun add @cratis/scene.components`

## README

# @ cratis/ scene. 组件

曝光的场景包 [`@cratis/components`](https://www.npmjs.com/package/@cratis/components) - 那个 Cratis React 组件库——作为可解析的场景组件.

`@cratis/components` 以反亚力亚元件为基础。 这个 `Cratis.Components` 软件包宣布依赖 只有尾风; PrimeReact 不是一个依赖性. 想要 PrimeReact 部件的 UI 配置文件列出可选内容 `PrimeReact` 软件包( r)`@cratis/scene.primereact`)本身.

面向用户的文档 [`Documentation/components-package/`](https://npmcn.com/Documentation/components-package/index.md)。 。 。 . 这个文件是撰稿人的说明:包裹是如何布置的,为什么是负载决定 做他们的方式.

## 约束一切

多数 `@cratis/components` 实值 **弧线**。 。 。 . `DataPage`, (中文(简体) ), `DataTableForQuery`, (中文(简体) ), `DataTableForObservableQuery`, (中文(简体) ), `AutoCommandForm`, (中文(简体) ), `CommandDialog` 财务报告和审定财务报表 `StepperCommandDialog` 全拿一个 _查询或命令类构建器_ 然后通过直播后端说话 `@cratis/arc.react`。 。 。 .

场景 `ExternalComponent` 携带一个 `properties` 包中纯值并命名 `slots`。没有办法 将 TypeScript 类放在一个中, 不应该有—— a `.play` 文档是文本,由 Stage 和 由 Studio 读回来, 和任何在那个回程旅行 无法携带一个课程.

因此适配器不能从属性字符串中调出查询类. 唯一诚实的缝合是 在屏幕上 _是一个名字_,一个名字需要一个地方 成为一个类.

### 具有约束力的登记处

`bindings/bindingRegistry.ts`数字 :

```typescript
registerQuery(name: string, queryClass: BoundConstructor): void
registerQueries(bindings: Record<string, BoundConstructor>): void
resolveQuery(name: string): BoundConstructor | undefined

registerCommand(name: string, commandClass: BoundConstructor): void
registerCommands(bindings: Record<string, BoundConstructor>): void
resolveCommand(name: string): BoundConstructor | undefined

registeredQueryNames(): string[]
registeredCommandNames(): string[]
clearBindings(): void
```

主机 — Stage 生成的应用程序, 或者工作室的预览, 当它被连接到真实的后端时 — 注册 在名字屏幕下真实生成的Arc代指它们。 适配器在渲染处查看 时间通过 `resolveElementBinding`,其内容如下: `properties.query` 或者说 `properties.command` 取决于 `BindingKind`。 。 。 .

设计注释 :

-   **查询和命令是单独的命名空间.** 它们是对半的 CQRS 和屏幕表示 让一个满足另一个会把一个模型错误变成一个运行时间错误.
-   **`BoundConstructor` 实值 `new (...args: never[]) => object`, (中文(简体) ),** 不是Arc类型。 场景故意不 依赖Arc。 注册类是否真的是一个查询, 由主机注册, 用 范围中真正的Arc类型——即该检查的所在.
-   **重新登记一个名字就可以代替它**,因此一个主机可以在热重装时重新注册.
-   **`clearBindings()` 已存在** 因为模块级别状态对一个一次注册错误的主机是正确的 用于 Studio 切换项目,或者用于不能继承上一个注册的 spec .

### 缺少的束缚是占位符,从不扔

`resolveQuery` 返回时 `undefined`,每个弧形适配器 `MissingBinding`数字 :

```text
Unresolved query binding 'AllInvoices' on Cratis.Components:dataTable
Missing query binding on Cratis.Components:dataTable
```

两个消息,因为它们是两个不同的错误——一个需要主机注册这个名字,另一个是 需要编辑屏幕。 演示文稿刻意匹配 `UnresolvedComponent` 内 `@cratis/scene.react`。 。 。 .

Studio的设计时间预览通常没有任何记录,而且必须显示可用的布局:一个 未绑定的表格需要一个破碎的盒子,而不是整个屏幕.

### 弧被懒惰地装入

`@cratis/arc`, (中文(简体) ), `@cratis/arc.react` 财务报告和审定财务报表 `@cratis/fundamentals` 是同位素的依赖关系 `@cratis/components` 关于 _东道主_ 供应。 此套件还宣布 Arc 和 Arc React 为可选的对等方和针 22.19.1 作为本土融合测试的发展依赖。 设计表面不是主机.

每个到达他们的适配器都通过动态 `import()` 内部 `React.lazy`,包裹在 `ArcRuntimeBoundary` (单位:千美元)`Suspense` + 图书馆本身 `ErrorBoundary`) (中文(简体) ). 只有图书馆的屏幕 Arc-free half从未将Arc客户端拉入,一个无约束组件甚至从未到达导入.

这可以把图书馆干净地拆分,拆分就是图书馆自己的:

| 无弧 (静态导入) | 弧形( 懒惰导入) |
| --- | --- |
| `Common`, (中文(简体) ), `Dropdown`, (中文(简体) ), `Filter`, (中文(简体) ), `Toolbar`, (中文(简体) ), `SchemaEditor`, (中文(简体) ), `TimeMachine`, (中文(简体) ), `ObjectContentEditor`, (中文(简体) ), `ObjectNavigationalBar` | `DataPage`, (中文(简体) ), `DataTables`, (中文(简体) ), `CommandForm`, (中文(简体) ), `CommandDialog`, (中文(简体) ), `Dialogs` |

故事书将Arc包外部化(`.storybook/main.ts`这样懒散的块就可以被排放 它的进口却一无所有。 没有故事装入这个块, 因为没有故事记录一个约束.

## 可操作命令表单

`commandForm` 通过提供本地提交按钮 `AutoCommandForm`选择 `footer` 反应节点接合. `submitLabel` 是可选字符串,默认为 `Submit`私人懒惰的运行时间让Arc不受约束 预览;其页脚孩子读取执行和授权状态的实际本土形式上下文. 有效性不会禁用提交 : 本地验证必须能够在未激活的表格上显示错误 . 既不直接执行命令,也不创建其他形式或命令上下文.

选择性明确 `inputs` 使用准确的本地代理描述名称和类型( q)`string`编号 :`guid`在一个 Arc CommandForm; 缺少,模棱两可, 被揭穿需要的或不支持的宣告会阻碍表单. 自动 模式只为字段,只支持 String/number/Boolean/Date 提供者,所以要求 Guide 不沉默 不见了。 内容槽没有与两个模式连接。 有效的“指导”草稿变为“指导” JSON在不改变身份的情况下将文本化了. 没有生成ID 。 申报的同伴要求 footer 和 Arc/Arc React 22.19.1 的自定义-error ging 的组件. 弧等同位素仍然是可选的,所以无约束的预览保持无弧.

## 可选的单结果视图( 只读)

`Cratis.Components:singleResult` 是一个可选的窄适配器 **单一模式**,而不是一个收藏. 例如,一个主机登记其生成 `ProjectName` 代理和供应这些外部组件 属性( 标识符来自主机承诺的输入, 绝不是猜测的工程) :

```typescript
registerQuery('ProjectName', ProjectName);
const properties = {
    query: 'ProjectName',
    queryArguments: Object.freeze({ projectId: committedProjectId }),
    enabled: true,
    resultField: 'name',
};
```

使用生成模型的实际自域名 . `resultField` 选择一个完全自己的数据字段 : 没有dotted-path traversal, getters, 继承成员,表达式, JSON 显示或结果约束 DSL. 字符串、 有限数字和布尔渲染为隐藏文本, 包括 `0`, (中文(简体) ), `false` 和空字符串. 缺/非平面字段是明显的失败,而不是缺失的模型. 无效/ 未定义的成功模式 实值 `Not found`;未成功、未经授权、无效和例外信封 `Unable to load result`。 。 。 . 闲置,加载和失败状态从不显示服务器例外消息或堆栈.

`enabled` 默认为虚假,并且必须是完全真实的;元素也必须启用。 主机拥有 输入控制、验证反馈和承诺/替换不可改变 `queryArguments` 对象。 连 无参数查询需要明确 `{}`. 缺失的束缚优先于所有其他检查 并且从不导入 Arc。已禁用或变形的适配器属性也不导入懒惰的运行时间. 原生弧 `perform` 在 HTTP 之前拥有所需的参数和生成验证器检查; Scene 添加 no 商业验证,并按身份转发参数对象.

私人懒惰的运行时间每个请求生成一个新鲜的本地代理, 配置全部四个Arc 上下文连接/标题值,并在替换或卸载时中止。 这也忽略了晚完成 当取消被忽略时, 掩盖先前在输入更改渲染上的结果, 并回复 标题召回身份和 `queryVersion` 变化。 主机必须替换回调或折叠版本 当证书在稳定的回调中隐形地改变。 没有共享缓存, 命令触发 刷新,投票,重试按钮, 或可观察的-query订阅.

已公布 Arc 22.16.1 本身使顶级疟原虫原始有效载荷正常化为无效 `QueryResult`。 。 。 . 因此,这个适配器保证了斯卡尔 **模型领域**,不是顶级原始查询;而是 而不是叉子断层取回这些有效载荷. `isReady: false` 这一枪失败了 视图而不是发明的重试协议。 推定代理人在被执行前被拒绝.

测试使用真实 `QueryFor` 未修改的子类 `perform`, 本地验证, 并仅使用 HTTP 边界被替换。 分出懒惰的双人测试 Arc-free gating,而非本地客户正确. 它们无法证明生成的服务器路由或后端持久性 。 选入 `queryInputForm` 下级 添加出窗体本地可编辑的输入/承诺语义; 第39幕仍然开放,供更广泛的约束和接受. 未更改默认配置文件、 生成器或方案 .

## 查询输入窗体( opt- in)

`Cratis.Components:queryInputForm` 使用 **现有** `SingleResultRuntime`。它的软件包 - 本地 `QueryInput` 声明名称 精确参数、标签、, 需要状态和可选的整弦模式。 它验证提交,冻结 新的承诺 在编辑时快照、取消/取消已过时的结果,并支持重复提交。 此时没有查询 编辑、 假命令上下文、 新执行器、 核心计划、 默认标识符或推断的路由.

已发布组件 `InputTextField` 包裹着 `asCommandFormField` 并使用命令上下文; 它不是出口的独立控制输入。 有意使用原版标签文本输入 换句话说 现有的命令-战地适配器和命令-slot行为不变.

`registerQueryIdentity(name, sourceIdentity, proxy)` 是明确选择的碰撞意识 API : 相同身份在热重装时替换; 不同来源的同名模糊. `queryInputForm` 订阅精确约束的更改。 遗产 `registerQuery` 保留其最后的写成 语义学和遗产权威 `resolveQuery` 此时此刻 否则,一个唯一独特的身份 登记还提供现有表格和 `singleResult`; 多个身份显示其未解决 不选择候选人的占位符。 现有适配器在主机渲染上重新解析. `registeredQueryNames` 包括两个命名空间的排序结合。 严格 `resolveExactQuery` 还是 阶段应每个来源提供一份身份登记,而不是同样提供 通过 `registerQueries`。 。 。 .

在目前懒散的运行时间边界上,形式声明必须精确地绘制成平面图 `String` 或者说 `Guid` 代理描述符. 不支持/缺失/重复描述符在HTTP之前失效;没有实施强制. 犬形生成的Guide代理形状测试不变. 本地弧验证所需的参数 和代理规则,但不自动验证 GUID 格式:如果需要,宣布一个明确的模式. 懒惰的运行时间使用Arc 已经要求的可选基本原理对等; 没有组件对等底 需要改变.

这个 [公共合同](https://npmcn.com/Documentation/components-package/query-input-form.md) 文档精确 有效载荷和相位消耗模式。 测试通过真实 `SceneElementView`,无修改的本地 弧形 `QueryFor.perform` 并仅替换 HTTP,包括验证、 stale 请求和卸载. 它们不是生成/浏览器接受;DOM套件发送程序提交而非模拟 a 浏览器隐含的 Enter 算法.

## 命名和跟踪

鲜有名字是 `lowerCamelCase` 和抽象—— `dataTable`没有 `DataTableForQuery` - 登记在 `componentRegistryKey('Cratis.Components', name)`。 。 。 .

`table` 财务报告和审定财务报表 `dialog` 故意再利用名称 `core` 选项 `PrimeReact` 软件包声明。 概况列表 `core`, (中文(简体) ), `PrimeReact`, (中文(简体) ), `Cratis.Components` 这样一来,就解决了这里 并记录了其他人 被阴影了 两种替代品都更适合 Cratis 应用程序: `DataTableForQuery` 执行查询 而不是被手排, 和克拉提人 `Dialog` 通过Arc的对话框上下文解决结果.

**`card` 故意不申报.** `@cratis/components` 没有船牌,最接近的是 `Page`是因为 `panel` 铬,其 `.panel` 分类 。 阴影 `card` 这样就能 更糟糕的是名称决心——只有在更换对每一个更合适时才有理由取消 屏幕中已写入名称.

`dataTable` 财务报告和审定财务报表 `table` 在两个名称下是同一个适配器,所以采用包不需要 重写相屏.

## 托肯桥

`theme/sceneTokenBridge.css`,导出为 `@cratis/scene.components/styles`,地图场景 `--scene-*` 符号 打开 `--cratis-*` 名称 `@cratis/components` 全文如下:

```css
--cratis-surface-card: var(--scene-surface-card, var(--p-content-background, var(--surface-card)));
/*                         ^ Scene theme           ^ PrimeReact v11         ^ v10 legacy */
```

它扩展了图书馆本身的倒转链而不是取而代之,所以一个部分主题留下了其余的为: primeReact主题有它。 这些规则的范围为: `[data-scene-theme-root], [data-scene-theme]` 从来没有 `:root`时 `--scene-*` 根本不存在,每张地图都会一无所获.

词汇是13个符号 `theme/themePresets.ts` 内 `@cratis/scene.primereact` 这样 两种软件包都用一种语言写主题: `primary.color`, (中文(简体) ), `primary.contrastColor`, (中文(简体) ), `surface.background`, (中文(简体) ), `surface.card`, (中文(简体) ), `surface.border`, (中文(简体) ), `surface.hover`, (中文(简体) ), `surface.overlay`, (中文(简体) ), `text.color`, (中文(简体) ), `text.mutedColor`, (中文(简体) ), `highlight.background`, (中文(简体) ), `highlight.color`, (中文(简体) ), `content.borderRadius`, (中文(简体) ), `focus.ring`。 。 。 .

## 故意不涵盖

-   **`PivotViewer`** ——拖入内 `pixi.js`,一个完整的 WebGL 渲染器, 在每个捆绑 列出这个包, 用于设计时没有显示的面相浏览器。 想要导入的应用程序 直接说.
-   **`card`** 见上文.
-   **`column`** ——一列是配置元素,而不是已渲染的组件:它宣布 `field`, (中文(简体) ), `header`, (中文(简体) ), `sortable` 财务报告和审定财务报表 `filter`,表读取的孩子。 因此,列来了 通过 `content` 位置,在此声明一个名称将添加一个注册项,用于不 屏幕自行解决。 注意 _所有权_ 联 合 国 `Column` 移动于 PrimeReact 11 - `primereact/column` 被删除 `@cratis/components` 现在,它自己的船(`@cratis/components/DataTables`,从 `DataPage`)——因此,如果 `column` 名字是被通缉的,这是有组件的软件包 后面是那个 不申报的决定没有改变;只有理由不同.
-   **事件处理器** - 场景还没有行动约束的接合。 当一个召回驱动一个组件自己的 适配器持有的可见状态( name`useEditableCopy`因此,面包屑, 计划编辑器和时光机 就像自己一样 适配器在外边会暴露什么 悄悄的无所事事.
-   **`calendarField` 日期界限** ——作为弦而来,必须在这里被解析;范围无声地 错位比无差. 该规则属于命令的验证器.

## 版式

```
bindings/    the registry, BindingKind, BoundConstructor, MissingBinding, ArcRuntimeBoundary
pages/       page, dataPage, formElement
data/        dataTable, table, observableDataTable, singleResult
forms/       commandForm, queryInputForm; forms/fields/ the twelve field types
dialogs/     dialog, confirmationDialog, busyIndicatorDialog, commandDialog, stepperCommandDialog
common/      icon, tooltip, dropdown, errorBoundary
editors/     objectContentEditor, objectNavigationalBar, schemaEditor, timeMachine, filterPanel
toolbar/     toolbar, toolbarButton, toolbarGroup, toolbarSeparator
theme/       sceneTokenBridge.css
properties.ts            narrow readers for the property bag
cratisComponents.ts      the component registry
cratisComponentsPackage.ts   the manifest and bundle
```

适配器为前缀 `Scene` (单位:千美元)`ScenePage`, (中文(简体) ), `SceneDataTable`),因为被包裹的部件带有相同的 名称 - `Page`, (中文(简体) ), `DataPage`, (中文(简体) ), `Dialog` - 而且都住在同一个档案里.

## 属性读取

`properties.ts` 是唯一一个财产包的价值被缩小的地方, 没有铸造。 每个助手都会回答 相同方式: 当它真的是被请求的类型时, `undefined` 否则 适配器会读到 属性,并在一个表达式中应用自己的默认值.

`stringProperty`, (中文(简体) ), `booleanProperty`, (中文(简体) ), `numberProperty`, (中文(简体) ), `arrayProperty`, (中文(简体) ), `stringArrayProperty`, (中文(简体) ), `objectArrayProperty`, (中文(简体) ), `objectProperty`, (中文(简体) ), `unionProperty`。 。 。 .

`unionProperty(properties, 'orientation', ['vertical', 'horizontal'] as const)` 变成作者的 串入一个组件的字符串-立体结合道具中,没有断言.

## 盖茨

```bash
npx tsc -b                 # from the repository root
yarn build
yarn test
yarn lint:ci
yarn build-storybook
```

过去有两个工作轮 住在这个文件夹中 对于上游问题 `@cratis/components` 3.0.0和3 (中文(简体) ) PrimeReact 11移除了原因. 两者都不见了 也不应该回来 没有新的证据:

-   `.storybook/main.ts` 不再使用武力 `cssMinify: 'esbuild'`\- 它在那里,因为 `@cratis/components@2.9.0` 已运出 `dist/esm/TimeMachine/Properties.css` 与 `//` 线条注释,哪一 并不是 CSS, Vite 默认的闪电计数器拒绝一个无效文件的整捆. 3. 0.0 从 JavaScript 模块图中完全取出 CSS: 没有每个组件样式表 更多,仅 `styles.css`, (中文(简体) ), `tokens.css` 财务报告和审定财务报表 `theme.css` 在包根上,所有三个都清晰 在闪电下.
-   `vite.config.mts` 不再内含 `@cratis/components` 财务报告和审定财务报表 `primereact` 为了维特 已经存在 由于两者均使用名录进口方式作为无害环境管理发布(`primereact/api`),是节点自己的解析器 拒绝. `primereact/api` 完全不存在于第11版; PrimeReact's `exports` 现在解析地图 `./*` 给水泥 `./*/index.mjs`和每个 `@cratis/components` 子路径指向一个真实文件, 所以 节点在本地装入它们,而维特可以像其他依赖一样将它们外部化.

## 常见问题

### @cratis/scene\.components 是什么？

Cratis 组件适配器用于 Cratis Scene : 将来自 @cratis/ 组件的Arc- 绑定数据, 形式和对话框复合材料曝光为 Scene 组件 \.

### 如何安装 @cratis/scene\.components？

在项目目录运行 npm install @cratis/scene\.components，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）、react-dom（^19\.0\.0）、@cratis/arc（^22\.19\.1）、@cratis/arc\.react（^22\.19\.1）、@cratis/components（^4\.13\.0）、@cratis/fundamentals（^7\.19\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cratis/scene\.components 支持 TypeScript 吗？

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

### @cratis/scene\.components 支持 ESM 还是 CommonJS？

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

### @cratis/scene\.components 可以商用吗？

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

### @cratis/scene\.components 的下载量有多少？

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

### @cratis/scene\.components 还在维护吗？

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