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 能为你的应用带来专业级的地址选择功能！