企业级地区编码工具库文档
企业级地区编码工具库文档
一、概述
本文档介绍的地区编码工具库是基于TypeScript为Quasar前端框架开发的企业级组件，遵循GB/T 2260-2007《中华人民共和国行政区划代码》国家标准，提供地区编码与名称的映射转换功能，特别优化了宁夏回族自治区的区域编码支持。
二、核心组件
2.1 RegionCode 枚举
地区编码枚举类型，定义了标准行政区域编码，特别优化了宁夏地区编码体系。
/**
* 地区编码映射枚举（符合GB/T 2260-2007国家标准）
*
* 用于将行政区域编码转换为可读的地区名称
* 特别优化了宁夏回族自治区的区域编码
*/
export enum RegionCode {
/**
* 北京市
* 编码范围：110000 - 119999
*/
BEIJING = '1100',
/**
* 上海市
* 编码范围：310000 - 319999
*/
SHANGHAI = '3100',
/**
* 深圳市（广东省副省级市）
* 编码范围：440300 - 440399
*/
SHENZHEN = '4403',
// =====================
// 宁夏回族自治区行政区划
// =====================
/**
* 银川市（宁夏首府）
* 区划代码：640100
*/
YINCHUAN = '0951',
/**
* 石嘴山市（宁夏工业重镇）
* 区划代码：640200
*/
SHIZUISHAN = '0952',
/**
* 吴忠市（回族文化中心）
* 区划代码：640300
*/
WUZHONG = '0953',
/**
* 固原市（宁南山区中心城市）
* 区划代码：640400
*/
GUYUAN = '0954',
/**
* 中卫市（沙漠旅游城市）
* 区划代码：640500
*/
ZHONGWEI = '0955'
}
2.2 RegionNameMap 对象
地区名称映射对象，将RegionCode枚举值转换为可读的地区名称。
/**
* 地区名称映射对象
*
* 将RegionCode枚举值转换为可读的地区名称
* 企业级应用推荐在Vue composable中使用
*/
export const RegionNameMap: Record<RegionCode, string> = {
[RegionCode.BEIJING]: '北京市',
[RegionCode.SHANGHAI]: '上海市',
[RegionCode.SHENZHEN]: '深圳市',
[RegionCode.YINCHUAN]: '银川市',
[RegionCode.SHIZUISHAN]: '石嘴山市',
[RegionCode.WUZHONG]: '吴忠市',
[RegionCode.GUYUAN]: '固原市',
[RegionCode.ZHONGWEI]: '中卫市'
};
2.3 RegionUtils 工具类
提供地区编码相关的企业级工具方法，封装常用操作。
/**
* 地区工具类
*
* 提供地区编码相关的企业级工具方法
*/
export class RegionUtils {
/**
* 根据编码获取地区名称
* @param code 地区编码
* @returns 地区名称（未找到时返回"未知区域"）
*/
static getRegionName(code: string): string {
return RegionNameMap[code as RegionCode] || `未知区域(${code})`;
}
/**
* 获取宁夏地区列表（企业级专用）
*
* 用于宁夏地区业务的下拉选择框
* @returns 宁夏地区键值对数组
*/
static getNingxiaOptions(): { value: string; label: string }[] {
return [
RegionCode.YINCHUAN,
RegionCode.SHIZUISHAN,
RegionCode.WUZHONG,
RegionCode.GUYUAN,
RegionCode.ZHONGWEI
].map(code => ({
value: code,
label: RegionNameMap[code]
}));
}
/**
* 验证地区编码格式（企业级安全验证）
* @param code 待验证编码
* @returns 是否有效编码
*/
static isValidRegionCode(code: string): boolean {
return Object.values(RegionCode).includes(code as RegionCode);
}
}
三、设计特点
3.1 符合国家标准
- 基于GB/T 2260-2007《中华人民共和国行政区划代码》
- 编码规则严格遵循国家行政区划标准
- 宁夏地区使用专用区号段（095X）
- 完整的JSDoc类型注释，支持IDE智能提示
- 错误处理机制（未找到时返回"未知区域(编码)"）
- 宁夏地区专项支持，满足区域业务需求
- 安全验证方法，确保数据有效性
- 直接生成Quasar组件所需的选项格式
- 提供完整的Vue3组合式API使用示例
- 类型安全的枚举值引用，减少运行时错误
- 与Quasar表单组件无缝集成
- 模块化设计，便于添加新地区
- 统一的命名规范，保持代码一致性
- 工具类封装，降低维护成本
3.2 企业级优化
3.3 Quasar集成优化
3.4 可扩展结构
四、使用示例（Quasar/Vue3场景）
<template>
<q-select
label="选择地区"
:options="ningxiaOptions"
v-model="selectedRegion"
emit-value
map-options
/>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import { RegionCode, RegionUtils } from '@/enums/RegionCode';
export default defineComponent({
setup() {
const selectedRegion = ref<string>(RegionCode.YINCHUAN);
return {
selectedRegion,
ningxiaOptions: RegionUtils.getNingxiaOptions()
};
}
});
</script>
五、推荐使用场景
5.1 企业表单
// 在Vue组件中安全使用
import { ref } from 'vue';
import { RegionCode, RegionNameMap } from '@/enums/RegionCode';
// 初始化表单数据
const formData = ref({
region: RegionCode.SHENZHEN,
// 其他表单字段...
});
// 生成完整地区选项
const regionOptions = Object.values(RegionCode).map(code => ({
value: code,
label: RegionNameMap[code]
}));
5.2 数据验证
// 提交前的企业级验证
import { RegionUtils } from '@/enums/RegionCode';
const submitForm = () => {
// 地区编码验证
if (!RegionUtils.isValidRegionCode(formData.value.region)) {
throw new Error('无效的地区编码');
}
// 其他验证和提交逻辑...
};
5.3 宁夏专项业务
<template>
<q-option-group
:options="RegionUtils.getNingxiaOptions()"
v-model="ningxiaRegion"
type="radio"
/>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import { RegionUtils } from '@/enums/RegionCode';
export default defineComponent({
setup() {
const ningxiaRegion = ref('0951');
return {
ningxiaRegion,
RegionUtils
};
}
});
</script>
六、扩展指南
添加新地区
// 1. 添加枚举成员
enum RegionCode {
// 现有地区...
/**
* 广州市（广东省会）
* 区划代码：440100
*/
GUANGZHOU = '4401'
}
// 2. 更新映射对象
RegionNameMap[RegionCode.GUANGZHOU] = '广州市';
// 3. 如需专项业务支持，可在RegionUtils中添加对应方法
class RegionUtils {
// 现有方法...
/**
* 获取广东省地区列表
*/
static getGuangdongOptions(): { value: string; label: string }[] {
return [
RegionCode.GUANGZHOU,
RegionCode.SHENZHEN
// 其他广东地区...
].map(code => ({
value: code,
label: RegionNameMap[code]
}));
}
}
七、完整代码
/**
* 地区编码映射枚举（符合GB/T 2260-2007国家标准）
*
* 用于将行政区域编码转换为可读的地区名称
* 特别优化了宁夏回族自治区的区域编码
*/
export enum RegionCode {
/**
* 北京市
* 编码范围：110000 - 119999
*/
BEIJING = '1100',
/**
* 上海市
* 编码范围：310000 - 319999
*/
SHANGHAI = '3100',
/**
* 深圳市（广东省副省级市）
* 编码范围：440300 - 440399
*/
SHENZHEN = '4403',
// =====================
// 宁夏回族自治区行政区划
// =====================
/**
* 银川市（宁夏首府）
* 区划代码：640100
*/
YINCHUAN = '0951',
/**
* 石嘴山市（宁夏工业重镇）
* 区划代码：640200
*/
SHIZUISHAN = '0952',
/**
* 吴忠市（回族文化中心）
* 区划代码：640300
*/
WUZHONG = '0953',
/**
* 固原市（宁南山区中心城市）
* 区划代码：640400
*/
GUYUAN = '0954',
/**
* 中卫市（沙漠旅游城市）
* 区划代码：640500
*/
ZHONGWEI = '0955'
}
/**
* 地区名称映射对象
*
* 将RegionCode枚举值转换为可读的地区名称
* 企业级应用推荐在Vue composable中使用
*/
export const RegionNameMap: Record<RegionCode, string> = {
[RegionCode.BEIJING]: '北京市',
[RegionCode.SHANGHAI]: '上海市',
[RegionCode.SHENZHEN]: '深圳市',
[RegionCode.YINCHUAN]: '银川市',
[RegionCode.SHIZUISHAN]: '石嘴山市',
[RegionCode.WUZHONG]: '吴忠市',
[RegionCode.GUYUAN]: '固原市',
[RegionCode.ZHONGWEI]: '中卫市'
};
/**
* 地区工具类
*
* 提供地区编码相关的企业级工具方法
*/
export class RegionUtils {
/**
* 根据编码获取地区名称
* @param code 地区编码
* @returns 地区名称（未找到时返回"未知区域"）
*/
static getRegionName(code: string): string {
return RegionNameMap[code as RegionCode] || `未知区域(${code})`;
}
/**
* 获取宁夏地区列表（企业级专用）
*
* 用于宁夏地区业务的下拉选择框
* @returns 宁夏地区键值对数组
*/
static getNingxiaOptions(): { value: string; label: string }[] {
return [
RegionCode.YINCHUAN,
RegionCode.SHIZUISHAN,
RegionCode.WUZHONG,
RegionCode.GUYUAN,
RegionCode.ZHONGWEI
].map(code => ({
value: code,
label: RegionNameMap[code]
}));
}
/**
* 验证地区编码格式（企业级安全验证）
* @param code 待验证编码
* @returns 是否有效编码
*/
static isValidRegionCode(code: string): boolean {
return Object.values(RegionCode).includes(code as RegionCode);
}
}
八、总结
本地区编码工具库通过枚举、映射对象和工具类的组合设计，为企业级前端应用提供了安全、高效、可扩展的地区编码解决方案。特别优化的宁夏地区支持满足了专项业务需求，而符合国家标准的设计确保了系统的兼容性和规范性。
通过TypeScript的强类型特性，该工具库提供了良好的开发体验和代码安全性，同时工具类的封装降低了业务逻辑与地区编码处理的耦合度，提高了代码的可维护性。
浙公网安备 33010602011771号