省市区选择器组件

概述

RegionSelector 是一个省市区级联选择器组件，支持最多五级行政区划（省、市、区、街道、村庄），支持静态数据和动态 API 懒加载两种模式。

组件路径：web/apps/web-ele/src/components/zq-form/region-selector/

组件名称：RegionSelector

功能特性

• 五级行政区划：省、市、区、街道、村庄
• 支持静态数据和 API 懒加载
• 可配置选择级别
• 支持搜索过滤
• 显示完整路径或仅显示最后一级
• 支持任意级别选择（checkStrictly）

Props

属性	类型	默认值	说明
modelValue	string | string[]	-	选中的区域编码数组
level	1 | 2 | 3 | 4 | 5	3	选择级别
placeholder	string	-	占位符（自动根据级别生成）
disabled	boolean	false	是否禁用
clearable	boolean	true	是否可清除
multiple	boolean	false	是否多选
showAllLevels	boolean	true	是否显示完整路径
separator	string	'/'	路径分隔符
dataSource	'static' | 'api'	'api'	数据源类型
apiUrl	string	'/api/core/regions'	API 地址
lazy	boolean	true	是否懒加载
checkStrictly	boolean	false	是否可选任意级别
expandTrigger	'click' | 'hover'	'click'	展开触发方式

级别说明

级别	说明	默认占位符
1	仅省份	请选择省份
2	省/市	请选择省/市
3	省/市/区	请选择省/市/区
4	省/市/区/街道	请选择省/市/区/街道
5	省/市/区/街道/村庄	请选择省/市/区/街道/村庄

Events

事件	参数	说明
update:modelValue	string[] | undefined	值更新（区域编码数组）
change	string[] | undefined, RegionItem[]	值变化，返回编码数组和区域对象数组

使用示例

省市区三级选择

<template>
  <RegionSelector
    v-model="regionCodes"
    :level="3"
    placeholder="请选择省市区"
  />
</template>

<script setup>
import { ref } from 'vue';

const regionCodes = ref([]);
// 选中后值为：['110000', '110100', '110101']
</script>

仅省市两级

<template>
  <RegionSelector
    v-model="regionCodes"
    :level="2"
  />
</template>

五级完整选择

<template>
  <RegionSelector
    v-model="regionCodes"
    :level="5"
    :lazy="true"
  />
</template>

使用静态数据

<template>
  <RegionSelector
    v-model="regionCodes"
    data-source="static"
    :level="3"
  />
</template>

允许选择任意级别

<template>
  <RegionSelector
    v-model="regionCodes"
    :level="3"
    :check-strictly="true"
  />
</template>

与表单设计器集成

在表单设计器中，该组件作为 region-selector 类型的表单项使用：

{
  "type": "region-selector",
  "field": "region",
  "label": "所在地区",
  "props": {
    "level": 3,
    "dataSource": "api",
    "lazy": true,
    "showAllLevels": true,
    "clearable": true
  }
}

API 依赖

• RegionApi.getProvinces() - 获取省份列表
• RegionApi.getCities(provinceCode) - 获取城市列表
• RegionApi.getAreas(cityCode) - 获取区县列表
• RegionApi.getStreets(areaCode) - 获取街道列表
• RegionApi.getVillages(streetCode) - 获取村庄列表

典型应用场景

• 地址选择：用户收货地址、公司地址
• 区域配置：配置服务覆盖区域
• 数据统计：按区域筛选数据