閱讀(2k) 書(shū)簽贊(0) 我要糾錯(cuò)

Vant4 從 v3 升級(jí)到 v4

2023-02-16 17:54 更新

介紹

本文檔提供了從 Vant 3 到 Vant 4 的升級(jí)指南。

安裝 Vant 4

首先你需要安裝 Vant 4 以及 ?@vant/compat?。

?@vant/compat? 是一個(gè)兼容包，可以幫助你從 Vant 3 過(guò)渡到 Vant 4。

# 通過(guò) npm 安裝
npm add vant@^4 @vant/compat@^1

# 通過(guò) yarn 安裝
yarn add vant@^4 @vant/compat@^1

# 通過(guò) pnpm 安裝
pnpm add vant@^4 @vant/compat@^1

你也可以直接修改 ?package.json? 的 ?dependencies? 字段中的版本號(hào)，修改完成后需要重新安裝依賴。

{
  "dependencies": {
-    "vant": "^3.0.0",
+    "vant": "^4.0.0",
+    "@vant/compat": "^1.0.0",
  }
}

調(diào)整按需引入方式

移除 babel-plugin-import

從 Vant 4.0 開(kāi)始，將不再支持 ?babel-plugin-import?，請(qǐng)移除項(xiàng)目中依賴的 ?babel-plugin-import? 插件。

只需要?jiǎng)h除 ?babel.config.js? 中的以下代碼即可：

module.exports = {
  plugins: [
-    ['import', {
-      libraryName: 'vant',
-      libraryDirectory: 'es',
-      style: true
-    }, 'vant']
  ]
};

收益

移除 ?babel-plugin-import? 主要帶來(lái)以下收益：

不再?gòu)?qiáng)依賴 Babel 編譯，項(xiàng)目可以使用 SWC、esbuild 等現(xiàn)代編譯工具，進(jìn)而提升編譯效率。
不再受到 ?babel-plugin-import? 的 import 限制，可以從 Vant 中導(dǎo)入除組件以外的內(nèi)容，比如 Vant 4 中新增的 ?showToast? 方法，或是 ?buttonProps? 對(duì)象：

import { showToast, buttonProps } from 'vant';

樣式引入方案

移除 ?babel-plugin-import? 對(duì)項(xiàng)目的 JS 體積不會(huì)有影響，因?yàn)?Vant 默認(rèn)支持通過(guò) Tree Shaking 來(lái)移除不需要的 JS 代碼。

而 CSS 代碼的引入方式可以從以下兩種方式中進(jìn)行選擇：

在項(xiàng)目中全量引入 Vant 的樣式文件：

import 'vant/lib/index.css';

通過(guò) unplugin-vue-components 插件實(shí)現(xiàn)按需引入樣式，詳細(xì)用法參見(jiàn) 快速上手。

組件重構(gòu)

介紹

在 Vant 4 中，一共有三個(gè)組件被完全重構(gòu)，它們是：

?Area?
?Picker?
?DatetimePicker?

這三個(gè)組件之所以被重構(gòu)，是因?yàn)樵谥暗陌姹局校?Picker? 組件的 API 設(shè)計(jì)存在一些不合理的設(shè)計(jì)，導(dǎo)致大家在使用時(shí)經(jīng)常遇到問(wèn)題，比如：

Picker columns 數(shù)據(jù)格式定義不合理，容易產(chǎn)生誤解
Picker 數(shù)據(jù)流不清晰，暴露了過(guò)多的實(shí)例方法來(lái)對(duì)數(shù)據(jù)進(jìn)行操作
DatetimePicker 邏輯過(guò)于復(fù)雜，經(jīng)常在邊界場(chǎng)景下出現(xiàn) bug

為了解決上述問(wèn)題，我們?cè)?v4 版本中對(duì) ?Picker? 組件進(jìn)行了重構(gòu)，同時(shí)也重構(gòu)了基于 ?Picker? 派生出的 ?Area? 和 ?DatetimePicker? 組件。如果你的項(xiàng)目中使用了這三個(gè)組件，請(qǐng)仔細(xì)閱讀文檔并進(jìn)行升級(jí)。

Picker 組件重構(gòu)

主要變更

支持通過(guò) ?v-model? 綁定當(dāng)前選中的值，移除 ?default-index? 屬性
重新定義了 ?columns? 屬性的結(jié)構(gòu)
移除了操作內(nèi)部數(shù)據(jù)的實(shí)例方法，僅保留 ?confirm? 方法
新增 ?getSelectedOptions? 實(shí)例方法
調(diào)整了 ?confirm?、?cancel?、?change? 事件的參數(shù)
重命名 ?item-height? 屬性為 ?option-height?
重命名 ?visible-item-count? 屬性為 ?visible-option-num?

