migrate-v1-to-v2

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

从 v1 迁移到 v2 技能

Skill for Migrating from v1 to v2

本技能用于辅助用户将项目从

Wot UI v1

(

wot-design-uni

) 迁移到

Wot UI v2

(

@wot-ui/ui

)。

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

This skill is used to assist users in migrating projects from

Wot UI v1

(

wot-design-uni

) to

Wot UI v2

(

@wot-ui/ui

Complete Migration Guide: 中文 / English.

职责边界

Scope of Responsibilities

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

Scan for v1 usage, replace package names/paths, migrate component APIs, migrate form validation systems, and fix incompatible changes.
Not responsible for creating new business pages or refactoring business logic; only perform minimal necessary compatibility replacements.
Not responsible for dependency installation; users shall execute this in the terminal on their own.

首次交互确认

Initial Interaction Confirmation

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

安装方式：npm 还是 uni_modules？（影响导入路径和 easycom 配置）
目标：
- A. 全量迁移（项目尚未升级）→ 按阶段一～七执行
- B. 升级后修错误（已升级但遇到编译/运行时报错）→ 先读
```
errors.md
```
  定位问题
目标平台：H5 / 微信小程序 / 支付宝小程序？（影响样式隔离和 easycom 验证方式）

Before starting any operation, confirm the following three points with the user (skip corresponding questions if inferable from context):

Installation Method: npm or uni_modules? (Affects import paths and easycom configuration)
Objective:
- A. Full Migration (Project not upgraded yet) → Execute Phase 1 to 7
- B. Fix Errors After Upgrade (Upgraded but encountered compilation/runtime errors) → Locate issues by reading
```
errors.md
```
  first
Target Platform: H5 / WeChat Mini Program / Alipay Mini Program? (Affects style isolation and easycom verification methods)

快速通道

Quick Access

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

关键词	子文件
错误信息 / 编译报错 / 找不到模块 / 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`

Load corresponding sub-files directly based on the user's described issues:

Keywords	Sub-file
Error message / Compilation error / Module not found / is not defined / Abnormal after upgrade	`errors.md`
Form / Form / schema / zodAdapter / FormRules / Validation / Required asterisk	`form.md`
Package name / easycom / Volar / vite plugin / Internationalization / Path replacement / uni_modules	`infra.md`
Sass / Theme / Design Token / CSS variable / Style override / 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`

核心变更速查表

Quick Reference for Core Changes

类型	v1	v2
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`

Type	v1	v2
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 tip	`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 forms	`shape` / `inline` / `cell`	`type` / `direction` / Manual combination with `wd-cell`
Light-style search box	`light`	`variant="light"`
GridItem click event	`@itemclick`	`@click`
Utility function path	`components/common/util`	`common/util`

迁移流程

Migration Process

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

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

Recommended order: Dependency upgrade → Path replacement → Form pages → High-impact components → Medium-low impact components → Styles & themes → Regression testing.

Confirm with the user after completing each phase before proceeding to the next.

阶段一：扫描与诊断

Phase 1: Scanning & Diagnosis

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

搜索 v1 旧用法：

bash

rg "wot-design-uni|wd-message-box|useMessage|wd-status-tip|wd-col-picker|wd-number-keyboard|@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 (
```
npm
```
or
```
uni_modules
```
).
Confirm project configurations:
```
pages.json
```
easycom,
```
tsconfig.json
```
type declarations, Vite plugin auto-import.

Search for v1 legacy usage:

bash

rg "wot-design-uni|wd-message-box|useMessage|wd-status-tip|wd-col-picker|wd-number-keyboard|@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 has forms, additionally search:

bash

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

Report the discovered list to the user, sorted by impact level:
- High Impact: Form (structure + validation system), Dialog (formerly MessageBox), ColPicker, NumberKeyboard
- Medium Impact: Button, Tag, Radio/Checkbox, Search, Grid, Fab
- Low Impact: camelCase property names, minor property adjustments for Badge/Slider/Tabs/Steps/Swiper, etc.

