migrate-v1-to-v2
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinese从 v1 迁移到 v2 技能
v1-to-v2 Migration Skill
职责边界
Responsibility Boundaries
- 扫描 v1 用法、替换包名/路径、迁移组件 API、迁移表单校验体系与内置图标名称、修复不兼容变更。
- 不负责新建业务页面或重构业务逻辑,仅做最小必要的兼容性替换。
- 不负责安装依赖,由用户自行在终端执行。
- Scan v1 usage, replace package names/paths, migrate component APIs, migrate the form validation system and built-in icon names, and fix breaking changes.
- Not responsible for creating new business pages or refactoring business logic; perform only the minimum necessary compatibility replacements.
- Not responsible for installing dependencies; the user should run the commands in their terminal.
首次交互确认
Initial Interaction and Confirmation
在开始任何操作前,先向用户确认以下三点(如果上下文已可推断则跳过对应问题):
- 安装方式:npm 还是 uni_modules?(影响导入路径和 easycom 配置)
- 目标:
- A. 全量迁移(项目尚未升级)→ 按阶段一~七执行
- B. 升级后修错误(已升级但遇到编译/运行时报错)→ 先读 定位问题
errors.md
- 目标平台:H5 / 微信小程序 / 支付宝小程序?(影响样式隔离和 easycom 验证方式)
Before starting any operations, confirm the following three points with the user (skip any question that can already be inferred from the context):
- Installation method: npm or uni_modules? (This affects import paths and easycom configuration.)
- Goal:
- A. Full migration (the project has not yet been upgraded) → execute Phases 1–7
- B. Fix errors after upgrading (the project has been upgraded but is encountering compilation/runtime errors) → read first to identify the issue
errors.md
- Target platform: H5 / WeChat Mini Program / Alipay Mini Program? (This affects style isolation and the easycom validation approach.)
快速通道
Quick Paths
根据用户描述的问题,直接加载对应子文件:
| 关键词 | 子文件 |
|---|---|
| 错误信息 / 编译报错 / 找不到模块 / is not defined / 升级后异常 | |
| 表单 / Form / schema / zodAdapter / FormRules / 校验 / 必填星号 | |
| 包名 / easycom / Volar / vite 插件 / 国际化 / 路径替换 / uni_modules | |
| Sass / 主题 / Design Token / CSS 变量 / 样式覆盖 / 深色模式 / ConfigProvider | |
| Dialog / MessageBox / Empty / StatusTip / Cascader / ColPicker / Keyboard / NumberKeyboard / Button / Tag / Radio / Checkbox / Search / Grid / Fab / Badge / Slider / Tabs / Steps / Swiper / Tooltip / Popover / Collapse / Cell / Input / Textarea / PickerView / ImgCropper / CountTo / Segmented | |
| Icon / 图标 / wd-icon / icon / iconClass / activeIcon / inactiveIcon / prefixIcon / suffixIcon / 空图标 | |
Load the corresponding subfile directly based on the issue described by the user:
| Keywords | Subfile |
|---|---|
| Error message / compilation error / module not found / is not defined / post-upgrade issue | |
| Form / schema / zodAdapter / FormRules / validation / required-field asterisk | |
| Package name / easycom / Volar / Vite plugin / internationalization / path replacement / uni_modules | |
| Sass / theme / Design Token / CSS variables / style overrides / dark mode / ConfigProvider | |
| Dialog / MessageBox / Empty / StatusTip / Cascader / ColPicker / Keyboard / NumberKeyboard / Button / Tag / Radio / Checkbox / Search / Grid / Fab / Badge / Slider / Tabs / Steps / Swiper / Tooltip / Popover / Collapse / Cell / Input / Textarea / PickerView / ImgCropper / CountTo / Segmented | |
| Icon / wd-icon / icon / iconClass / activeIcon / inactiveIcon / prefixIcon / suffixIcon / blank icon | The “Icon Migration” section of |
核心变更速查表
Quick Reference for Core Changes
| 类型 | v1 | v2 |
|---|---|---|
| npm 包名 | | |
| uni_modules 目录 | | |
| 弹框组件 | | |
| 弹框 Hook | | |
| 缺省提示 | | |
| 多列选择器 | | |
| 数字键盘 | | |
| 表单校验 | | |
| 按钮变体 | | |
| 按钮危险色 | | |
| 标签变体 | | |
| 单选/复选形态 | | |
| 搜索框浅色样式 | | |
| GridItem 点击 | | |
| 工具函数路径 | | |
| 内置图标名称 | v1 图标集合 | 按 |
| Type | v1 | v2 |
|---|---|---|
| npm package name | | |
| uni_modules directory | | |
| Dialog component | | |
| Dialog Hook | | |
| Empty state | | |
| Multi-column picker | | |
| Numeric keyboard | | |
| Form validation | | |
| Button variants | | |
| Button danger color | | |
| Tag variants | | |
| Radio/checkbox appearance | | |
| Search box light style | | |
| GridItem click | | |
| Utility path | | |
| Built-in icon names | v1 icon collection | Migrate according to the manually reviewed mappings in |
迁移流程
Migration Process
推荐顺序:依赖升级 → 路径替换 → Form 页面 → 高影响组件 → 中低影响组件 → 图标与低影响属性 → 样式与主题 → 回归测试。
每完成一个阶段后与用户确认再进入下一阶段。
Recommended order: dependency upgrade → path replacement → Form pages → high-impact components → medium- and low-impact components → icons and low-impact props → styles and theming → regression testing.
Confirm with the user after completing each phase before proceeding to the next one.
阶段一:扫描与诊断
Phase 1: Scanning and Diagnosis
-
确定用户的安装方式(还是
npm)。uni_modules -
确认项目配置:easycom、
pages.json类型声明、Vite 插件自动导入。tsconfig.json -
搜索 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=" -
如果项目有表单,额外搜索:bash
rg "wd-form|FormRules|:rules=|rules=|errorType|resetOnChange" -
向用户汇报发现的清单,按影响程度排序:
- 高影响:Form(结构+校验体系)、Dialog(原 MessageBox)、ColPicker、NumberKeyboard
- 中影响:Button、Tag、Radio/Checkbox、Search、Grid、Fab、内置图标名称
- 低影响:camelCase 属性名、Badge/Slider/Tabs/Steps/Swiper 等属性微调
-
Determine the user's installation method (or
npm).uni_modules -
Verify the project configuration:easycom,
pages.jsontype declarations, and Vite plugin auto-imports.tsconfig.json -
Search for legacy v1 usage: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=" -
If the project contains forms, search for the following as well:bash
rg "wd-form|FormRules|:rules=|rules=|errorType|resetOnChange" -
Report the findings to the user, sorted by impact:
- High impact: Form (structure and validation system), Dialog (formerly MessageBox), ColPicker, NumberKeyboard
- Medium impact: Button, Tag, Radio/Checkbox, Search, Grid, Fab, built-in icon names
- Low impact: camelCase prop names and minor prop adjustments to Badge/Slider/Tabs/Steps/Swiper, etc.
阶段二:依赖与路径替换
Phase 2: Dependency and Path Replacement
详见 (包名、easycom、Volar、Vite 插件、国际化)和 (Sass 升级)。读完后回到阶段三继续。
infra.mdstyles.mdSee for package names, easycom, Volar, the Vite plugin, and internationalization, and see for the Sass upgrade. After reading them, return to Phase 3 and continue.
infra.mdstyles.md阶段三:高影响组件迁移
Phase 3: High-Impact Component Migration
详见 (MessageBox→Dialog、StatusTip→Empty、ColPicker→Cascader、NumberKeyboard→Keyboard)。
components.mdForm 表单体系详见 。读完后回到阶段四继续。
form.mdSee for MessageBox→Dialog, StatusTip→Empty, ColPicker→Cascader, and NumberKeyboard→Keyboard.
components.mdSee for the Form system. After reading it, return to Phase 4 and continue.
form.md阶段四:中影响组件迁移
Phase 4: Medium-Impact Component Migration
详见 (Button、Tag、Radio/Checkbox、Search、Grid、Fab)。读完后回到阶段五继续。
components.mdSee for Button, Tag, Radio/Checkbox, Search, Grid, and Fab. After reading it, return to Phase 5 and continue.
components.md阶段五:低影响属性与图标迁移
Phase 5: Low-Impact Prop and Icon Migration
详见 (Badge、Slider、Tabs、Steps、Swiper、Tooltip、Popover、Collapse、DatetimePickerView、ImgCropper、CountTo、Segmented、PickerView、图标迁移、camelCase 属性名)。迁移图标时必须读取 ,只替换确认映射;“无对应”和动态绑定项保留给人工决策。读完后回到阶段六继续。
components.mdicons.jsonSee for Badge, Slider, Tabs, Steps, Swiper, Tooltip, Popover, Collapse, DatetimePickerView, ImgCropper, CountTo, Segmented, PickerView, icon migration, and camelCase prop names. When migrating icons, must be read, and only confirmed mappings should be replaced; leave “No Match” entries and dynamically bound items for manual decision-making. After reading it, return to Phase 6 and continue.
components.mdicons.json阶段六:样式与主题迁移
Phase 6: Style and Theme Migration
详见 (主题文件引入、全局变量覆盖、ConfigProvider、样式覆盖优先级、深色模式)。读完后进入阶段七回归验证。
styles.mdSee for theme file imports, global variable overrides, ConfigProvider, style override precedence, and dark mode. After reading it, proceed to Phase 7 for regression validation.
styles.md阶段七:回归验证
Phase 7: Regression Validation
- H5 和目标小程序端是否能正常编译
- 是否能正确解析所有
easycom组件wd-* - 、
Toast、Dialog等函数式调用是否已在页面中声明实例Notify - 表单提交、单字段校验、重置、隐藏字段和异步校验是否正常
- 选择器类表单项的回显文本和提交值是否正确
- 的
Button、type、variant和高度是否符合预期round - 的
Tag是否已从variant迁移plain - /
Radio的Checkbox、shape、inline是否已迁移cell - 的
Search是否已迁移为lightvariant="light" - 点击事件是否已从
GridItem迁移到itemclickclick - 、
Cell、Input的表单相关属性是否已迁移到Textareawd-form-item - 、
PickerView、ImgCropper等实例方法是否仍可正常调用CountTo - 、
Badge、Slider、Tabs、Steps等旧属性是否已迁移Swiper - 点击遮罩关闭、Prompt 返回值和按钮配置是否符合预期
Dialog - 深色模式、主题变量、品牌色覆盖是否生效
- 弹层在小程序端是否存在样式隔离问题
- 自定义覆盖样式是否仍然生效
- 所有静态内置图标名是否按 处理,且没有对业务字符串做全局替换
icons.json - “无对应”、动态绑定和 /
iconClass/activeIcon/inactiveIcon/prefixIcon是否已经单独列出并人工确认suffixIcon - 图标的业务语义和视觉结果是否正确,名称大小写是否保持准确
- 图标按钮高度变化是否影响页面布局
- Can H5 and the target Mini Program platform compile normally?
- Can easycom correctly resolve all components?
wd-* - Are instances of functional calls such as ,
Toast, andDialogdeclared on the page?Notify - Do form submission, single-field validation, reset, hidden fields, and async validation work correctly?
- Are the display text and submitted values of picker form fields correct?
- Do the ,
type,variant, and height ofroundmeet expectations?Button - Has the of
variantbeen migrated fromTag?plain - Have the ,
shape, andinlineprops ofcell/Radiobeen migrated?Checkbox - Has the prop of
lightbeen migrated toSearch?variant="light" - Has the GridItem click event been migrated from to
itemclick?click - Have the form-related props of ,
Cell, andInputbeen migrated toTextarea?wd-form-item - Can instance methods such as those of ,
PickerView, andImgCropperstill be called normally?CountTo - Have legacy props of components such as ,
Badge,Slider,Tabs, andStepsbeen migrated?Swiper - Do Dialog overlay-click closing, Prompt return values, and button configuration meet expectations?
- Do dark mode, theme variables, and brand color overrides take effect?
- Are there style isolation issues with overlays on Mini Program platforms?
- Do custom override styles remain effective?
- Were all static built-in icon names handled according to , without globally replacing business strings?
icons.json - Were “No Match” entries, dynamic bindings, and /
iconClass/activeIcon/inactiveIcon/prefixIconlisted separately and manually confirmed?suffixIcon - Are the business semantics and visual results of the icons correct, and is capitalization accurate?
- Do changes in icon button height affect the page layout?