詳細(xì)用法請(qǐng)參見(jiàn) Picker 組件文檔。

DatetimePicker 組件重構(gòu)

DatetimePicker 組件被拆分為三個(gè)子組件：

TimePicker: 用于時(shí)間選擇，包括時(shí)、分、秒。
DatePicker: 用于日期選擇，包括年、月、日。
PickerGroup: 用于結(jié)合多個(gè) Picker 選擇器組件，在一次交互中完成多個(gè)值的選擇。

同時(shí)，TimePicker 和 DatePicker 組件也基于新版 Picker 組件進(jìn)行重構(gòu)，并優(yōu)化了部分 API 設(shè)計(jì)。

主要變更

以下是 TimePicker 和 DatePicker 的主要 API 變化，更多細(xì)節(jié)請(qǐng)參考 TimePicker 和 DatePicker 文檔。

?v-model? 綁定的值調(diào)整為數(shù)組格式
新增 ?columns-type? 屬性，用于控制選項(xiàng)類型和順序
移除 ?type? 屬性和 ?columns-order? 屬性
移除 ?getPicker? 方法
調(diào)整 ?confirm?、?cancel?、?change? 事件的參數(shù)，與 Picker 組件保持一致

Vant 4 不再提供舊版的 DatetimePicker 組件，使用 PickerGroup 組件可以實(shí)現(xiàn)更靈活、更豐富的交互效果，具體用法請(qǐng)參考 PickerGroup 組件文檔。

Area 組件重構(gòu)

Area 組件是基于 Picker 組件進(jìn)行封裝的，因此本次升級(jí)也對(duì) Area 組件進(jìn)行了內(nèi)部邏輯的重構(gòu)，并優(yōu)化了部分 API。

主要變更

支持通過(guò) ?v-model? 綁定當(dāng)前選中的值
移除 ?reset? 方法，現(xiàn)在可以通過(guò)修改 ?v-model? 來(lái)進(jìn)行重置
移除 ?is-oversea-code? 屬性
調(diào)整 ?confirm?、?cancel?、?change? 事件的參數(shù)，與 Picker 組件保持一致
重命名 ?value? 屬性為 ?modelValue?
重命名 ?item-height? 屬性為 ?option-height?
重命名 ?visible-item-count? 屬性為 ?visible-option-num?

詳細(xì)用法請(qǐng)參見(jiàn) Area 組件文檔。

API 調(diào)整

Dialog 調(diào)用方式調(diào)整

在 Vant 3 中，?Dialog? 是一個(gè)函數(shù)，調(diào)用函數(shù)可以快速喚起全局的彈窗組件，而 ?Dialog.Component? 才是 ?Dialog? 組件對(duì)象，這與大部分組件的用法存在差異，容易導(dǎo)致使用錯(cuò)誤。

為了更符合直覺(jué)，我們?cè)?Vant 4 中調(diào)整了 ?Dialog? 的調(diào)用方式，將 ?Dialog()? 函數(shù)重命名為 ?showDialog()?，并讓 ?Dialog? 直接指向組件對(duì)象。

// Vant 3
Dialog(); // 函數(shù)調(diào)用
Dialog.Component; // 組件對(duì)象

// Vant 4
showDialog(); // 函數(shù)調(diào)用
Dialog; // 組件對(duì)象

由于 ?Dialog? 變?yōu)榱私M件對(duì)象，?Dialog? 上掛載的其他方法也進(jìn)行了重命名，新舊 API 的映射關(guān)系如下：

Dialog(); // -> showDialog()
Dialog.alert(); // -> showDialog()
Dialog.confirm(); // -> showConfirmDialog()
Dialog.close(); // -> closeDialog();
Dialog.setDefaultOptions(); // -> setDialogDefaultOptions()
Dialog.resetDefaultOptions(); // -> resetDialogDefaultOptions()

兼容方案

為了便于舊版本代碼遷移至 v4，我們提供了兼容方案，你可以使用 ?@vant/compat? 中導(dǎo)出的 ?Dialog? 對(duì)象來(lái)兼容原有代碼。

從 ?@vant/compat? 中引用 ?Dialog? 方法：

import { Dialog } from '@vant/compat';

Dialog();
Dialog.close();

?@vant/compat? 中導(dǎo)出的 ?Dialog? 與 Vant 3 中的 ?Dialog? 擁有完全一致的 API 和行為，因此你只需要修改 ?Dialog? 的引用路徑，其他代碼可以保持不變。

