Region
行政区划选择器组件
项目状态
版本更新内容请访问 Changelog
如果您的项目正在使用 vue 2.x 版本生态,请使用 v-region 2.x 版本
安装
将 v-region
组件安装到项目中
npm i v-region
npm i v-region
yarn add v-region
yarn add v-region
pnpm add v-region
pnpm add v-region
全局安装组件
import { createApp } from 'vue'
import App from './app.vue'
import Region from 'v-region'
const app = createApp(App)
/**
* Globally register region components
* v-region-group
* v-region-selects
* v-region-columns
* v-region-city-picker
* v-region-text
*/
app.use(Region)
app.mount('#app')
import { createApp } from 'vue'
import App from './app.vue'
import Region from 'v-region'
const app = createApp(App)
/**
* Globally register region components
* v-region-group
* v-region-selects
* v-region-columns
* v-region-city-picker
* v-region-text
*/
app.use(Region)
app.mount('#app')
局部使用组件,这是更推荐的使用方式,而且这也更有利于项目打包时的代码拆分,达到更好的资源按需引用的效果
<template>
<RegionSelects />
</template>
<script setup>
import { RegionSelects } from 'v-region'
</script>
<template>
<RegionSelects />
</template>
<script setup>
import { RegionSelects } from 'v-region'
</script>
实例
下拉列表模式
<RegionSelects :city="false" />
<RegionSelects :city="false" />
<RegionSelects :area="false" />
<RegionSelects :area="false" />
<RegionSelects />
<RegionSelects />
<RegionSelects :town="true" />
<RegionSelects :town="true" />
change 事件响应结果
选择项目值绑定
<template>
<RegionSelects
:town="true"
v-model="region"
/>
</template>
<script setup>
import { ref } from 'vue'
import { RegionSelects } from 'v-region'
const region = ref({
province: '350000',
city: '350100',
area: '350104',
town: '350104008'
})
</script>
<template>
<RegionSelects
:town="true"
v-model="region"
/>
</template>
<script setup>
import { ref } from 'vue'
import { RegionSelects } from 'v-region'
const region = ref({
province: '350000',
city: '350100',
area: '350104',
town: '350104008'
})
</script>
禁用状态
<RegionSelects
:town="true"
:disabled="true"
v-model="region"
/>
<RegionSelects
:town="true"
:disabled="true"
v-model="region"
/>
纯文本模式
行政区域信息以纯文本方式展示
<template>
<RegionText v-model="region" />
</template>
<script setup>
import { ref } from 'vue'
import { RegionText } from 'v-region'
const region = ref({
province: '350000',
city: '350100',
area: '350104',
town: '350104008'
})
</script>
<template>
<RegionText v-model="region" />
</template>
<script setup>
import { ref } from 'vue'
import { RegionText } from 'v-region'
const region = ref({
province: '350000',
city: '350100',
area: '350104',
town: '350104008'
})
</script>
分隔符
在各级别行政区域名称间应用指定的分隔符,增加信息可读性
<RegionText
v-model="region"
separator="-"
/>
<RegionText
v-model="region"
separator="-"
/>
分组模式
使用分组切换显示行政区域的选择模式
分组选择器模式
<RegionGroup v-model="region" />
<RegionGroup v-model="region" />
使用内置按钮作为触发对象的选择器模式
分组核心模块
<RegionGroupCore v-model="region" />
<RegionGroupCore v-model="region" />
核心模块可自由搭配其他交互形式
分组自定义选择器触发对象
使用作用域插槽 Scoped slots
自定义选择器触发对象
<RegionGroup :town="true">
<template #default="{ region, visible }">
<button
type="button"
class="btn btn-success"
>
region: <span v-text="resultText(region)" />,
visible: <span v-text="visible" />
</button>
</template>
</RegionGroup>
<RegionGroup :town="true">
<template #default="{ region, visible }">
<button
type="button"
class="btn btn-success"
>
region: <span v-text="resultText(region)" />,
visible: <span v-text="visible" />
</button>
</template>
</RegionGroup>
作用域插槽中输出了两个数据字段
region
当前区域选择情况数据模型visible
下拉层打开状态
泳道模式
使用多数据列并排展示行政区域的选择模式
泳道选择器模式
<RegionColumns v-model="region" />
<RegionColumns v-model="region" />
使用内置按钮作为触发对象的选择器模式
泳道核心模块
<RegionColumnsCore v-model="region" />
<RegionColumnsCore v-model="region" />
- 北京市
- 天津市
- 河北省
- 山西省
- 内蒙古自治区
- 辽宁省
- 吉林省
- 黑龙江省
- 上海市
- 江苏省
- 浙江省
- 安徽省
- 福建省
- 江西省
- 山东省
- 河南省
- 湖北省
- 湖南省
- 广东省
- 广西壮族自治区
- 海南省
- 重庆市
- 四川省
- 贵州省
- 云南省
- 西藏自治区
- 陕西省
- 甘肃省
- 青海省
- 宁夏回族自治区
- 新疆维吾尔自治区
- 香港特别行政区
- 澳门特别行政区
- 台湾省
核心模块可自由搭配其他交互形式
泳道自定义选择器触发对象
使用作用域插槽 Scoped slots
自定义选择器触发对象
<RegionColumns :town="true">
<template #default="{ region, visible }">
<button
type="button"
class="btn btn-success"
>
region: <span v-text="resultText(region)" />,
visible: <span v-text="visible" />
</button>
</template>
</RegionColumns>
<RegionColumns :town="true">
<template #default="{ region, visible }">
<button
type="button"
class="btn btn-success"
>
region: <span v-text="resultText(region)" />,
visible: <span v-text="visible" />
</button>
</template>
</RegionColumns>
作用域插槽中输出了两个数据字段
region
当前区域选择情况数据模型visible
下拉层打开状态
城市选择器模式
<template>
<RegionCityPicker
v-model="selected"
@change="change"
/>
</template>
<script setup lang="ts">
import { ref } from 'vue'
import { RegionCityPicker } from 'v-region'
import type { RegionItem } from 'v-region'
const selected = ref<string[]>(['110000', '130200', '140100'])
function change (data: RegionItem[]): void {
console.log(data)
}
</script>
<template>
<RegionCityPicker
v-model="selected"
@change="change"
/>
</template>
<script setup lang="ts">
import { ref } from 'vue'
import { RegionCityPicker } from 'v-region'
import type { RegionItem } from 'v-region'
const selected = ref<string[]>(['110000', '130200', '140100'])
function change (data: RegionItem[]): void {
console.log(data)
}
</script>
change 事件响应数据
折叠项目
在默认情况下,选择超过 2 个城市项目,将会被统一收纳显示,并显示折叠收纳数量
设置 overflow
为 true
后,选择项目将被完整显示在触发对象中,不再进行折叠
<RegionCityPicker
v-model="selected"
:overflow="true"
/>
<RegionCityPicker
v-model="selected"
:overflow="true"
/>
Props
v-model/modelValue
- 类型
RegionKeys | string[]
interface RegionInputModel {
province: string
city: string
area: string
town: string
}
interface RegionInputModel {
province: string
city: string
area: string
town: string
}
各级别行政区划选择项目绑定值
格式
RegionCityPicker
城市选择器的选择项目绑定通过 string[]
数组格式进行绑定
city
- 类型
boolean
- 默认
true
使用城市行政级别,若关闭该级别,则所有下级行政级别均不可用
area
- 类型
boolean
- 默认
true
使用区/县行政级别,若关闭该级别,则所有下级行政级别均不可用
town
- 类型
boolean
- 默认
false
使用乡/镇/街道行政级别
blank
- 类型
boolean
- 默认
false
在下拉选项中增加 请选择
选项,该功能仅适用于 RegionSelects
disabled
- 类型
boolean
- 默认
false
设置插件禁用状态,适用于 RegionSelects
、RegionGroup
与 RegionColumns
模式
language
- 类型
string
- 默认
'cn'
插件使用语言
cn
中文en
英文
separator
- 类型
string
- 默认
''
行政区域名称间的分隔符,适用于 RegionText
模式
overflow
- 类型
boolean
- 默认
false
选择的城市较多时,超出 2 个的城市仅以数量显示,仅适用于 RegionCityPicker
模式
true
显示所有选中城市名称false
选中的城市多于两个时,仅显示前两个城市名称,其他城市会被收起
customTriggerClass
- 类型
string
- 默认
''
添加自定义样式类名至触发对象容器,作用于下拉选择的模块
customContainerClass
- 类型
string
- 默认
''
添加自定义样式类名至下拉容器中,作用于下拉选择的模块
事件
组件各类操作响应事件
change
响应行政区划变化
change: (data: RegionModel) => void
change: (data: RegionModel) => void
interface RegionItem {
key: string
value: string
}
interface RegionModel {
province: RegionItem
city: RegionItem
area: RegionItem
town: RegionItem
}
interface RegionItem {
key: string
value: string
}
interface RegionModel {
province: RegionItem
city: RegionItem
area: RegionItem
town: RegionItem
}
你也可直接使用组件提供的类型定义
<template>
<RegionSelects
v-model="region"
@change="change"
/>
</template>
<script setup lang="ts">
import { ref } from 'vue'
import { RegionSelects } from 'v-region'
import type { RegionInputModel, RegionModel } from 'v-region'
const region = ref<RegionInputModel>({
province: '350000',
city: '350100',
area: '350104',
town: '350104008'
})
function change (data: RegionModel): void {
console.log(data)
}
</script>
<template>
<RegionSelects
v-model="region"
@change="change"
/>
</template>
<script setup lang="ts">
import { ref } from 'vue'
import { RegionSelects } from 'v-region'
import type { RegionInputModel, RegionModel } from 'v-region'
const region = ref<RegionInputModel>({
province: '350000',
city: '350100',
area: '350104',
town: '350104008'
})
function change (data: RegionModel): void {
console.log(data)
}
</script>
complete
响应所有有效的行政区划选择完成,该事件仅适用于 RegionGroupCore
与 RegionColumnsCore
核心功能模块
complete: () => void
complete: () => void
visible-change
响应下拉栏打开 / 关闭的状态变化
'visible-change': (visible: boolean) => void
'visible-change': (visible: boolean) => void
API
使用插件的 API 前,需为组件声明 ref
属性,并使用 ref()
声明对应名称的响应式变量以调用 API 方法
<template>
<RegionSelects ref="region" />
</template>
<script setup>
import { ref } from 'vue'
import { RegionSelects } from 'v-region'
const region = ref()
// call api
region.value.reset()
</script>
<template>
<RegionSelects ref="region" />
</template>
<script setup>
import { ref } from 'vue'
import { RegionSelects } from 'v-region'
const region = ref()
// call api
region.value.reset()
</script>
reset
重置并清空所有级别的数据
reset: () => void
reset: () => void