Area 省市區選擇 - Vant 4
Area 省市區選擇
🗺️ 介紹
省市區選擇組件提供了優雅的三級聯動選擇體驗！它能幫助使用者快速準確地選擇地理位置，通常與彈出層組件配合使用，為地址選擇提供流暢的互動體驗。
📦 引入
透過以下方式來全域註冊組件，更多註冊方式請參考組件註冊。
import { createApp } from'vue'; import { Area } from'vant'; const app = createApp(); app.use(Area);🎯 程式碼演示
基礎用法
初始化省市區組件時，需要透過 area-list 屬性傳入省市區資料。簡單配置，即可擁有完整的地區選擇功能！
areaList 格式
areaList 為物件結構，包含 province_list、city_list、county_list 三個 key。
每項以地區碼作為 key，省市區名字作為 value。地區碼為 6 位數字，前兩位代表省份，中間兩位代表城市，後兩位代表區縣，以 0 補足 6 位。比如北京的地區碼為 11，以 0 補足 6 位，為 110000。
範例資料如下：
const areaList = { province_list: { 110000: '北京市', 120000: '天津市', }, city_list: { 110100: '北京市', 120100: '天津市', }, county_list: { 110101: '東城區', 110102: '西城區', // .... }, };中國省市區資料
Vant 提供了一份中國省市區資料，你可以安裝 @vant/area-data npm 包來引入：
# 透過 npm npm i @vant/area-data # 透過 yarn yarn add @vant/area-data # 透過 pnpm pnpm add @vant/area-data # 透過 Bun bun add @vant/area-dataimport { areaList } from'@vant/area-data'; exportdefault { setup() { return { areaList }; }, };Tips: 中國的行政區劃每年都會有變動，如果發現省市區資料未及時更新，歡迎提 Pull Request 幫助我們更新。你可以在「國家統計局 - 全國區劃代碼」 和「民政部 - 行政區劃代碼」上查詢到最新資料，請根據官方資料進行核實。
控制選中項
透過 v-model 綁定目前選中的地區碼。
import { ref } from'vue'; exportdefault { setup() { const value = ref('330302'); return { value }; }, };配置顯示列
可以透過 columns-num 屬性配置省市區顯示的列數，預設情況下會顯示省市區，當你設定為 2，則只會顯示省市選擇。
配置列佔位提示文字
可以透過 columns-placeholder 屬性配置每一列的佔位提示文字。
API
Props
| 參數 | 說明 | 類型 | 預設值 |
|---|---|---|---|
| v-model | 目前選中項對應的地區碼 | string | - |
| title | 頂部欄標題 | string | - |
| confirm-button-text | 確認按鈕文字 | string | 確認 |
| cancel-button-text | 取消按鈕文字 | string | 取消 |
| area-list | 省市區資料，格式見下方 | object | - |
| columns-placeholder | 列佔位提示文字 | string[] | [] |
| loading | 是否顯示載入狀態 | boolean | false |
| readonly | 是否為唯讀狀態，唯讀狀態下無法切換選項 | boolean | false |
| option-height | 選項高度，支援 px``vw``vh``rem 單位，預設 px | *number | string* |
| columns-num | 顯示列數，3-省市區，2-省市，1-省 | *number | string* |
| visible-option-num | 可見的選項個數 | *number | string* |
| swipe-duration | 快速滑動時慣性滾動的時長，單位 ms | *number | string* |
Events
| 事件名 | 說明 | 回調參數 |
|---|---|---|
| confirm | 點擊完成按鈕時觸發 | { selectedValues, selectedOptions, selectedIndexes } |
| cancel | 點擊取消按鈕時觸發 | { selectedValues, selectedOptions, selectedIndexes } |
| change | 選項改變時觸發 | { selectedValues, selectedOptions, selectedIndexes, columnIndex } |
Slots
| 名稱 | 說明 | 參數 |
|---|---|---|
| toolbar | 自訂整個頂部欄的內容 | - |
| title | 自訂標題內容 | - |
| confirm | 自訂確認按鈕內容 | - |
| cancel | 自訂取消按鈕內容 | - |
| columns-top | 自訂選項上方內容 | - |
| columns-bottom | 自訂選項下方內容 | - |
方法
透過 ref 可以獲取到 Area 實例並呼叫實例方法，詳見組件實例方法。
| 方法名 | 說明 | 參數 | 回傳值 |
|---|---|---|---|
| confirm | 停止慣性滾動並觸發 confirm 事件 | - | - |
| getSelectedOptions | 獲取目前選中的選項 | - | PickerOption[] |
類型定義
組件匯出以下類型定義：
importtype { AreaProps, AreaList, AreaInstance } from'vant';AreaInstance 是組件實例的類型，用法如下：
import { ref } from'vue'; importtype { AreaInstance } from'vant'; const areaRef = ref<AreaInstance>(); areaRef.value?.confirm();常見問題
在桌面端無法操作組件？
參見桌面端適配。
📝 總結
Area 省市區選擇組件為地址選擇提供了完美的解決方案！🗺️ 透過三級聯動的優雅互動，使用者可以快速準確地選擇所需的地理位置。無論是電商應用的收貨地址選擇，還是其他需要地區資訊的場景，Area 組件都能提供流暢的使用者體驗。
🎯 核心特性：
- 🔄 三級聯動：省市區智慧聯動，選擇更便捷
- 📊 資料完整：提供完整的中國省市區資料包
- ⚙️ 靈活配置：支援自訂顯示列數和佔位文字
- 🎨 樣式定製：豐富的樣式變數，滿足不同設計需求
- 📱 行動優化：專為行動端設計的滑動選擇體驗
配合彈出層組件使用，Area 能為你的應用帶來專業級的地址選擇功能！