migrate-v1-to-v2

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

从 v1 迁移到 v2 技能

v1-to-v2 Migration Skill

本技能用于辅助用户将项目从
Wot UI v1
(
wot-design-uni
) 迁移到
Wot UI v2
(
@wot-ui/ui
)。
完整迁移指南:中文 / English。

This skill helps users migrate a project from
Wot UI v1
(
wot-design-uni
) to
Wot UI v2
(
@wot-ui/ui
).
Complete migration guide: Chinese / English.

职责边界

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

在开始任何操作前,先向用户确认以下三点(如果上下文已可推断则跳过对应问题):
  1. 安装方式:npm 还是 uni_modules?(影响导入路径和 easycom 配置)
  2. 目标:
    • A. 全量迁移(项目尚未升级)→ 按阶段一~七执行
    • B. 升级后修错误(已升级但遇到编译/运行时报错)→ 先读
      errors.md
      定位问题
  3. 目标平台: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):
  1. Installation method: npm or uni_modules? (This affects import paths and easycom configuration.)
  2. 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
      errors.md
      first to identify the issue
  3. Target platform: H5 / WeChat Mini Program / Alipay Mini Program? (This affects style isolation and the easycom validation approach.)

快速通道

Quick Paths

根据用户描述的问题,直接加载对应子文件:
关键词子文件
错误信息 / 编译报错 / 找不到模块 / is not defined / 升级后异常
errors.md
表单 / Form / schema / zodAdapter / FormRules / 校验 / 必填星号
form.md
包名 / easycom / Volar / vite 插件 / 国际化 / 路径替换 / uni_modules
infra.md
Sass / 主题 / Design Token / CSS 变量 / 样式覆盖 / 深色模式 / ConfigProvider
styles.md
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
components.md
Icon / 图标 / wd-icon / icon / iconClass / activeIcon / inactiveIcon / prefixIcon / suffixIcon / 空图标
components.md
的“图标迁移”与
icons.json

Load the corresponding subfile directly based on the issue described by the user:
KeywordsSubfile
Error message / compilation error / module not found / is not defined / post-upgrade issue
errors.md
Form / schema / zodAdapter / FormRules / validation / required-field asterisk
form.md
Package name / easycom / Volar / Vite plugin / internationalization / path replacement / uni_modules
infra.md
Sass / theme / Design Token / CSS variables / style overrides / dark mode / ConfigProvider
styles.md
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
components.md
Icon / wd-icon / icon / iconClass / activeIcon / inactiveIcon / prefixIcon / suffixIcon / blank iconThe “Icon Migration” section of
components.md
and
icons.json

核心变更速查表

Quick Reference for Core Changes

类型v1v2
npm 包名
wot-design-uni
@wot-ui/ui
uni_modules 目录
wot-design-uni
wot-ui
弹框组件
wd-message-box
wd-dialog
弹框 Hook
useMessage
useDialog
缺省提示
wd-status-tip
wd-empty
多列选择器
wd-col-picker
wd-cascader
数字键盘
wd-number-keyboard
wd-keyboard
表单校验
rules
/
FormRules
schema
/
FormSchema
按钮变体
plain
/
type="text"
/
type="icon"
variant
/ 图标按钮
按钮危险色
type="error"
type="danger"
标签变体
plain
variant="plain"
单选/复选形态
shape
/
inline
/
cell
type
/
direction
/ 手动组合
wd-cell
搜索框浅色样式
light
variant="light"
GridItem 点击
@itemclick
@click
工具函数路径
components/common/util
common/util
内置图标名称v1 图标集合按
icons.json
中的人工审核结果迁移

Typev1v2
npm package name
wot-design-uni
@wot-ui/ui
uni_modules directory
wot-design-uni
wot-ui
Dialog component
wd-message-box
wd-dialog
Dialog Hook
useMessage
useDialog
Empty state
wd-status-tip
wd-empty
Multi-column picker
wd-col-picker
wd-cascader
Numeric keyboard
wd-number-keyboard
wd-keyboard
Form validation
rules
/
FormRules
schema
/
FormSchema
Button variants
plain
/
type="text"
/
type="icon"
variant
/ icon button
Button danger color
type="error"
type="danger"
Tag variants
plain
variant="plain"
Radio/checkbox appearance
shape
/
inline
/
cell
type
/
direction
/ manual composition with
wd-cell
Search box light style
light
variant="light"
GridItem click
@itemclick
@click
Utility path
components/common/util
common/util
Built-in icon namesv1 icon collectionMigrate according to the manually reviewed mappings in
icons.json

