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

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

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

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

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

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

- 包体积（解压后）：4.6 MB，1425 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：quill ^2\.0\.3，react ^19\.0\.0，chart\.js ^4\.5\.1，react-dom ^19\.0\.0，primeicons ^8\.0\.0，primereact ^11\.0\.0，@primereact/core ^11\.0\.0，@primereact/headless ^11\.0\.0
- 首次发布：2026-08-16T10:56:06.614Z
- 最新版本发布：2026-11-10T16:52:04.007Z
- 近 30 天下载量：18366（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：137（近 12 个月 137 个）

## 中文简介

PrimeReact 组件包:将 Scene 的抽象组件名称映射到真实的 PrimeReact 组件上,将 PrimeReact 的自由主题映射到 Scene 主题上.

## 安装

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

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

## README

# @cratis/scene.primereact (英语)

Scene 的 PrimeReact 组件包 。 它将 Scene 的抽象组件名称映射到真实 PrimeReact 11 组件和 PrimeTek 的 `@primeuix/themes` 预设到场景 `Theme` 对象.

面向用户的文档 [`Documentation/primereact-package/`](https://npmcn.com/Documentation/primereact-package/index.md)。 。 。 . 该文件是撰稿人的说明:资料来源所遵循的惯例及其背后的理由.

## 版式

```text
primereact/
├── primeReactPackage.ts        the ScenePackage manifest + the ScenePackageBundle
├── primeReactComponents.ts     the ComponentRegistry - every abstract name to its adapter
├── properties.ts               typed readers for element.properties
├── menuItems.ts, treeNodes.ts  shared readers for the two nested models the menus and trees reuse
├── MenuItem.ts, TreeNode.ts    those two models - Scene's own since v11 removed PrimeReact's
├── primeReactTheme.css         the Scene token <-> PrimeReact design-token bridge
├── storyElements.ts            fixture builders the galleries share
├── button/ data/ form/ media/ menu/ messages/ misc/ overlay/ panel/ screen/
│                               one adapter per file, grouped by PrimeReact family
├── theme/                      the theme catalog and the preset resolution behind it
└── for_*/                      BDD specs beside the code they specify
```

## 公约

**适应器被命名 `Prime<Component>`。 。 。 .** 适配器用于 `dropdown` 实值 `PrimeDropdown`输入 `form/PrimeDropdown.tsx`。前缀存在,因为文件也导入 PrimeReact 自己的 `Dropdown`, (中文(简体) ), 和两件事叫 `Dropdown` 在一个文件中是混乱是如何开始的。 它跟随 `CoreButton` 编号 : `CoreText` 实例 `@cratis/scene.react`。 。 。 .

**摘要名称为: `lowerCamelCase`** —— 说 `inputText`, (中文(简体) ), `dataTable`, (中文(简体) ), `selectButton`。抽象名称 跟着什么部件 _实值_,而不是PrimeReact恰好称之为这个主要版本: `toggleSwitch` 映射到 v10's `InputSwitch`,v11将该组件更名为 `ToggleSwitch` - 那个 抽象的名字一直是正确的,没有移动.

**三个名字被刻意分享 `core`** —— 说 `text`, (中文(简体) ), `button` 财务报告和审定财务报表 `card`覆盖 优先工作按设计进行,而不是碰撞。 7个`table`, (中文(简体) ), `column`, (中文(简体) ), `title`, (中文(简体) ), `field`, (中文(简体) ), `section`, (中文(简体) ), `summary`, (中文(简体) ), `action`)是指令类型Screenplay的屏幕词汇汇编到的.

**读取属性通过 `properties.ts`从来没有与一个铸币局.** `@typescript-eslint/no-explicit-any` 实值 错误在这里, 并且一个铸件会让错误的属性到达 PrimeReact 而不是掉回 。 这个 读者对错误的打字 财产完全像一个缺失的.

**场景元素无法表达的地方状态 .** A 类 `SceneElement`是因为 `properties` 已编写 设计- 时间配置; 模型中没有位置可以放出“ 用户输入的 ” 或“ 用户关闭的 ” 对话". 因此,每个交互式适配器都从它的属性中种子局部状态。 后果 具有故意性: 预览是可操作的而不是被冻结的, 交互会保持局部到渲染 组件.

## 符号词汇

13个语义符号,每个场景包都必须同意这些符号——一个词汇,每个 软件包是无法依赖的软件包. `primeReactTheme.css` 唯一的地点是场景名称和 PrimeReact的名字见面.

| 场景标志 | CSS 定制财产 | PrimeReact 11 设计符号 |
| --- | --- | --- |
| `primary.color` | `--scene-primary-color` | `--p-primary-color` |
| `primary.contrastColor` | `--scene-primary-contrast-color` | `--p-primary-contrast-color` |
| `surface.background` | `--scene-surface-background` | `--p-surface-50` 编号 : `--p-surface-950` |
| `surface.card` | `--scene-surface-card` | `--p-content-background` |
| `surface.border` | `--scene-surface-border` | `--p-content-border-color` |
| `surface.hover` | `--scene-surface-hover` | `--p-content-hover-background` |
| `surface.overlay` | `--scene-surface-overlay` | `--p-overlay-popover-background` |
| `text.color` | `--scene-text-color` | `--p-text-color` |
| `text.mutedColor` | `--scene-text-muted-color` | `--p-text-muted-color` |
| `highlight.background` | `--scene-highlight-background` | `--p-highlight-background` |
| `highlight.color` | `--scene-highlight-color` | `--p-highlight-color` |
| `content.borderRadius` | `--scene-content-border-radius` | `--p-content-border-radius` |
| `focus.ring` | `--scene-focus-ring` | `--p-focus-ring-shadow` |

