Vant4 Area 省市區(qū)選擇

介紹

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

引入

通過(guò)以下方式來(lái)全局注冊(cè)組件，更多注冊(cè)方式請(qǐng)參考組件注冊(cè)。

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

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

代碼演示

基礎(chǔ)用法

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

<van-area title="標(biāo)題" :area-list="areaList" />

areaList 格式

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

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

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

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

@vant/area-data

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

# 通過(guò) npm
npm i @vant/area-data

# 通過(guò) yarn
yarn add @vant/area-data

# 通過(guò) pnpm
pnpm add @vant/area-data

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

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

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

控制選中項(xiàng)

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

<van-area v-model="value" title="標(biāo)題" :area-list="areaList" />

import { ref } from 'vue';

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

配置顯示列

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

<van-area title="標(biāo)題" :area-list="areaList" :columns-num="2" />

配置列占位提示文字

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

<van-area
  title="標(biāo)題"
  :area-list="areaList"
  :columns-placeholder="['請(qǐng)選擇', '請(qǐng)選擇', '請(qǐng)選擇']"
/>

API

Props

Events

Slots

方法

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

類型定義

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

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

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

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

const areaRef = ref<AreaInstance>();

areaRef.value?.confirm();

常見(jiàn)問(wèn)題

在桌面端無(wú)法操作組件？

參見(jiàn)桌面端適配。