Vant4 Area 省市區(qū)選擇

介紹

省市區(qū)三級聯(lián)動選擇，通常與彈出層組件配合使用。

引入

通過以下方式來全局注冊組件，更多注冊方式請參考組件注冊。

import { createApp } from 'vue';
import { Area } from 'vant';

const app = createApp();
app.use(Area);

代碼演示

基礎(chǔ)用法

初始化省市區(qū)組件時，需要通過 ?area-list? 屬性傳入省市區(qū)數(shù)據(jù)。

<van-area title="標題" :area-list="areaList" />

areaList 格式

areaList 為對象結(jié)構(gòu)，包含 ?province_list?、?city_list?、?county_list? 三個 key。

每項以地區(qū)碼作為 key，省市區(qū)名字作為 value。地區(qū)碼為 6 位數(shù)字，前兩位代表省份，中間兩位代表城市，后兩位代表區(qū)縣，以 0 補足 6 位。比如北京的地區(qū)碼為 ?11?，以 0 補足 6 位，為 ?110000?。

示例數(shù)據(jù)如下：

const areaList = {
  province_list: {
    110000: '北京市',
    120000: '天津市',
  },
  city_list: {
    110100: '北京市',
    120100: '天津市',
  },
  county_list: {
    110101: '東城區(qū)',
    110102: '西城區(qū)',
    // ....
  },
};

@vant/area-data

Vant 官方提供了一份默認的中國省市區(qū)數(shù)據(jù)，可以通過 @vant/area-data 引入：

# 通過 npm
npm i @vant/area-data

# 通過 yarn
yarn add @vant/area-data

# 通過 pnpm
pnpm add @vant/area-data

import { areaList } from '@vant/area-data';

export default {
  setup() {
    return { areaList };
  },
};

Tips: 中國的行政區(qū)劃每年都會有變動，如果發(fā)現(xiàn)省市區(qū)數(shù)據(jù)未及時更新，歡迎提 Pull Request 幫助我們更新。你可以在「國家統(tǒng)計局 - 全國區(qū)劃代碼」 和「民政部 - 行政區(qū)劃代碼」上查詢到最新數(shù)據(jù)，請根據(jù)官方數(shù)據(jù)進行核實。

控制選中項

通過 ?v-model? 綁定當前選中的地區(qū)碼。

<van-area v-model="value" title="標題" :area-list="areaList" />

import { ref } from 'vue';

export default {
  setup() {
    const value = ref('330302');
    return { value };
  },
};

配置顯示列

可以通過 ?columns-num? 屬性配置省市區(qū)顯示的列數(shù)，默認情況下會顯示省市區(qū)，當你設(shè)置為 ?2?，則只會顯示省市選擇。

<van-area title="標題" :area-list="areaList" :columns-num="2" />

配置列占位提示文字

可以通過 ?columns-placeholder? 屬性配置每一列的占位提示文字。

<van-area
  title="標題"
  :area-list="areaList"
  :columns-placeholder="['請選擇', '請選擇', '請選擇']"
/>

API

Props

Events

Slots

方法

通過 ref 可以獲取到 Area 實例并調(diào)用實例方法，詳見組件實例方法。

類型定義

組件導(dǎo)出以下類型定義：

import type { AreaProps, AreaList, AreaInstance } from 'vant';

?AreaInstance? 是組件實例的類型，用法如下：

import { ref } from 'vue';
import type { AreaInstance } from 'vant';

const areaRef = ref<AreaInstance>();

areaRef.value?.confirm();

常見問題

在桌面端無法操作組件？

參見桌面端適配。