# @aphrody/m3-codemods 中文文档

规范地址：https://npmcn.com/package/%40aphrody/m3-codemods/

版本：1\.4\.7
npm 元数据更新时间：2026-10-23T03:52:17.800Z
中文译文更新时间：2026-11-08T10:04:10.344Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aphrody/m3-codemods
原文对照：https://npmcn.com/package/%40aphrody/m3-codemods/?lang=original
项目主页：https://github.com/aphrody-labs/bun-distribution/tree/os/packages/m3-codemods#readme
源码仓库：https://github.com/aphrody-labs/bun-distribution

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

- 包体积（解压后）：185 kB，28 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-10-05T08:04:48.121Z
- 最新版本发布：2026-10-23T03:52:17.599Z
- 近 30 天下载量：1806（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

代码MUI React - > @aphody/m3-react (Bun, sans dépendance runtime) + règles ast-grep

## 安装

```sh
npm install @aphrody/m3-codemods
```

也可以使用：`pnpm add @aphrody/m3-codemods`、`yarn add @aphrody/m3-codemods`、`bun add @aphrody/m3-codemods`

## README

# @ aphrody/ m3- codemods (英语)

迁移 MUI React 的代码和 ast- grep 规则(`@mui/material`, (中文(简体) ), `@mui/icons-material`改为: `@aphrody/m3-react` 和材料符号.

```sh
bun add -d @aphrody/m3-codemods
```

```ts
import { transformSource } from "@aphrody/m3-codemods";

const { source, diagnostics } =
  transformSource(`import { Button } from "@mui/material";
export const Save = () => <Button variant="outlined">Save</Button>;`);
console.log(source); // MdOutlinedButton from @aphrody/m3-react
console.log(diagnostics); // MIGRATION-TODO notes left for manual work
```

许可证: Apache-2.0(`LICENSE`) (中文(简体) ). 安装指南 : [文件/材料/立方米/INSTALL.md](https://github.com/aphrody-labs/bun-distribution/blob/os/docs/material/m3/INSTALL.md)。 。 。 .

没有运行时间依赖性:引擎单独运行于 Bun. `m3-bun migrate` 运行这些转换在一个项目上.

## 两个工具

| 工具 | 作用 |
| --- | --- |
| 转变(`transforms/`(中文(简体) ) | 完全重写:进口,JSX,道具,插槽;变相知觉和一能. |
| ast-grep 规则(`rules/`(中文(简体) ) | 盘点需要迁移的东西,加上一些微不足道的修补. |

## 变换

所有转换共享 `lib/engine.ts` (地图表) `lib/mapping.ts`, JSX 帮助者 `lib/jsx-helpers.ts`) (中文(简体) ). 读取来源 使用TSX扫描仪(`lib/tsx-scan.ts`)并被定位文本编辑所更改(`lib/edits.ts`),所以未触及的代码保持其 格式化。 输入必须是 TSX `Bun.Transpiler` 接受;否则文件保持不变,但有一个 `SyntaxError`。 。 。 .

| 变形 | 范围 |
| --- | --- |
| `transforms/orchestrator.ts` | 全图(推荐批量迁移). |
| `transforms/mui-imports.ts` | 与管弦乐团(语义化名)相同. |
| `transforms/button.ts` | `Button`, (中文(简体) ), `IconButton`, (中文(简体) ), `Fab` 只有(变相意识). |
| `transforms/fields.ts` | `TextField`, (中文(简体) ), `Select`, (中文(简体) ), `NativeSelect` (+ 数) `MenuItem`仅此而已. |
| `transforms/icons.ts` | `@mui/icons-material` 改为 `<md-icon>` (实体符号名称). |

从此包的检出 :

```sh
bun scripts/codemod.ts orchestrator 'src/**/*.tsx' --dry   # list the files that would change
bun scripts/codemod.ts icons src/App.tsx                   # write the change
```

每一次改变出口 `default (file: { path?, source }, api?, options?) => string`。 。 。 . `icons.ts` 分开( 管弦乐手不碰 `@mui/icons-material`: `<CloseIcon/>` 变成 `<md-icon>close</md-icon>` 结束 `lib/icon-names.ts` (PascalCase to snake case, 与 4253 个官方格莱弗在 `data/material-symbols-names.json`;品牌标志用TODO保存. 集成组件和图标映射为 `mui-m3-map.json` (单位:千美元)`bun scripts/export-map-json.ts`) (中文(简体) ). 目标明确的改革(`button`, (中文(简体) ), `fields`只接触它们的组件.

### 自动

-   导入 : `@mui/material` 命名、 默认子路径和别名导入成为排序 `import { ... } from "@aphrody/m3-react"`; 副作用导入 `@aphrody/material-web/icon/icon.js` 当一个 `<md-icon>` 生成.
-   变相意识包装: `Button` 内有(或无) / 概述 / 文本 / 提升 / 直线改为 `MdFilledButton`, (中文(简体) ), `MdOutlinedButton`, (中文(简体) ), `MdTextButton`, (中文(简体) ), `MdElevatedButton`, (中文(简体) ), `MdFilledTonalButton`· ; `TextField` 财务报告和审定财务报表 `Select` 已填入或 大纲成为匹配 `MdFilled*` 编号 : `MdOutlined*`编辑 `variant` 道具被消耗.
-   一对一重命名: `Checkbox` 改为 `MdCheckbox`, (中文(简体) ), `Switch` 改为 `MdSwitch`, (中文(简体) ), `Dialog` 改为 `MdDialog`, (中文(简体) ), `MenuItem` 改为 `MdMenuItem`, (中文(简体) ), `Divider` 改为 `MdDivider`, (中文(简体) ), `Typography` 改为 `MdType`,等等。 (笑声).
-   图标 : `startIcon` 编号 : `endIcon` 变成 `<md-icon slot="icon">` 作为第一个孩子 (TODO: `endIcon`) (中文(简体) ).
-   分层部件 : `DialogTitle` 编号 : `DialogContent` 编号 : `DialogActions` 财务报告和审定财务报表 `CardContent` 编号 : `CardHeader` 编号 : `CardMedia` 变成 `<div slot="headline|content|actions|media">` (与一个TODO).
-   布局 : `Box`, (中文(简体) ), `Container`, (中文(简体) ), `Stack`, (中文(简体) ), `Grid`, (中文(简体) ), `Paper` 变成 `<div>` (Tailwind课程的TODO).
-   其他的都一样 `MIGRATION-TODO` 标记总是有效的 JSX.

### 手动( 标记) `MIGRATION-TODO`(中文(简体) )

-   `sx`: 删除; 转换为 Tailwind 类和 `--md-sys-*` 标志。 尾风无法到达阴影 DOM `md-*`。 。 。 .
-   `onChange(e, value)`: 物质-网络传播本土 `input` 编号 : `change` 事件; 读取 `e.target.value`。处理器尸体不是 重写.
-   无等同物的道具( E)`color`, (中文(简体) ), `size`, (中文(简体) ), `fullWidth`, (中文(简体) ), `disableElevation`, (中文(简体) ), `disableRipple`页:1.
-   差距部分(`Avatar`, (中文(简体) ), `Alert`, (中文(简体) ), `Breadcrumbs`, (中文(简体) ), `Rating`, (中文(简体) ), `Skeleton`, (中文(简体) ), `Backdrop`, (中文(简体) ), `Modal`, (中文(简体) ), `Popover`, (中文(简体) ), `Popper`, (中文(简体) ), `Link`, (中文(简体) ), 过渡, `CssBaseline`(......)没有改变;他们的JSX和MUI进口停留.
-   对话框和牌位:检查每个 `<div slot>` 直系子女为: `md-*` 亲子关系.

### 已知限制

-   Handler身体和可控状态逻辑不重写.
-   成员表达部分(`<Foo.Bar/>`)和间接再出口(`import { Button } from "./ui"`未处理.
-   `Tab` 总是变成 `MdPrimaryTab`。 。 。 .
-   被重新命名的元素的儿童失去断线 JSX 白空间(化妆;跑) `bun fmt` 后来).
-   `startIcon` 编号 : `endIcon` 自动关闭元件的去除没有 `<md-icon>` (TODO添加).

## ast-grep 规则(`rules/`, (中文(简体) ), `sgconfig.yml`(中文(简体) )

```sh
ast-grep scan                                           # report for the project (from this directory)
ast-grep scan --filter '^fix-divider$' --update-all     # apply the Divider fix
```

| 规则 | 仁爱 | 效果 |
| --- | --- | --- |
| `detect-mui-imports` | 报告,警告 | 每个 `@mui/material` 导入(根和子路径). |
| `detect-gap-components` | 报告,错误 | 空白组件无 `md-*` 相当. |
| `detect-sx-prop` | 报告,警告 | `sx` 道具来皈依. |
| `fix-divider` | 可修复 | `<Divider .../>` 改为 `<md-divider ...>` (进口保留). |

规则不选择变体或管理进口;使用变体进行真正的迁移.

## 固定设备

固定装置存在之前/之后 `__testfixtures__/` (前缀) `icons-` 运行 `icons` 变身,其他的乐团. `bun scripts/run-fixtures.ts` 比较它们(`--update` 在预期变动后,重新产生预期产出.

## 常见问题

### @aphrody/m3-codemods 是什么？

代码MUI React - \> @aphody/m3-react \(Bun, sans dépendance runtime\) \+ règles ast-grep

### 如何安装 @aphrody/m3-codemods？

在项目目录运行 npm install @aphrody/m3-codemods，或使用 pnpm add / yarn add / bun add。

### @aphrody/m3-codemods 支持 TypeScript 吗？

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

### @aphrody/m3-codemods 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aphrody/m3-codemods 可以商用吗？

@aphrody/m3-codemods 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aphrody/m3-codemods 的下载量有多少？

根据 npm 官方下载统计，@aphrody/m3-codemods 在 2026/10/06 – 2026/11/04 这 30 天内被下载 1,806 次，日均约 60 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aphrody/m3-codemods 还在维护吗？

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