在項(xiàng)目完成升級(jí)到 Vant v4 后，建議在迭代中逐步替換為新的 ?showDialog? 等方法，并移除 ?@vant/compat? 包。

Toast 調(diào)用方式調(diào)整

Vant 4 中，?Toast? 組件的調(diào)用方式也進(jìn)行了調(diào)整，與 ?Dialog? 組件的改動(dòng)一致：

// Vant 3
Toast(); // 函數(shù)調(diào)用

// Vant 4
showToast(); // 函數(shù)調(diào)用
Toast; // 組件對(duì)象

?Toast? 上掛載的其他方法也進(jìn)行了重命名，新舊 API 的映射關(guān)系如下：

Toast(); // -> showToast()
Toast.fail(); // -> showFailToast()
Toast.success(); // -> showSuccessToast()
Toast.loading(); // -> showLoadingToast()
Toast.clear(); // -> closeToast()
Toast.setDefaultOptions(); // -> setToastDefaultOptions()
Toast.resetDefaultOptions(); // -> resetToastDefaultOptions()

同時(shí)，Vant 4 將不再在 ?this? 對(duì)象上全局注冊(cè) ?$toast? 方法，這意味著 ?this? 對(duì)象上將無(wú)法訪問(wèn)到 ?$toast?。

兼容方案

為了便于代碼遷移，我們提供了兼容方案，你可以使用 ?@vant/compat? 中導(dǎo)出的 ?Toast? 對(duì)象來(lái)兼容原有代碼。

import { Toast } from '@vant/compat';

Toast();
Toast.clear();

?@vant/compat? 中導(dǎo)出的 ?Toast? 與 Vant 3 中的 ?Toast? 擁有完全一致的 API 和行為，因此你只需要修改 ?Toast? 的引用路徑，其他代碼可以保持不變。

Notify 調(diào)用方式調(diào)整

Vant 4 中，?Notify? 組件的調(diào)用方式也進(jìn)行了調(diào)整，與 ?Dialog? 組件的改動(dòng)一致：

// Vant 3
Notify(); // 函數(shù)調(diào)用
Notify.Component; // 組件對(duì)象

// Vant 4
showNotify(); // 函數(shù)調(diào)用
Notify; // 組件對(duì)象

?Notify? 上掛載的其他方法也進(jìn)行了重命名，新舊 API 的映射關(guān)系如下：

Notify(); // -> showNotify()
Notify.clear(); // -> closeNotify()
Notify.setDefaultOptions(); // -> setNotifyDefaultOptions()
Notify.resetDefaultOptions(); // -> resetNotifyDefaultOptions()

同時(shí)，Vant 4 將不再在 ?this? 對(duì)象上全局注冊(cè) ?$notify? 方法，這意味著 ?this? 對(duì)象上將無(wú)法訪問(wèn)到 ?$notify?。

兼容方案

為了便于代碼遷移，我們提供了兼容方案，你可以使用 ?@vant/compat? 中導(dǎo)出的 ?Notify? 對(duì)象來(lái)兼容原有代碼。

import { Notify } from '@vant/compat';

Notify();
Notify.clear();

?@vant/compat? 中導(dǎo)出的 ?Notify? 與 Vant 3 中的 ?Notify? 擁有完全一致的 API 和行為，因此你只需要修改 ?Notify? 的引用路徑，其他代碼可以保持不變。

ImagePreview 調(diào)用方式調(diào)整

Vant 4 中，ImagePreview 組件的調(diào)用方式也進(jìn)行了調(diào)整，與 ?ImagePreview? 組件的改動(dòng)一致：

// Vant 3
ImagePreview(); // 函數(shù)調(diào)用
ImagePreview.Component; // 組件對(duì)象

// Vant 4
showImagePreview(); // 函數(shù)調(diào)用
ImagePreview; // 組件對(duì)象

兼容方案

為了便于代碼遷移，我們提供了兼容方案，你可以使用 ?@vant/compat? 中導(dǎo)出的 ?ImagePreview? 對(duì)象來(lái)兼容原有代碼。

import { ImagePreview } from '@vant/compat';

ImagePreview();

?@vant/compat? 中導(dǎo)出的 ?ImagePreview? 與 Vant 3 中的 ?ImagePreview? 擁有完全一致的 API 和行為，因此你只需要修改 ?ImagePreview? 的引用路徑，其他代碼可以保持不變。

事件命名調(diào)整

從 Vant 4 開(kāi)始，所有的事件均采用 Vue 官方推薦的駝峰格式進(jìn)行命名。

// Vant 3
emit('click-input');

// Vant 4
emit('clickInput');

