// Vant 3 .van-popup--center { left: 50%; transform: translate3d(-50%, -50%, 0); }
// Vant 4 .van-popup--center { left: 0; right: 0; width: fit-content; max-width: calc(100vw - var(--van-padding-md) * 2); margin: 0 auto; transform: translateY(-50%); }
**New Component**
- 新增 [Space 间距](./vant/index) 组件, 由 [@LadyChatterleyLover](https://github.com/LadyChatterleyLover) 贡献 ❤️ [#10857](https://github.com/vant-ui/vant/issues/10857)
**Feature**
- ConfigProvider: 新增 z-index 属性，用于设置弹窗组件的 z-index [#10915](https://github.com/vant-ui/vant/issues/10915)
- Form: 新增 rule 的 validateEmpty 选项 [#10913](https://github.com/vant-ui/vant/issues/10913)
- Popup: 新增 role 和 tabindex，优化无障碍访问 [#10894](https://github.com/vant-ui/vant/issues/10894)
- TouchEmulator: 支持 .mjs 后缀 [#10888](https://github.com/vant-ui/vant/issues/10888)
**Feature**
- ConfigProvider: 新增 theme-vars-dark 和 theme-vars-light 属性 [#10939](https://github.com/vant-ui/vant/issues/10939)
- Picker: 新增 clickOption 事件 [#10865](https://github.com/vant-ui/vant/issues/10865)
- 为 scroll 事件添加了正确的 passive 标记来提升滚动性能 [#10951](https://github.com/vant-ui/vant/issues/10951)
- @vant/use: 优化 useEventListener 类型定义 [#10952](https://github.com/vant-ui/vant/issues/10952)
**Bug Fixes**
- ConfigProvider: 修复销毁时没有回收全局样式类的问题 [#10898](https://github.com/vant-ui/vant/issues/10898)
- 修复 touchstart 导致控制台出现 passive event warning 的问题 [#10954](https://github.com/vant-ui/vant/issues/10954)
- Tabs: 修复开启 swipeable 时，resize 方法无法正确生效的问题 [#10964](https://github.com/vant-ui/vant/issues/10964)
- 修复在 WebStorm 下标签无法自动补全的问题 [#10946](https://github.com/vant-ui/vant/issues/10946)
- Badge: 修复使用 show-zero 时字符串 `'0'` 不生效的问题 [#10921](https://github.com/vant-ui/vant/issues/10921)
- Calendar: 修复关闭弹窗过程中内容白屏的问题 [#10910](https://github.com/vant-ui/vant/issues/10910)
- Calendar: 修复控制台出现读取 getFullYear 异常的问题 [#10909](https://github.com/vant-ui/vant/issues/10909)
- Empty: 修复在 Tab 下嵌套使用时渲染异常的问题 [#10943](https://github.com/vant-ui/vant/issues/10943)
- Popover: 修复在 Popup 下嵌套使用时无法滚动的问题 [#10949](https://github.com/vant-ui/vant/issues/10949)
- PullRefresh: 修复 Chrome 控制台出现 passive event warning 的问题 [#10938](https://github.com/vant-ui/vant/issues/10938)
- Search: 修复 --van-search-input-height 样式变量不生效的问题 [#10911](https://github.com/vant-ui/vant/issues/10911)
### [v4.0.0-beta.0](https://github.com/vant-ui/vant/compare/v3.5.2...v4.0.0-beta.0)
`2022-07-16`
**Breaking Changes**
- Toast: 重新设计函数调用 API [#10804](https://github.com/vant-ui/vant/issues/10804)
- Dialog: 重新设计函数调用 API [#10781](https://github.com/vant-ui/vant/issues/10781)
- Notify: 重新设计函数调用 API[#10782](https://github.com/vant-ui/vant/issues/10782)
- ImagePreview: 重新设计函数调用 API [#10802](https://github.com/vant-ui/vant/issues/10802)
关于以上改动的详细描述和迁移方法，请参考 [从 v3 升级到 v4](./vant/v4/index) 的 「API 调整」部分。
**Feature**
- 新增 @vant/compat 包，用于辅助代码迁移 [#10806](https://github.com/vant-ui/vant/issues/10806)
- Calendar: 新增 getSelectedDate 方法 [419a8e](https://github.com/vant-ui/vant/commit/419a8e4f0e6454b9aac30d5800318deabec099cb)
- 由于主题定制方式调整，发布到 npm 的代码中将不再包含 .less 样式源文件，从而减少 npm 包体积 [#10752](https://github.com/vant-ui/vant/issues/10752)
**Bug Fixes**
- Uploader: 修复预览图片时会展示上传失败的图片的问题 [#10790](https://github.com/vant-ui/vant/issues/10790)
### [v4.0.0-alpha.4](https://github.com/vant-ui/vant/compare/v3.5.0-beta.0...v4.0.0-alpha.4)
`2022-05-31`
**Feature**
- 适配 nuxt 3，现在 dist 目录下所有 esmodule 文件将使用 `.mjs` 文件后缀 [#10625](https://github.com/vant-ui/vant/issues/10625)
### [v4.0.0-alpha.3](https://github.com/vant-ui/vant/compare/v3.4.9...v4.0.0-alpha.3)
`2022-05-02`
**Feature**
- Form: 支持同时设置多个 validate-trigger 值 [#10544](https://github.com/vant-ui/vant/issues/10544)
- Empty: 支持在无网络的环境下离线使用，图片从 CDN 调整为内联的 SVG 图片 [#10514](https://github.com/vant-ui/vant/issues/10514) [#10515](https://github.com/vant-ui/vant/issues/10515) [#10516](https://github.com/vant-ui/vant/issues/10516)
- Loading: 优化无障碍访问 [#10568](https://github.com/vant-ui/vant/issues/10568)
**Bug Fixes**
- Search: 修复暗色模式下样式错误的问题 [#10527](https://github.com/vant-ui/vant/issues/10527)
- @vant/area-data: 修复发布到 npm 时包含 tsconfig.json 文件导致编译错误的问题 [f927f6](https://github.com/vant-ui/vant/commit/f927f6a7518cf7d08ec8abc5dd35019685c19e3a)
### [v4.0.0-alpha.2](https://github.com/vant-ui/vant/compare/v3.4.8...v4.0.0-alpha.2)
`2022-04-16`
**Feature**
- CalendarDay: 增加日期行间距 [#10441](https://github.com/vant-ui/vant/issues/10441)
- Empty: 支持单独设置 image 的宽高 [#10465](https://github.com/vant-ui/vant/issues/10465)
- Field: 新增 enterkeyhint 属性 [#10478](https://github.com/vant-ui/vant/issues/10478)
- Form: 新增 getValues 方法 [#10511](https://github.com/vant-ui/vant/issues/10511)
- Icon: 新增 qq、weibo 等图标 [#10468](https://github.com/vant-ui/vant/issues/10468)
- Locale: 新增丹麦语 [#10513](https://github.com/vant-ui/vant/issues/10513)
- ShareSheet: 不再依赖 CDN 上的图片资源，使用 iconfont 代替 [#10469](https://github.com/vant-ui/vant/issues/10469)
- web-types.json 文件增加 event arguments 信息 [#10474](https://github.com/vant-ui/vant/issues/10474)
**Bug Fixes**
- DatetimePicker: 修复 modeValue 与选中的数据不一致的问题 [#10448](https://github.com/vant-ui/vant/issues/10448)
- Rate: 修复多行时滑动选中不正确的问题 [#10500](https://github.com/vant-ui/vant/issues/10500)
### [v4.0.0-alpha.1](https://github.com/vant-ui/vant/compare/v3.4.6...v4.0.0-alpha.1)
`2022-03-19`
**Feature**
- @vant/area-data: 新增南京市江北新区 [#10410](https://github.com/vant-ui/vant/issues/10410)
- Locale: 新增老挝语 [#10388](https://github.com/vant-ui/vant/issues/10388)
**Bug Fixes**
- Calendar: 修复暗色模式下标题颜色 [#10403](https://github.com/vant-ui/vant/issues/10403)
- Picker: 修复暗色模式下标题颜色 [#10403](https://github.com/vant-ui/vant/issues/10403)
- ConfigProvider: 修复默认设置暗色模式不生效的问题 [#10413](https://github.com/vant-ui/vant/issues/10413)
- DatePicker: 修复更新 v-model 不生效的问题 [#10415](https://github.com/vant-ui/vant/issues/10415)
- Dialog: 修复暗色模式下标题和文本颜色 [#10379](https://github.com/vant-ui/vant/issues/10379)
- IndexBar: 修复底部索引无法高亮的问题 [#10404](https://github.com/vant-ui/vant/issues/10404)
### 4.0.0-alpha.0
`2022-02-21`
**不兼容更新**
参见 [从 v3 升级到 v4](./migrate-from-v3)。
**Feature**
- ConfigProvider: 新增 `theme` 属性，用于开启深色模式
- ConfigProvider: 新增 `ConfigProviderTheme` 类型
**Style**
在之前的版本中，Vant 组件有两种色彩风格，一部分采用红色作为主色调，另一部分采用蓝色。为了保持色彩规范的统一，我们在 Vant 4 中对组件的主色调进行了统一，所有组件均采用蓝色作为主色调。
以下组件的默认色值风格由红色调整为蓝色：
- AddressEdit
- AddressList
- Card
- Calendar
- Cascader
- ContactList
- ContactEdit
- CouponList
- Dialog
- DropdownMenu
- IndexBar
- Sidebar
- Steps
- Tabs
- TreeSelect
其他：
- `--van-font-bold` 的默认值由 `500` 调整为 `600`
- ActionBar: 调整 `--van-action-bar-icon-text-color` 变量的默认值为 `--van-text-color`
- AddressList: 重命名 `--van-address-list-item-radio-icon-color` 为 `--van-address-list-radio-color`
- Button: 默认圆角大小从 `2px` 调整为 `4px`
- Button: 默认按钮的边框颜色调整为 `--van-gray-4`
- Button: 调整 `font-smoothing`，默认使用粗体文字
- Cell: 只设置 `value` 时，内容不再会靠左对齐
- Card: 调整 `--van-card-background` 变量的默认值为 `--van-background`
- Card: 调整 `--van-card-price-color` 变量的默认值为 `--van-text-color`
- Card: 调整 `--van-card-desc-color` 变量的默认值为 `--van-text-color-2`
- ContactList: 重命名 `--van-contact-list-item-radio-icon-color` 为 `--van-contact-list-radio-color`
- CouponList: 重命名 `--van-coupon-corner-checkbox-icon-color` 为 `--van-coupon-checkbox-color`
- Field: 调整 `--van-field-label-color` 变量的默认值为 `--van-text-color`
- Switch: 移除 `--van-switch-border` 变量
---
## 📋 版本升级最佳实践
### 🎯 升级前的准备工作
在升级 Vant 版本之前，建议你做好以下准备：
1. **备份当前项目** 📦
```bash
# 创建项目备份
git add .
git commit -m "backup before vant upgrade"查看破坏性变更 ⚠️
- 仔细阅读目标版本的更新日志
- 特别关注标有 "BREAKING CHANGE" 的内容
- 检查是否有组件 API 变更
测试环境验证 🧪
- 先在测试环境进行升级
- 运行完整的测试套件
- 检查关键功能是否正常
🚀 平滑升级策略
渐进式升级
bash
# 推荐：逐个小版本升级
npm update @vant/weapp@4.8.0 # 先升级到中间版本
npm update @vant/weapp@4.9.0 # 再升级到目标版本一步到位升级
bash
# 直接升级到最新版本（需要更多测试）
npm update @vant/weapp@latest🔍 常见升级问题解决
样式问题
- 检查 CSS 变量是否有变更
- 确认主题定制是否需要调整
- 验证响应式布局是否正常
功能问题
- 查看组件 API 是否有变更
- 检查事件回调参数是否有调整
- 确认新增的必需属性
性能问题
- 利用新版本的性能优化特性
- 移除已废弃的功能和属性
- 更新构建配置以获得最佳性能
🤝 参与贡献
成为 Vant 贡献者
看到这么多优秀的贡献者为 Vant 添砖加瓦，你是否也想加入我们？
🌟 贡献方式
- 代码贡献：修复 bug、添加新功能、优化性能
- 文档完善：改进文档、添加示例、翻译内容
- 问题反馈：报告 bug、提出改进建议
- 社区支持：帮助其他开发者解决问题
📝 贡献流程
- Fork 项目到你的 GitHub
- 创建功能分支：
git checkout -b feature/amazing-feature - 提交你的改动：
git commit -m 'Add amazing feature' - 推送到分支：
git push origin feature/amazing-feature - 提交 Pull Request
🔗 相关资源
官方资源
社区资源
学习资源
💡 小贴士：定期关注 Vant 的更新日志，不仅能让你及时了解新功能，还能学习到优秀的开源项目是如何演进的。每一个版本背后都有无数开发者的智慧结晶，值得我们学习和借鉴！
- Switch: 调整
--van-switch-size变量的默认值为26px - Switch: 调整
--van-switch-background变量的默认值为rgba(120, 120, 128, 0.16) - Tabbar: 调整
--van-tabbar-item-text-color变量的默认值为--van-text-color - GridItem: 调整
--van-grid-item-text-color变量的默认值为--van-text-color
v4.0.10
2023-02-02
Bug Fixes
v4.0.9
2023-01-26
Feature
- BackTop: 新增 immediate 屬性 #11515
- Calendar: 新增 month-title 插槽 #11500
- Cascader: 新增 useCascaderAreaData 方法 #11518
- ImagePreview: 支援在縮放圖片後滑動至其他圖片 #11505
- Locale: 新增 Esperanto 世界語 #11520
- Locale: 新增 useCurrentLang 方法 #11517
- Swipe: 新增 drag-start, drag-end 事件 #11502
Bug Fixes
v4.0.8
2023-01-15
Feature
- PickerGroup: 新增 next-step-text 屬性 #11487
Bug Fixes
- Picker: 調整確認按鈕的顏色為 primary color #11479
- NumberKeyboard: 調整確認按鈕的顏色為 primary color #11479
- Icons: 增加 woff 格式來相容個別 webview 環境 #11485
- Picker: 修復標題文字可能不居中的問題 #11489
- Skeleton: 修復全量引入組件時不會自動註冊 Skeleton 子組件的問題 #11470 #11469
- Tabs: 修復動態插入 Tab 時在個別情況下順序錯誤的問題 #11462
v4.0.7
2023-01-02
Bug Fixes
- Icons: 修復 delete / delete-o 圖標存在多餘黑點的問題 #11441
- Icons: 移除多餘的 woff/ttf 格式宣告 #11442
- ImagePreview：修復 teleport 屬性不生效的問題 #11429
- Locale: 修復 ru-RU 中的 "Calendar" 拼寫錯誤 #11425
- Swipe: 修復在 keep-alive 內使用時可能渲染空白的問題 #11437
v4.0.6
2022-12-26
Bug Fixes
- 修復升級 vite v4 導致建置產物不全的問題 #11423
v4.0.5
2022-12-25
Feature
Bug Fixes
- Badge: 修復 offset 屬性部分情況下導致樣式錯誤的問題 #11400
- Form: 修復事件參數中可能出現 key 為 undefined 的問題 #11410
- Picker: 修復深色模式下載入狀態樣式錯誤的問題 #11405
v4.0.4
2022-12-23
Bug Fixes
v4.0.3
2022-12-13
Bug Fixes
v4.0.2
2022-12-03
Bug Fixes
- Field: 修復使用 formatter 時游標位置錯誤的問題 #11348
- Image: 修復在 Nuxt 3 下圖片可能無法展示的問題 128972
- NavBar: 修復螢幕旋轉時 placeholder 未自動適配高度的問題 #11351
v4.0.1
2022-12-01
Feature
- Picker: 新增 selectedIndexes 作為事件入參 #11329
Bug Fixes
- Field: 修復未選中時修改綑続的值會導致鍵盤彈出的問題 #11333
v4.0.0
2022-11-26
完整內容請移步：「4.0 更新介紹」
Feature
- List: 新增 disabled 屬性 #11307
- BackTop: 支援動態設定 target 屬性 #11311
- BackTop: 支援透過 CSS 變數修改組件位置 #11312
- BackTop: 重新命名 visibility-height 屬性為 offset #11309
Bug Fixes
- Field: 修復格式化值後，游標位置錯誤的問題 #11308
v4.0.0-rc.9
2022-11-24
Bug Fixes
v4.0.0-rc.8
2022-11-20
Feature
- 新增 BackTop 回到頂部組件，注意該新組件的 API 尚未穩定，在 4.0 正式版發佈前仍可能產生 breaking change #11236
Bug Fixes
- DropdownItem: 修復使用 teleport 時無法設定 attr 的問題 #11273
- List: 修復初始的 loading 值為 true 時載入錯誤的問題 #11275
- NumberKeyboard: 修復使用 teleport 時無法設定 attr 的問題 #11274
v4.0.0-rc.7
2022-11-13
New Component
- 新增 SkeletonAvatar、SkeletonTitle、SkeletonImage、SkeletonParagraph 組件 #11173
Feature
Bug Fixes
- ActionSheet: 修復標題為空時取消按鈕層級錯誤的問題 #11213
- DatePicker: 在生產環境下不再拋出開發錯誤提示 #11248
- Lazyload: 修復使用 lazy-image 時報錯 h is not a function 的問題 #11229
- Picker: 修復拋出 confirm 事件時 v-model 未正確更新的問題 #11194
- Picker: 修復 column 為空時操作報錯的問題 #11249
- Uploader: 修復 show-upload 為 false 時 chooseFile 無法呼叫的問題 #11218
v4.0.0-rc.6
2022-10-23
Feature
- Calendar: subtitle 插槽新增 text 和 date 入參 #11168
- Cell: 新增 tag 屬性 #11139
- ImagePreview: 新增 image 插槽 #11133
- Toast: 新增 wordBreak 選項 #11147
Bug Fixes
- CouponList: 修復 coupon 位置錯誤的問題 #11153
- CouponList: 修復輸入框樣式錯誤的問題 #11155
- Swipe: 修復在 Popup 內時個別情況下渲染錯誤的問題 #11162
v4.0.0-rc.5
2022-10-07
Feature
- Field: 支援將 label-position 設定為 top #11102
- Loading: 新增 icon 插槽 #11109
- NavBar: 新增 clickable 屬性 #11048
- Stepper: 新增 auto-fixed 屬性 #11071
Bug Fixes
- DatePicker: 修復日期超出 maxDate 時格式化不正確的問題 #11122
- Tabs: 修復開啟 scrollspy 時個別情況下標題欄滾動位置錯誤的問題 #11116
- Tabs: 修復開啟 scrollspy 時 nav-bottom 插槽遮擋內容的問題 #11115
v4.0.0-rc.4
2022-09-25
Feature
- Field: end-validate 事件新增 message 參數 #11080
Bug Fixes
v4.0.0-rc.3
2022-09-12
Feature
- ConfigProvider: 新增 ConfigProviderThemeVars 類型 #11034
- Notify: 新增 z-index 屬性 #11032
- 移除
@popperjs/core依賴，減少安裝體積 1.6MB #11030
Types
- Toast: 修復缺少全域類型定義的問題 #11033
v4.0.0-rc.2
2022-09-11
Breaking Changes
- 調整了所有 CSS 變數的掛載位置，由
body節點調整回:root節點，調整後與 Vant v3 版本保持一致，以便於 v3 專案更平滑地升級到 v4 版本。 #11026
Bug Fixes
v4.0.0-rc.1
2022-09-10
Feature
- 匯出所有組件的 props，方便進行二次封裝 #11024
- Dialog: message-align 屬性支援設定為 justify #11014
- Image: 新增 block 屬性 #11022
- Toast: 新增 message 插槽 #11018
Bug Fixes
v4.0.0-rc.0
2022-09-04
Feature
- 新增 PickerGroup 選擇器組 組件
Bug Fixes
v4.0.0-beta.1
2022-08-24
Breaking Changes
- Popup: 預設添加了
box-sizing: border-box樣式。 - Popup: 調整了
position="center"時的水平居中方式，以解決彈窗寬度無法正確自適應的問題。
less
// Vant 3
.van-popup--center {
left: 50%;
transform: translateX(-50%);
}
// Vant 4
.van-popup--center {
left: 0;
right: 0;
width: fit-content;
max-width: calc(100vw - var(--van-popup-round-border-radius) * 2);
margin: 0 auto;
}Feature
- 新增 Space 間距 組件
- 新增深色模式，所有組件都支援深色模式
- 新增 ConfigProvider 全域配置 組件，用於配置 Vant 組件的主題等全域屬性
- 新增 4 個新圖標：
guide-o、check-circle-o、circle、warning - ActionSheet: 新增
description屬性 - BackTop: 新增
right、bottom屬性 - Badge: 新增
offset屬性 - Button: 新增
icon-prefix屬性 - Calendar: 新增
prev-month、prev-year、next-month、next-year事件 - Calendar: 新增
getSelectedDate方法 - CascaderOption: 新增
className屬性 - ContactCard: 新增
editable屬性 - ContactList: 新增
default-tag-text屬性 - DatePicker: 新增
columns-order屬性 - DropdownMenu: 新增
close-on-click-outside屬性 - Empty: 新增
image-size屬性 - Form: 新增
disabled屬性 - Form: 新增
readonly屬性 - Icon: 新增
badge屬性 - Icon: 新增
dot屬性 - Image: 新增
error-icon屬性 - Image: 新增
loading-icon屬性 - IndexBar: 新增
scrollTo方法 - List: 新增
error-text屬性 - List: 新增
error插槽 - NavBar: 新增
placeholder屬性 - NoticeBar: 新增
left-icon插槽 - NoticeBar: 新增
right-icon插槽 - Notify: 新增
close-on-click-overlay屬性 - PasswordInput: 新增
focused屬性 - Picker: 新增
columns-field-names屬性 - Popup: 新增
close-on-popstate屬性 - Progress: 新增
track-color屬性 - Rate: 新增
readonly屬性 - Search: 新增
error-message屬性 - Search: 新增
formatter屬性 - Search: 新增
format-trigger屬性 - Search: 新增
clear-icon屬性 - Search: 新增
clear-trigger屬性 - Search: 新增
error屬性 - Search: 新增
error-message-align屬性 - Slider: 新增
readonly屬性 - Stepper: 新增
theme屬性 - Steps: 新增
finish-icon插槽 - Steps: 新增
active-icon插槽 - Steps: 新增
inactive-icon插槽 - SubmitBar: 新增
placeholder屬性 - Swipe: 新增
indicator插槽 - Switch: 新增
before-change屬性 - Tabbar: 新增
placeholder屬性 - Tag: 新增
show屬性 - TimePicker: 新增
columns-order屬性 - TreeSelect: 新增
dot屬性 - TreeSelect: 新增
badge屬性 - Uploader: 新增
readonly屬性
Bug Fixes
- ActionSheet: 修復
close-icon屬性不生效的問題 - Calendar: 修復
default-date屬性可能不生效的問題 - Calendar: 修復範圍選擇模式下選擇同一天時狀態錯誤的問題
- Cascader: 修復
field-names屬性不生效的問題 - ContactEdit: 修復
is-edit屬性不生效的問題 - DatePicker: 修復
min-date和max-date屬性不生效的問題 - DropdownMenu: 修復
close-on-click-overlay屬性預設值錯誤的問題 - Field: 修復
center屬性不生效的問題 - Form: 修復
validate方法可能返回錯誤的 Promise 狀態的問題 - IndexBar: 修復
sticky-offset-top屬性不生效的問題 - Locale: 修復
moment.js的國際化配置不生效的問題 - NavBar: 修復
z-index屬性不生效的問題 - NoticeBar: 修復
reset方法不生效的問題 - Picker: 修復
allow-html屬性不生效的問題 - Popup: 修復
close-on-popstate屬性不生效的問題 - Rate: 修復
touchable屬性不生效的問題 - Search: 修復
id屬性不生效的問題 - Slider: 修復
button插槽不生效的問題 - Steps: 修復
inactive-color屬性不生效的問題 - Sticky: 修復
z-index屬性不生效的問題 - SubmitBar: 修復
safe-area-inset-bottom屬性不生效的問題 - Swipe: 修復
stop-propagation屬性不生效的問題 - Switch: 修復
active-color和inactive-color屬性不生效的問題 - Tabbar: 修復
safe-area-inset-bottom屬性不生效的問題 - Tabs: 修復
line-height屬性不生效的問題 - TreeSelect: 修復
height屬性不生效的問題
// ... existing code ...