AGENT SKILL
taro2rn
Taro 小程序代码转 React Native 完整工具包。提供组件映射、API 映射、样式转换规则和已知问题解决方案。兼容 Taro 3.x 与 React Native 0.72+。
使用场景前端开发
- License 许可
- Apache-2.0
- 最近更新
- 2026-05-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- taro2rn
- description
- Taro 小程序代码转 React Native 完整工具包。提供组件映射、API 映射、样式转换规则和已知问题解决方案。兼容 Taro 3.x 与 React Native 0.72+。
- when_to_use
- 用户需要将 Taro 项目代码迁移至 React Native 时触发。Trigger phrases: '转 RN' / '转换 RN' / 'taro to rn' / 'taro2rn' / '迁移成原生' / 'port Taro to RN' / 'Taro 转 native' / '从 Taro 迁出'。也包括询问 Taro/RN 组件映射、样式映射、迁移问题。Do NOT use for: uni-app 或 Vue 小程序迁移、纯新建 RN 项目(无 Taro 来源)、单文件实验性转换、纯 RN 项目调试。
- allowed-tools
- Read Write Edit Glob Grep
02 资源文件 11
- 资产文件assets/TODO_TEMPLATE.md1.3 KB
- 参考文档references/api.md4.4 KB
- 参考文档references/components.md4.9 KB
- 参考文档references/im-layout.md3.5 KB
- 参考文档references/KNOWN_ISSUES.md2.4 KB
- 参考文档references/known-issues-api.md7.0 KB
- 参考文档references/known-issues-dependencies.md5.7 KB
- 参考文档references/known-issues-monorepo.md1.8 KB
- 参考文档references/known-issues-styles.md4.9 KB
- 参考文档references/styles.md4.0 KB
- 参考文档references/TRANSFORM_RULES.md2.2 KB
03 SKILL.md 正文
Taro to React Native 转换
快速开始
第一步:处理 taro2rnTODO.md
检查项目根目录是否存在 taro2rnTODO.md:
| 情况 | 操作 |
|---|---|
| 存在 | 读取进度,跳至第二步 |
| 不存在 | 执行初始化流程(见下方) |
初始化流程
- 询问用户配置:
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 项目名称 | 当前目录名 | 标识项目 |
| 设计稿宽度 | 750 | 750 或 1242 |
| RN 应用路径 | . | React Native 应用相对路径 |
- 基于模板生成 taro2rnTODO.md:读取
assets/TODO_TEMPLATE.md,替换占位符后写入项目根目录。
第二步:执行转换
进入实际转换前 ultrathink:先确认设计稿宽度、检查 rpx 工具函数是否已封装、识别项目是否为 Monorepo(pnpm-workspace.yaml 或 workspaces 字段)。这三项判断错了后续每次转换都要返工。
- 读取 Taro 源码,分析组件结构
- 按场景加载对应转换规则(见下方索引)
- 遇到问题查阅对应子域 known-issues 文件
- 完成后更新
taro2rnTODO.md
转换规则(按需加载)
主要转换规则
| 转换场景 | 加载文件 | 包含内容 |
|---|---|---|
| 规则索引 + 速查 | references/TRANSFORM_RULES.md | 最常用映射速查表(先读这个) |
| 组件转换 | references/components.md | 基础组件映射、事件处理、Portal/RichText/WebView、导入汇总 |
| API / 生命周期 | references/api.md | 路由、存储、网络、UI 反馈、页面生命周期、平台代码 |
| 样式转换 | references/styles.md | rpx 单位、Flex、文字/边框/定位、不支持的 CSS、动态宽度 |
| IM 聊天页面 | references/im-layout.md | 键盘避让、FlatList inverted、滚动监听、分页加载 |
已知问题(按子域加载,不要一次性读全部)
| 子域 | 加载文件 | 适用场景 |
|---|---|---|
| 依赖兼容 | references/known-issues-dependencies.md | 渐变、安全区、Picker、DatePicker、常用依赖清单 |
| 样式差异 | references/known-issues-styles.md | rpx 设计稿、Image、阴影、Flex 宽度、模糊效果 |
| API / 键盘 / React 版本 | references/known-issues-api.md | API 差异、ScrollView 监听、IM 键盘、React 版本冲突 |
| Monorepo | references/known-issues-monorepo.md | pnpm 依赖提升、CocoaPods、Metro、Monorepo React 冲突 |
| (索引/兼容) | references/KNOWN_ISSUES.md | 子域路由索引(旧链接仍可用) |
加载策略:先读 TRANSFORM_RULES.md 速查表 → 不够用时按场景加载详细 references → 遇到具体问题只加载对应子域的 known-issues-*.md。
转换工作流
1. 处理 taro2rnTODO.md → 初始化或读取现有进度
2. 确认设计稿标准 → 750 用 rpx(),1242 用 rpx1242()
3. 读取 Taro 源码 → 分析组件结构
4. 应用转换规则 → 按需加载对应 references
5. 处理特殊情况 → 按子域查阅 known-issues-*.md
6. 更新 taro2rnTODO.md → 标记完成
文档结构
taro2rn/
├── SKILL.md # 入口(本文件)
├── references/
│ ├── TRANSFORM_RULES.md # 规则索引 + 速查表
│ ├── components.md # 组件映射详细规则
│ ├── api.md # API/生命周期映射
│ ├── styles.md # 样式转换规则
│ ├── im-layout.md # IM 页面布局方案
│ ├── KNOWN_ISSUES.md # 已知问题索引(旧链接兼容)
│ ├── known-issues-dependencies.md # 依赖兼容
│ ├── known-issues-styles.md # 样式差异
│ ├── known-issues-api.md # API/键盘/React 版本
│ └── known-issues-monorepo.md # Monorepo 特有
└── assets/
└── TODO_TEMPLATE.md # 项目进度模板