迁移流程

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

  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="
  4. 如果项目有表单,额外搜索:
    bash
    rg "wd-form|FormRules|:rules=|rules=|errorType|resetOnChange"
  5. 向用户汇报发现的清单,按影响程度排序:
    • 高影响:Form(结构+校验体系)、Dialog(原 MessageBox)、ColPicker、NumberKeyboard
    • 中影响:Button、Tag、Radio/Checkbox、Search、Grid、Fab、内置图标名称
    • 低影响:camelCase 属性名、Badge/Slider/Tabs/Steps/Swiper 等属性微调
  1. Determine the user's installation method (
    npm
    or
    uni_modules
    ).
  2. Verify the project configuration:
    pages.json
    easycom,
    tsconfig.json
    type declarations, and Vite plugin auto-imports.
  3. 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="
  4. If the project contains forms, search for the following as well:
    bash
    rg "wd-form|FormRules|:rules=|rules=|errorType|resetOnChange"
  5. 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

详见
infra.md
(包名、easycom、Volar、Vite 插件、国际化)和
styles.md
(Sass 升级)。读完后回到阶段三继续。
See
infra.md
for package names, easycom, Volar, the Vite plugin, and internationalization, and see
styles.md
for the Sass upgrade. After reading them, return to Phase 3 and continue.

阶段三:高影响组件迁移

Phase 3: High-Impact Component Migration

详见
components.md
(MessageBox→Dialog、StatusTip→Empty、ColPicker→Cascader、NumberKeyboard→Keyboard)。
Form 表单体系详见
form.md
。读完后回到阶段四继续。
See
components.md
for MessageBox→Dialog, StatusTip→Empty, ColPicker→Cascader, and NumberKeyboard→Keyboard.
See
form.md
for the Form system. After reading it, return to Phase 4 and continue.

阶段四:中影响组件迁移

Phase 4: Medium-Impact Component Migration

详见
components.md
(Button、Tag、Radio/Checkbox、Search、Grid、Fab)。读完后回到阶段五继续。
See
components.md
for Button, Tag, Radio/Checkbox, Search, Grid, and Fab. After reading it, return to Phase 5 and continue.

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

Phase 5: Low-Impact Prop and Icon Migration

详见
components.md
(Badge、Slider、Tabs、Steps、Swiper、Tooltip、Popover、Collapse、DatetimePickerView、ImgCropper、CountTo、Segmented、PickerView、图标迁移、camelCase 属性名)。迁移图标时必须读取
icons.json
,只替换确认映射;“无对应”和动态绑定项保留给人工决策。读完后回到阶段六继续。
See
components.md
for Badge, Slider, Tabs, Steps, Swiper, Tooltip, Popover, Collapse, DatetimePickerView, ImgCropper, CountTo, Segmented, PickerView, icon migration, and camelCase prop names. When migrating icons,
icons.json
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.

阶段六:样式与主题迁移

Phase 6: Style and Theme Migration

详见
styles.md
(主题文件引入、全局变量覆盖、ConfigProvider、样式覆盖优先级、深色模式)。读完后进入阶段七回归验证。
See
styles.md
for theme file imports, global variable overrides, ConfigProvider, style override precedence, and dark mode. After reading it, proceed to Phase 7 for regression validation.

阶段七:回归验证

Phase 7: Regression Validation

  • 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
    是否已经单独列出并人工确认
  • 图标的业务语义和视觉结果是否正确,名称大小写是否保持准确
  • 图标按钮高度变化是否影响页面布局
  • Can H5 and the target Mini Program platform compile normally?
  • Can easycom correctly resolve all
    wd-*
    components?
  • Are instances of functional calls such as
    Toast
    ,
    Dialog
    , and
    Notify
    declared on the page?
  • 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
    ,
    round
    , and height of
    Button
    meet expectations?
  • Has the
    variant
    of
    Tag
    been migrated from
    plain
    ?
  • Have the
    shape
    ,
    inline
    , and
    cell
    props of
    Radio
    /
    Checkbox
    been migrated?
  • Has the
    light
    prop of
    Search
    been migrated to
    variant="light"
    ?
  • Has the GridItem click event been migrated from
    itemclick
    to
    click
    ?
  • Have the form-related props of
    Cell
    ,
    Input
    , and
    Textarea
    been migrated to
    wd-form-item
    ?
  • Can instance methods such as those of
    PickerView
    ,
    ImgCropper
    , and
    CountTo
    still be called normally?
  • Have legacy props of components such as
    Badge
    ,
    Slider
    ,
    Tabs
    ,
    Steps
    , and
    Swiper
    been migrated?
  • 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
    icons.json
    , without globally replacing business strings?
  • Were “No Match” entries, dynamic bindings, and
    iconClass
    /
    activeIcon
    /
    inactiveIcon
    /
    prefixIcon
    /
    suffixIcon
    listed separately and manually confirmed?
  • 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?