這項(xiàng)改動(dòng)不影響原有的模板代碼，Vue 會(huì)自動(dòng)在模板中對(duì)事件名進(jìn)行格式轉(zhuǎn)換，因此你無(wú)須做任何更改。

<!-- 以下代碼可以照常運(yùn)行，無(wú)須做任何更改 -->
<van-field @click-input="onClick" />

如果你在 JSX 中使用 Vant 組件，需要將監(jiān)聽(tīng)的事件名調(diào)整為駝峰格式，原有的中劃線格式將不再生效，新的監(jiān)聽(tīng)方式更加符合 JSX 本身的規(guī)范：

// Vant 3
<Field onClick-input={onClick} />

// Vant 4
<Field onClickInput={onClick} />

其他 API 調(diào)整

在 Vant 4.0 版本中，以下 API 進(jìn)行了不兼容更新：

AddressEdit

移除 ?show-postal? 屬性
移除 ?postal-validator? 屬性
?change-area? 事件的參數(shù)調(diào)整為 ?PickerOption[]? 類型
移除未在文檔中標(biāo)注的 ?getArea? 實(shí)例方法

Popup

Popup 的 CSS 樣式進(jìn)行了一定調(diào)整，如果你在 Popup 組件上添加了一些自定義的 CSS 樣式，請(qǐng)確認(rèn)本次升級(jí)是否對(duì)項(xiàng)目中的 UI 產(chǎn)生影響。

默認(rèn)添加了 ?box-sizing: border-box? 樣式
調(diào)整了 ?position="center"? 時(shí)的水平居中方式，以解決彈窗寬度無(wú)法正確自適應(yīng)的問(wèn)題：

// 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%);
}

Tabs

移除了 ?click? 和 ?disabled? 事件，請(qǐng)使用 ?click-tab? 事件代替

樣式調(diào)整

主色調(diào)統(tǒng)一

在之前的版本中，Vant 組件有兩種主色調(diào)，部分組件采用藍(lán)色（#1989fa）作為主色調(diào)，另一部分則采用紅色（#ee0a24）。

為了保持色彩規(guī)范的一致性，我們?cè)?Vant 4 中對(duì)主色調(diào)進(jìn)行統(tǒng)一，所有組件均采用藍(lán)色作為主色調(diào)。

以下組件的主色調(diào)由紅色調(diào)整為藍(lán)色：

AddressEdit
AddressList
Card
Calendar
Cascader
ContactList
ContactEdit
CouponList
Dialog
DropdownMenu
IndexBar
Sidebar
Steps
Tabs
TreeSelect

移除 Less 變量

目前 Vant 已經(jīng)支持了基于 CSS 變量的主題定制能力，相較于 Less 定制更加靈活。因此，Vant 4 將不再提供基于 Less 的主題定制方式。

這意味著 Vant 的 npm 包中將不再會(huì)包含 ?.less? 樣式源文件，只會(huì)提供編譯后的 ?.css? 樣式文件。

如果你的項(xiàng)目正在使用舊版的 Less 主題定制，請(qǐng)使用 ConfigProvider 全局配置組件進(jìn)行替換。

簡(jiǎn)化 CSS 變量名

考慮到 代碼體積 和 使用便捷性，我們對(duì)部分 CSS 變量的名稱進(jìn)行了簡(jiǎn)化，在變量名中使用了更簡(jiǎn)短的單詞，以減小代碼體積。

本次升級(jí)涉及以下變量名變更：

animation-duration               ->  duration
animation-timing-function-enter  ->  ease-out
animation-timing-function-leave  ->  ease-in
background-color                 ->  background
background-color-light           ->  background-2
border-radius                    ->  radius
border-width-base                ->  border-width
box-shadow                       ->  shadow
font-family                      ->  font
font-weight-bold                 ->  font-bold
price-integer-font               ->  price-font
text-link                        ->  link
transition-duration              ->  duration

由于涉及的 CSS 變量較多，建議在代碼倉(cāng)庫(kù)中進(jìn)行全局匹配和替換。

對(duì)于 ?ConfigProvider? 組件，我們新增了 ?ConfigProviderThemeVars? 類型定義，提供完整的類型提示。在 TypeScript 代碼中，你可以通過(guò)類型提示來(lái)確保主題變量被正確替換。

import type { ConfigProviderThemeVars } from 'vant';

const themeVars: ConfigProviderThemeVars = {
  sliderBarHeight: '4px',
};

以上內(nèi)容是否對(duì)您有幫助：

← Vant4 從 v2 升級(jí)到 v3

Vant4 貢獻(xiàn)指南 →

寫(xiě)筆記

我要補(bǔ)充