本表的v10一栏是一个特设词汇,只能通过所编译的读取来学习 样式表; v11 是一个系统 `--p-*` 命名空间来自预设本身的符号路径, 所以 桥倒了.

桥道双向行驶,测距可负载. 打开 `:root`,每个场景标志 回到 活动预设 `--p-*` 数值。 内部 `[data-scene-theme-root]` ——要件 `SceneThemeProvider` 写入 上方的符号——景色符号被反馈到PrimeReact的变量上. 第二条规则永远不能动 改为 `:root`: 自定义属性,在 _不变_ 元素构成循环,无效 在计算值时 决意一无所获.

## 主题

这四个主题共有24个 `@primeuix/themes` 预设家庭 -- -- 奥拉、拉腊、诺拉和材料 以它自己的口音命名的原始彩色坡道.

符号值是 **生成**,没有转写。 V10主题是一个编译的样式表,其 `:root` 块可以使用文本编辑器读取; v11 预设是一个 JavaScript 对象,其值为符号 参考文献(`{emerald.500}`, (中文(简体) ), `light-dark({surface.0}, {surface.900})`这 `@primeuix/styled` 解决 : 运行时间。 发生在 `themePresets.ts` 是运行相同分辨率规则的输出,所以 目录保留了纯数据 拾取器可以读取而不启动主题引擎,同时仍然同意 预设会是什么。 如果任何符号仍然有未解决的引用, 则一个 spec 失败构建 .

每个主题都是PrimeTek的设计工作, 没有一个是我们的 - 场景选择口音,没有别的. 归属在 `primeReactThemes.ts` 每个主题的预设而不是写,所以 没有第二十五个主题,就无法增加。 全部归属表在 [主题参考文献](https://npmcn.com/Documentation/primereact-package/theme-reference.md)。 。 。 .

| 外地 | 数值 |
| --- | --- |
| `author` | `PrimeTek` |
| `authorUrl` | `https://primereact.org` |
| `license` | `PrimeUI Commercial` - 说吧 **不是麻省理工学院.** v10及其主题为麻省理工学院;v11为整个堆栈重新颁发了许可证. 见 [许可证发放](https://npmcn.com/package/%40cratis/scene.primereact/#readme-licensing)。 。 。 . |

`compatibleWith` 实值 `['PrimeReact', 'Tailwind', 'core']`。 。 。 . `core` 故意列出: `ThemeCompatibility` 没有任何隐含的例外,这些主题真正触及 `core`是因为 组件 - 通过语义符号层 `SceneThemeProvider` 适用于整个树丛 不通过 `--p-*` 属性,只有 PrimeReact 自己的组件读取.

### 混合图书馆主题

内部 `SceneThemeProvider`,桥将活动场景调色板映射到PrimeReact的语义和 组合符号。 主按钮、标签和进度标签使用主题的主控/相接 配对;卡片和相板使用其表面/文字配对。 已装运的 PrimeReact 主题保留其主 遇到正文 WCAG AA( 4. 5: 1) 时的前景; 否则 Scene 选择黑色或白色相对 预设的主填充,保留小标记文本和可读进度值。 蓝图主题 配对不变。 这也暴露了遗产 `--primary-color`, (中文(简体) ), `--primary-color-text`, (中文(简体) ), `--text-color` 和表面的别名,用于没有第二个调色板的老年消费者. 场景 `data-scene-color-scheme` 标记与 `.scene-dark`。 。 。 .

## 可选同伴

### 图.js 对等依赖

PrimeReact 11 移除了它以前的 Chart.js 包装器,所以 Scene `chart` 适配器挂载 Chart.js 画布 自己来. `chart.js@^4.5.1` 是一个可选的同伴依附关系 `@cratis/scene.primereact`中,可选 从不制作图表的主机可以省略. **生成图表的主机必须安装 `chart.js`**, (中文(简体) ), 包括当捆绑者静态解决进口时:没有它,建设就无法解决 `chart.js/auto`,或图表显示无法绘制.

适配器仅在其帆布上架后导入 Chart.js,这保证了SSR的安全. 它重建图表 当 类型、数据或选项在内容上发生变化,而不是当文档编辑在新对象中将数据等同.

`chart` 接受条形字符串类型(`bar`, (中文(简体) ), `line`, (中文(简体) ), `pie`, (中文(简体) ), `doughnut`, (中文(简体) ), `polarArea`, (中文(简体) ), `radar`, (中文(简体) ), `bubble`, (中文(简体) ), `scatter`,数字值 `0` 改为 `7` 旧的.NET enum, 和该enum的帕斯卡案件名称,没有 重写存储的元素 。 任何其他类型均作为条形图报告。 无数据的图表 点显示其 `emptyLabel`。 。 。 .

### 奎尔对等依赖

`quill` 并不是由软件包根导入的,所以一个使文本不丰富的主机也不需要 `quill` 也没有 要构建的样式表。 想要编辑丰富文本的主机安装 `quill@^2.0.3` 并明确选择:

```tsx
import 'quill/dist/quill.snow.css';
import { QuillLoaderProvider } from '@cratis/scene.primereact';
import { loadQuill } from '@cratis/scene.primereact/quill';

<QuillLoaderProvider loader={loadQuill}>{screen}</QuillLoaderProvider>
```

`@cratis/scene.primereact/quill` (来源于 `loadQuill/`)是命名的唯一模块 `quill`没有 编辑器只显示其内容并说。 作者 HTML 总是先通过许可列表; 查看 页:1 [构成部分参考](https://npmcn.com/Documentation/primereact-package/component-reference.md#rich-text-and-quill)。 。 。 .

## 浏览器规格

大部分规格在jsdom下运行 `yarn test`绘制像素、键盘行为和计算主题 样式需要一个真正的浏览器,所以 `yarn test:browser` 捆绑控件并驱动无头铬通过 `playwright-core`设置浏览器 `yarn playwright-core install chromium`。这些规格 不属于 `yarn test` 而失败,而不是跳过, 当铬缺失.

还值得知道: `column` 自PrimeReact 11以来 _我们_ 语义 而不是PrimeReact's. v11 已删除 `primereact/column`这样 `data/Column.tsx` 是克拉蒂斯拥有的 返回的宣告组件 `null`当 a `column` 元素被嵌入 `dataTable` 或者说 `table`, (中文(简体) ), 该表读取其 `field`编号 :`header`编号 :`sortable` 关闭 _模式_ (单位:千美元)`element.slots`而不是提供 节点 - 这就是为什么在v11端口幸存下来的原因.

## 主反应 11

此一揽子目标 **11.1.0 联合国**。从10.9.8开始,端口的全部记录 - 每个更名,每个抽象 名称,如果它失去了组件,以及所建造、转换或投放的每个部件,则在 [迁移页面](https://npmcn.com/Documentation/primereact-package/primereact-11-migration.md)。 。 。 .

撰稿人的简短版本:

-   **v11为组成.** `primereact/select` 出口 `Select.Root` 编号 : `Trigger` 编号 : `Value` 编号 : `Portal` 编号 : `Positioner` 编号 : `Popup` 编号 : `List` 编号 : `Option` 你把它们组装起来。 大多数重命名都不仅仅是一个导入.
-   **`Sidebar` 这是陷阱.** 10号 `Sidebar` 是v11的吗 `Drawer`, (中文(简体) ), _财务报告和审定财务报表_ v11推出全新的, 无关 `Sidebar` 用于应用-壳导航。 跟着名字而不是行为 编译干净而无声地将一个覆盖物交换为静态外壳.
-   **v11舰为零CSS.** 没有 `primereact/resources` 目录。 外观来自预设的手 改为 `PrimeReactProvider`· ; `usePrimeReactTheme` 返回场景主题的配置.
-   **16个抽象名称现在由克拉蒂斯拥有的组件支持** 因为v11取消了他们的, 2 表示为 `@primereact/headless` 钩子,还有3个从货单上掉下来 (单位:千美元)`cascadeSelect`, (中文(简体) ), `inputMask`, (中文(简体) ), `virtualScroller`) (中文(简体) ).
-   **`MenuItem` 财务报告和审定财务报表 `TreeNode` 现在是场景的类型了** - 说吧 `primereact/menuitem` 财务报告和审定财务报表 `primereact/treenode` 被删除。 从此软件包导入它们, 绝不从 `primereact/*`。 。 。 .

### 许可证发放

PrimeReact 10是麻省理工学院. PrimeReact 11不是, 也不是, 也不是 `primeicons` 8号, `@primereact/core`, (中文(简体) ), `@primereact/headless`, (中文(简体) ), `@primeuix/themes` 或者说 `@primeuix/styled` - 都听从商业总理的命令 许可证和 **需要许可证密钥,无论你如何风格**。检查运行在 `PrimeReactProvider` 挂载时没有条件 `unstyled`打开 `theme`,或打开 `NODE_ENV`;没有钥匙,您可以得到控制台 警告和"无效的PrimeUI许可证"在开发与生产上的标语.

见 [迁移页面](https://npmcn.com/Documentation/primereact-package/primereact-11-migration.md#licensing) 社区和商业层面以及再分配条款.

## 盖茨

从此文件夹中运行 :

```bash
yarn build          # tsc -b + rollup
yarn test           # vitest
yarn lint:ci        # eslint, zero warnings
yarn build-storybook
```

## 常见问题

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

PrimeReact 组件包:将 Scene 的抽象组件名称映射到真实的 PrimeReact 组件上,将 PrimeReact 的自由主题映射到 Scene 主题上\.

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

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

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

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

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

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

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

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

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

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

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

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