阶段二：依赖与路径替换

Phase 2: Dependency & Path Replacement

详见

infra.md

（包名、easycom、Volar、Vite 插件、国际化）和

styles.md

（Sass 升级）。读完后回到阶段三继续。

See

infra.md

(package name, easycom, Volar, Vite plugin, internationalization) and

styles.md

(Sass upgrade). Return to Phase 3 after reading.

阶段三：高影响组件迁移

Phase 3: Migrate High-Impact Components

详见

components.md

（MessageBox→Dialog、StatusTip→Empty、ColPicker→Cascader、NumberKeyboard→Keyboard）。

Form 表单体系详见

form.md

。读完后回到阶段四继续。

See

components.md

(MessageBox→Dialog, StatusTip→Empty, ColPicker→Cascader, NumberKeyboard→Keyboard).

For Form system migration, see

form.md

. Return to Phase 4 after reading.

阶段四：中影响组件迁移

Phase 4: Migrate Medium-Impact Components

详见

components.md

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

See

components.md

(Button, Tag, Radio/Checkbox, Search, Grid, Fab). Return to Phase 5 after reading.

阶段五：低影响属性迁移

Phase 5: Migrate Low-Impact Properties

详见

components.md

（Badge、Slider、Tabs、Steps、Swiper、Tooltip、Popover、Collapse、DatetimePickerView、ImgCropper、CountTo、Segmented、PickerView、camelCase 属性名）。读完后回到阶段六继续。

See

components.md

(Badge, Slider, Tabs, Steps, Swiper, Tooltip, Popover, Collapse, DatetimePickerView, ImgCropper, CountTo, Segmented, PickerView, camelCase property names). Return to Phase 6 after reading.

阶段六：样式与主题迁移

Phase 6: Migrate Styles & Themes

详见

styles.md

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

See

styles.md

(theme file import, global variable override, ConfigProvider, style override priority, dark mode). Proceed to Phase 7 regression verification after reading.

阶段七：回归验证

Phase 7: Regression Verification

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 返回值和按钮配置是否符合预期
深色模式、主题变量、品牌色覆盖是否生效
弹层在小程序端是否存在样式隔离问题
自定义覆盖样式是否仍然生效
图标名称是否仍然存在，按钮高度变化是否影响页面布局

Can it compile normally on H5 and target mini program platforms?
Can
```
easycom
```
correctly parse all
```
wd-*
```
components?
Have functional calls like
```
Toast
```
,
```
Dialog
```
,
```
Notify
```
been declared as instances in pages?
Are form submission, single-field validation, reset, hidden fields and asynchronous validation working normally?
Are the echo text and submission value of picker-type form items correct?
Do
```
Button
```
's
```
type
```
,
```
variant
```
,
```
round
```
and height meet expectations?
Has
```
Tag
```
's
```
variant
```
been migrated from
```
plain
```
?
Have
```
Radio
```
/
```
Checkbox
```
's
```
shape
```
,
```
inline
```
,
```
cell
```
been migrated?
Has
```
Search
```
's
```
light
```
been migrated to
```
variant="light"
```
?
Has
```
GridItem
```
's click event been migrated from
```
itemclick
```
to
```
click
```
?
Have form-related properties of
```
Cell
```
,
```
Input
```
,
```
Textarea
```
been migrated to
```
wd-form-item
```
?
Can instance methods like
```
PickerView
```
,
```
ImgCropper
```
,
```
CountTo
```
still be called normally?
Have old properties of
```
Badge
```
,
```
Slider
```
,
```
Tabs
```
,
```
Steps
```
,
```
Swiper
```
been migrated?
Does
```
Dialog
```
's mask click to close, Prompt return value and button configuration meet expectations?
Are dark mode, theme variables, and brand color override taking effect?
Are there style isolation issues with pop-ups on mini program platforms?
Do custom override styles still take effect?
Do icon names still exist, and does button height change affect page layout?