从 v1 迁移到 v2 技能

本技能用于辅助用户将项目从 Wot UI v1 (wot-design-uni) 迁移到 Wot UI v2 (@wot-ui/ui)。

完整迁移指南：中文 / English。

职责边界

• 扫描 v1 用法、替换包名/路径、迁移组件 API、迁移表单校验体系与内置图标名称、修复不兼容变更。
• 不负责新建业务页面或重构业务逻辑，仅做最小必要的兼容性替换。
• 不负责安装依赖，由用户自行在终端执行。

首次交互确认

在开始任何操作前，先向用户确认以下三点（如果上下文已可推断则跳过对应问题）：

1. 安装方式：npm 还是 uni_modules？（影响导入路径和 easycom 配置）
2. 目标：

- A. 全量迁移（项目尚未升级）→ 按阶段一～七执行 - B. 升级后修错误（已升级但遇到编译/运行时报错）→ 先读 errors.md 定位问题

1. 目标平台：H5 / 微信小程序 / 支付宝小程序？（影响样式隔离和 easycom 验证方式）

快速通道

根据用户描述的问题，直接加载对应子文件：

核心变更速查表

迁移流程

推荐顺序：依赖升级 → 路径替换 → Form 页面 → 高影响组件 → 中低影响组件 → 图标与低影响属性 → 样式与主题 → 回归测试。

每完成一个阶段后与用户确认再进入下一阶段。

阶段一：扫描与诊断

1. 确定用户的安装方式（npm 还是 uni_modules）。
2. 确认项目配置：pages.json easycom、tsconfig.json 类型声明、Vite 插件自动导入。
3. 搜索 v1 旧用法：

``bash rg "wot-design-uni|wd-message-box|useMessage|wd-status-tip|wd-col-picker|wd-number-keyboard|wd-icon|icon-class|iconClass|active-icon|activeIcon|inactive-icon|inactiveIcon|prefix-icon|prefixIcon|suffix-icon|suffixIcon|@itemclick|shape=|inline|\scell\b|\slight\b|type=\"error\"|type=\"icon\"|type=\"text\"|\splain\b|classPrefix|components/common/util|hide-label|hide-min-max|autoLineWidth|disabled-color|setRoate|useContentSlot|useMoreSlot|\bshow=" ``

1. 如果项目有表单，额外搜索：

``bash rg "wd-form|FormRules|:rules=|rules=|errorType|resetOnChange" ``

1. 向用户汇报发现的清单，按影响程度排序：

- 高影响：Form（结构+校验体系）、Dialog（原 MessageBox）、ColPicker、NumberKeyboard - 中影响：Button、Tag、Radio/Checkbox、Search、Grid、Fab、内置图标名称 - 低影响：camelCase 属性名、Badge/Slider/Tabs/Steps/Swiper 等属性微调

阶段二：依赖与路径替换

详见 infra.md（包名、easycom、Volar、Vite 插件、国际化）和 styles.md（Sass 升级）。读完后回到阶段三继续。

阶段三：高影响组件迁移

详见 components.md（MessageBox→Dialog、StatusTip→Empty、ColPicker→Cascader、NumberKeyboard→Keyboard）。

Form 表单体系详见 form.md。读完后回到阶段四继续。

阶段四：中影响组件迁移

详见 components.md（Button、Tag、Radio/Checkbox、Search、Grid、Fab）。读完后回到阶段五继续。

阶段五：低影响属性与图标迁移

详见 components.md（Badge、Slider、Tabs、Steps、Swiper、Tooltip、Popover、Collapse、DatetimePickerView、ImgCropper、CountTo、Segmented、PickerView、图标迁移、camelCase 属性名）。迁移图标时必须读取 icons.json，只替换确认映射；“无对应”和动态绑定项保留给人工决策。读完后回到阶段六继续。

阶段六：样式与主题迁移

详见 styles.md（主题文件引入、全局变量覆盖、ConfigProvider、样式覆盖优先级、深色模式）。读完后进入阶段七回归验证。

阶段七：回归验证

• H5 和目标小程序端是否能正常编译
• easycom 是否能正确解析所有 wd-* 组件
• Toast、Dialog、Notify 等函数式调用是否已在页面中声明实例
• 表单提交、单字段校验、重置、隐藏字段和异步校验是否正常
• 选择器类表单项的回显文本和提交值是否正确
• Button 的 type、variant、round 和高度是否符合预期
• Tag 的 variant 是否已从 plain 迁移
• Radio/Checkbox 的 shape、inline、cell 是否已迁移
• Search 的 light 是否已迁移为 variant="light"
• GridItem 点击事件是否已从 itemclick 迁移到 click
• Cell、Input、Textarea 的表单相关属性是否已迁移到 wd-form-item
• PickerView、ImgCropper、CountTo 等实例方法是否仍可正常调用
• Badge、Slider、Tabs、Steps、Swiper 等旧属性是否已迁移
• Dialog 点击遮罩关闭、Prompt 返回值和按钮配置是否符合预期
• 深色模式、主题变量、品牌色覆盖是否生效
• 弹层在小程序端是否存在样式隔离问题
• 自定义覆盖样式是否仍然生效
• 所有静态内置图标名是否按 icons.json 处理，且没有对业务字符串做全局替换
• “无对应”、动态绑定和 iconClass / activeIcon / inactiveIcon / prefixIcon / suffixIcon 是否已经单独列出并人工确认
• 图标的业务语义和视觉结果是否正确，名称大小写是否保持准确
• 图标按钮高度变化是否影响页面布局