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

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

版本：4\.40\.0
npm 元数据更新时间：2026-11-04T10:40:50.213Z
中文译文更新时间：2026-11-10T23:34:10.180Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：90.8 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20\.0\.0
- 运行依赖：2 个
- 首次发布：2026-08-30T20:53:36.613Z
- 最新版本发布：2026-11-04T10:40:49.736Z
- 近 30 天下载量：3968（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：83（近 12 个月 83 个）

## 中文简介

用于更新 @cratis/ 组件的迁移工具从组件 3 到组件 4 .

## 安装

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

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

## README

# @cratis/ 组件. migrator

A 第3部分编码库更新为第4部分公共合同。 它会将根命名空间移动到明确的子路径导入,取代已贬值的按钮外观道具,并将遗留的事件-收发回调改为语义值回调. CLI在内部使用语法感知码器,但每个指令都因其所执行的迁移而取名,可以独立运行,并具有同位素. 部件4只将包式供应商设置放在根上;每个部件都是从其明显的子路径导入的(`@cratis/components/Canvas`(例如,第1行) 伴侣 `@cratis/eslint-plugin-components` 软件包 `no-root-barrel-import` 规定一旦消费者迁移就执行.

软件包在 npm 上发布,并以与 `@cratis/components` (4.0.0 继续). 运行它 `npx`, (中文(简体) ), `pnpm dlx`,或 `yarn dlx` 如下所示 应用程序运行时间依赖 。 此寄存器的撰稿人可以运行工作空间脚本 直接换成.

已发布的软件包是 **仅限CLI** 工具。 它的公开表面是记录 `cratis-components-*` 可执行名称(+) `./package.json` 用于工具元数据; `lib/`, (中文(简体) ), `scripts/`,单个变换是执行细节,被包输出图所屏蔽. 不要从应用程序代码导入它们, 或在其上构建自定义的迁移 API .

## `remove-root-namespace-imports`

一个以TypeScript编译器API上所建的以AST为主的同能编码器. 出版的CLI 带来自己的 `typescript` 运行时间依赖,所以它的解析器不依赖于消费者 应用程序的 TypeScript 版本。 它重写静态 `import` 声明和名称 `export … from` 只有再出口;它永远不会猜测,并报告它不会触及的每一个案件.

### 重写什么

| 在此之前 | 之后 |
| --- | --- |
| `import { Canvas } from '@cratis/components';` | `import * as Canvas from '@cratis/components/Canvas';` |
| `import type { Canvas } from '@cratis/components';` | `import type * as Canvas from '@cratis/components/Canvas';` |
| `import { Canvas as C } from '@cratis/components';` | `import * as C from '@cratis/components/Canvas';` |
| `export { Canvas } from '@cratis/components';` | `export * as Canvas from '@cratis/components/Canvas';` |
| `export type { Canvas } from '@cratis/components';` | `export type * as Canvas from '@cratis/components/Canvas';` |
| `export { Canvas as C } from '@cratis/components';` | `export * as C from '@cratis/components/Canvas';` |

一个名字 `export … from '@cratis/components'` 再出口遵循的规则与 输入,因为两个方向的转换同样明确:出口 名称识别一个特定的命名空间(或经批准的设置符号),因此代码可以 重写而无猜想. 仅a **通配符** 整个包裹再出口—— `export * from '@cratis/components'` 或者说 `export * as X from '@cratis/components'` 留下来 不支持, 出于同样原因, 全包命名空间导入仍然不支持 : 见 [它拒绝猜测什么](https://npmcn.com/package/%40cratis/components.migrator/#readme-what-it-refuses-to-guess)。 。 。 .

历史 `CommandStepper` 根命名空间是一个特殊的情况: 它别名了完整 `CommandDialog` 模块。 因此,代码模块将其映射到 `@cratis/components/CommandDialog`,保留第4部分保留成员的模块身份。 它不能恢复一个已删除的模块导出, 如意外 `CommandStepperContent` 表面。 只需要独立组件的新代码 `import { CommandStepper } from '@cratis/components/CommandStepper'` (或等同再出口).

一个导入或再导出的多命名空间成为每个命名空间的子路径声明 :

```ts
// Before
import { Canvas, Common } from '@cratis/components';

// After
import * as Canvas from '@cratis/components/Canvas';
import * as Common from '@cratis/components/Common';
```

混合进口或再出口既命名一个经批准的设置符号,又命名空间被分割—— 设置符号保留在根上,命名空间移动到它的子路径:

```ts
// Before
import { CratisComponentsProvider, Canvas } from '@cratis/components';

// After
import { CratisComponentsProvider } from '@cratis/components';
import * as Canvas from '@cratis/components/Canvas';
```

重新运行自输出的编码器是无操作的——它只匹配导入或 命名后再导出其模块指定符是准确的 `@cratis/components` (或 `--package` ),因此,已经迁移的子路径导入或再出口永远不会被重审.

完整的命名空间 ~ 子路径图, 已知已删除的组件 3 相容导出, 以及经批准的- root- symbol 允许列表 [`lib/namespaceMap.js`](https://npmcn.com/package/%40cratis/components.migrator/lib/namespaceMap.js),反射为 `ESLint/lib/rootNamespaceMap.js`。当一个命名空间子路径、去除边界或设置符号改变时,贡献者必须一起更新两个软件包。 套件共享寄存器发布版本;等分谱防止了他们的迁移合同漂移.

### 它拒绝猜测什么

每一个都完全没有受到影响,而是报告为诊断:

-   整个软件包的命名空间导入—— `import * as Components from '@cratis/components';`。 。 。 . 稍后的子路径 `Components.X` 无法从 导入.
-   默认导入.. `import Components from '@cratis/components';`。软件包没有 默认导出 .
-   仅附带效果的导入 `import '@cratis/components';`。没有义务推断 子路径从.
-   既非经批准的设置符号, 也非已知名称空间的符号的命名导入 (例如成员喜欢: `Button` 仅存在 _内部_ 一个命名空间, 不在 词根). 整个导入语句没有被触及,而不是部分迁移.
-   构成部分3.6 `Compatibility` 名称空间及其直接通过输出。 他们 4组件没有兼容性 子路径,所以变换使语句未受影响,并指示消费者 键入 Cratis 部件.
-   TypeScript 导入任务 - `import Components = require('@cratis/components');`。 。 。 . 这就是整个软件包命名空间,所以后来的成员访问像 `import * as`。 。 。 .
-   一个动态 `import('@cratis/components')` 或一个普通JS `require('@cratis/components')`, (中文(简体) ), 档案里的任何地方.
-   整个包的通配符再出口—— `export * from '@cratis/components';` - 或一个 整个软件包的命名空间再导出 - `export * as Components from '@cratis/components';`。两者都与整包命名空间导入完全一样模糊: 单靠再出口无法确定后期的每一个准入需求。 A 类 _名称_ 再出口(`export { Canvas } from '@cratis/components';`)不在这份清单中—— 见 [重写什么](https://npmcn.com/package/%40cratis/components.migrator/#readme-what-it-rewrites)。 。 。 .

现有的子路径进口和再出口`@cratis/components/Canvas`,.)从不被触动—— 狭义的子路径消费者 被保留在原样.

### 使用

被包装的 CLI 需要更新的节点. js 20 或 更新并带来自己的 TypeScript 解析器; 它确实 不依赖于消费者应用程序的TypeScript版本. 它扫描了JavaScript, JSX, TypeScript, 和 TSX 来源, 包括 `.mjs`, (中文(简体) ), `.cjs`, (中文(简体) ), `.mts`,以及 `.cts` 变相. 构成部分 3没有3.x 迁移包。 4 迁移至 `>=4 <5`; 从不使用 `latest`。 。 。 .

在任何扫描或写入之前, CLI 验证其捆绑的相容性表, 检查它自己的 的版本 引用目录,并验证软件包在支持的 3.x 迁移源或 4.x 中 迁移目标窗口。 缺少组件、不支持的版本、陈旧的软件包元数据以及一个 无效的显示失败已关闭 . `--help` 在未安装组件的情况下仍然可用.

```sh
TOOLING_RANGE='^4.0.0' # Shell-safe equivalent of >=4 <5.

# Preview what would change, without writing anything:
npx --package "@cratis/components.migrator@$TOOLING_RANGE" \
  cratis-components-remove-root-namespace-imports --check path/to/app/src

# Apply the rewrite:
npx --package "@cratis/components.migrator@$TOOLING_RANGE" \
  cratis-components-remove-root-namespace-imports path/to/app/src

# Contributors to this repository can run the workspace source directly:
node Migrator/scripts/remove-root-namespace-imports.js --check Source
```

Pnpm和Yarn 2+项目中相同的有界限的软件包工作:

```sh
pnpm dlx --package "@cratis/components.migrator@$TOOLING_RANGE" \
  cratis-components-remove-root-namespace-imports --check path/to/app/src
yarn dlx --package "@cratis/components.migrator@$TOOLING_RANGE" \
  cratis-components-remove-root-namespace-imports --check path/to/app/src
```

引用含有空格的任何路径。 可执行示例中故意不使用角括号占位符,因为 `<...>` 是 shell 输入重定向语法.

当发现不支持的大小写时( 与 `--check` 或者没有.. 他们总是需要一个人类),和,在 `--check` 只有模式,当支持的重写有 尚未应用。 运行 `--help` 用于完整选项列表.

在运行了代码模块后, 运行项目自己的构建/ lint/ test 闸门—— 只运行代码模块 执行机械导入/再出口重写;它不试图修正任何结果 未使用导入, 也不知道您是否使用命名空间成员( q)`Canvas.Foo`还是 存在于该子路径.

## `button-variant-tone`

`cratis-components-button-variant-tone` 决定 `Button` 进口的JSX装订品,包括别名和 `Common.Button` 名称空间访问,来自 `@cratis/components/Common`它运用了运行时间遗留的优先权(`link` → `text` → `outlined` → `solid`并替换已贬值的道具:

| 折旧道具 | 语义道具 |
| --- | --- |
| `text` | `variant='ghost'` |
| `link` | `variant='link'` |
| `outlined` | `variant='outline'` |
| `rounded` | `shape='pill'` |
| `severity='secondary'` 编号 : `'contrast'` | `tone='neutral'` |
| `severity='info'` 编号 : `'help'` | `tone='accent'` |
| `severity='success'` | `tone='positive'` |
| `severity='warn'` | `tone='caution'` |
| `severity='danger'` | `tone='critical'` |

一个字形 `severity='contrast'` 还收到 `variant='solid'` 只有在没有明显的新的变体或更强大的真正遗产变体适用的情况下。 一个字面的新 `variant`, (中文(简体) ), `tone`,或 `shape` 胜出和它多余的后遗症被删除.

```tsx
// Safe rewrite
<Button outlined rounded severity='warn' />
// becomes
<Button variant='outline' shape='pill' tone='caution' />
```

变身从不通过JSX来猜测传播,动态后遗症值,重复道具,或与后遗症道具相冲突的未知新道具表达. 它使不确定的道具组保持原状,报告,并增加一个语法安全 `TODO(cratis-codemod)` 注释。 随后的运行并不重复该注释.

```tsx
// Refused and reported
<Button text={appearance.text} severity={appearance.severity} />
```

## `change-handler`

`cratis-components-change-handler` 解决组件拥有的 JSX 标识符,从 `@cratis/components/Dropdown`, (中文(简体) ), `@cratis/components/CommandForm`,以及 `@cratis/components/CommandForm/fields`。它会将结构上证明的单个转发回调单独改写 `Dropdown` 和命令表格字段 `onValueChange` 道具 :

```tsx
// Before
<Dropdown onChange={(event) => setRole(event.value)} />
// After
<Dropdown onChange={(value) => setRole(value)} />
```

对于组件 4 命令格式字段, 编码器会离开 `onChange` 并报告一个可操作的诊断,而不是改变回调。 弧线 `asCommandFormField` 包装不显示 `onChange` 作为元件 4 中的字段道具,所以保留属性即使重写回调也会产生TS2322. 将其副作用移动到附件 `CommandForm`是因为 `onFieldChange(command, fieldName, oldValue, newValue, validationInfo?)` 调用。 遗产 `onValueChange` 已证实事件有效载荷的字段回调重写为语义值; 已语义 `onValueChange` 召回无所动. 这个 [第3至4部分 移徙指南](https://www.cratis.io/components/migration/3-to-4/) 包括这个案子.

多声明、多用途、错误的负载、与默认/撤销的分解、以及依赖本地活动的回调都遭到拒绝、报告和一次附加说明:

```tsx
// Refused and reported: the host still depends on the old event object
<Dropdown
    onChange={(event) => {
        audit(event.originalEvent);
        setRole(event.value);
    }}
/>
```

## 运行迁移序列

对所有3个指令使用有界组件4工具列. 建议的来源/目标顺序是:

1.  包含第3部分`>=3 <4`)安装,预览和应用了root-import变换. 它的子路径存在于两个大都.
2.  运行组件 3 出入口并检查仅导入的更改 .
3.  核心升级到构成部分4(`^4.0.0`) (中文(简体) ).
4.  预览并应用按钮外观,然后进行更改-处理器迁移;这些生成组件 4 源.

飞行前还接受组件4目标窗口,这样在升级后可以恢复根变. 它不接受其他核心专业。 在应用前预览每个步骤 :

```sh
TOOLING_RANGE='^4.0.0'

npx --package "@cratis/components.migrator@$TOOLING_RANGE" \
  cratis-components-remove-root-namespace-imports --check path/to/app/src
npx --package "@cratis/components.migrator@$TOOLING_RANGE" \
  cratis-components-remove-root-namespace-imports path/to/app/src

npx --package "@cratis/components.migrator@$TOOLING_RANGE" \
  cratis-components-button-variant-tone --check path/to/app/src
npx --package "@cratis/components.migrator@$TOOLING_RANGE" \
  cratis-components-button-variant-tone path/to/app/src

npx --package "@cratis/components.migrator@$TOOLING_RANGE" \
  cratis-components-change-handler --check path/to/app/src
npx --package "@cratis/components.migrator@$TOOLING_RANGE" \
  cratis-components-change-handler path/to/app/src
```

永不替换 `latest`; 继续在内部使用工具 `>=4 <5`. Tooling包与 Core 共享寄存器的放出版本,被捆绑范围外加被捆绑的显示飞行前执行相容的迁移窗口而无需精确的patch耦合. 两种新的 CLI 都需要 Node.js 20 或更新, 捆绑自己的 TypeScript 编译器依赖性, 扫描 `.js`, (中文(简体) ), `.jsx`, (中文(简体) ), `.mjs`, (中文(简体) ), `.cjs`, (中文(简体) ), `.ts`, (中文(简体) ), `.tsx`, (中文(简体) ), `.mts`,以及 `.cts` 递归支持 `--package <name>`,然后退出非零,用于等待检查模式编辑或任何被拒绝的个案。 审查所有诊断和 `TODO(cratis-codemod)`,然后运行 消耗项目的东西, 油漆,类型检查,测试,和生产建设.

贡献者源指令为:

```sh
node Migrator/scripts/button-variant-tone.js --check Source
node Migrator/scripts/change-handler.js --check Source
```

### 测试

```sh
cd Migrator && yarn test
```

每个受支持和无支持的根进口案的仓库固定装置均在 `Migrator/test/fixtures`, (中文(简体) ), 各作为 `input.ts`编号 :`expected.ts` 双对 (`input.ts` 财务报告和审定财务报表 `expected.ts` 与 不支持的情况,因为没有什么应该改变。 按钮和换接器转换使用 `input.tsx`编号 :`expected.tsx` 下对 `Migrator/test/button-fixtures` 财务报告和审定财务报表 `Migrator/test/change-handler-fixtures`。 。 。 .

## 常见问题

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

用于更新 @cratis/ 组件的迁移工具从组件 3 到组件 4 \.

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

在项目目录运行 npm install @cratis/components\.migrator，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 cratis-components-change-handler、cratis-components-button-variant-tone、cratis-components-remove-root-namespace-imports，可以用 npx cratis-components-change-handler 直接运行。

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

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cratis\_\_components\.migrator 是否存在。

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

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cratis/components\.migrator 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

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

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

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

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

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

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