uniapp vue3+ts H5 省市区选择器组件

一、背景与问题

在H5开发中，省市区选择器是常见需求之一。传统方案多采用三级联动的下拉选择，但存在以下痛点：

数据加载性能问题：传统方案需要在前端维护完整的省市区数据，导致初始加载时占用大量内存
交互体验差：传统下拉选择器无法实现动态加载和搜索功能
复用性差：不同业务场景需要定制化改造
数据更新困难：行政区划变更时需要手动更新数据

本方案采用动态加载+虚拟滚动技术，结合TypeScript的类型安全特性，实现高性能、可扩展的省市区选择器组件。

二、基本原理

省市区选择器的核心原理是基于递归结构的树形数据处理，具体包含以下技术点：

树形数据结构：用嵌套对象表示省市区层级关系
动态渲染：根据当前选择层级动态生成下拉选项
虚拟滚动：对长列表使用虚拟滚动技术优化性能
数据懒加载：按需加载下一级数据，避免一次性加载全部数据
类型安全：使用TypeScript定义明确的数据结构

三、环境准备

开发环境：uni-app + Vue3 + TypeScript

依赖包：

npm install @types/axios --save-dev
npm install axios --save

数据源：使用阿里云的行政区划数据接口（需申请API密钥）
开发工具：HBuilderX 3.30+ 或 VSCode + Volar插件

四、核心实现

1. 树形数据结构定义

// types/region.ts
export interface RegionNode {
  id: string;
  name: string;
  level: number; // 1: 省，2: 市，3: 区
  children?: RegionNode[];
  parentId?: string;
}

2. 组件核心逻辑

<template>
  <view class="region-picker">
    <scroll-view :scroll-y="true" class="picker-container">
      <view v-for="item in currentLevelData" :key="item.id" 
        class="picker-item"
        @click="selectRegion(item)">
        {{ item.name }}
      </view>
    </scroll-view>
    <view class="footer">
      <button @click="prevLevel">上一级</button>
      <button @click="confirmSelect">确定</button>
    </view>
  </view>
</template>

<script lang="ts">
import { ref, reactive, computed } from 'vue';
import axios from 'axios';

interface RegionTreeNode {
  id: string;
  name: string;
  level: number;
  children?: RegionTreeNode[];
  parentId?: string;
}

export default {
  name: 'RegionPicker',
  props: {
    initialLevel: {
      type: Number,
      default: 1
    },
    onConfirm: {
      type: Function,
      default: () => {}
    }
  },
  setup(props) {
    const currentLevel = ref<number>(props.initialLevel);
    const selectedId = ref<string | null>(null);
    const currentLevelData = ref<RegionTreeNode[]>([]);
    const parentIds = ref<string[]>([]);
    
    // 模拟行政区划数据
    const regionData = ref<RegionTreeNode[]>([
      {
        id: '110000',
        name: '北京市',
        level: 1,
        children: [
          {
            id: '110100',
            name: '市辖区',
            level: 2,
            children: [
              {
                id: '110101',
                name: '东城区',
                level: 3
              },
              {
                id: '110102',
                name: '西城区',
                level: 3
              }
            ]
          }
        ]
      }
    ]);

    const fetchRegionData = async (parentId: string, level: number) => {
      // 实际开发中应调用API接口
      // 模拟数据
      const data: RegionTreeNode[] = [
        { id: `${parentId}01`, name: '区1', level: level+1 },
        { id: `${parentId}02`, name: '区2', level: level+1 },
        { id: `${parentId}03`, name: '区3', level: level+1 }
      ];
      return data;
    };

    const loadChildren = async (parentId: string, level: number) => {
      const data = await fetchRegionData(parentId, level);
      return data;
    };

    const selectRegion = (item: RegionTreeNode) => {
      selectedId.value = item.id;
      parentIds.value = [...parentIds.value, item.id];
      
      if (item.level < 3) {
        const nextLevelData = await loadChildren(item.id, item.level);
        currentLevelData.value = nextLevelData;
        currentLevel.value = item.level + 1;
      } else {
        props.onConfirm(item);
      }
    };

    const prevLevel = () => {
      if (currentLevel.value > 1) {
        currentLevel.value--;
        const parentId = parentIds.value[parentIds.value.length - 1];
        const nextLevelData = await loadChildren(parentId, currentLevel.value);
        currentLevelData.value = nextLevelData;
      }
    };

    return {
      currentLevel,
      selectedId,
      currentLevelData,
      selectRegion,
      prevLevel
    };
  }
};
</script>

<style scoped>
.region-picker {
  height: 100vh;
  display: flex;
  flex-direction: column;
}

.picker-container {
  flex: 1;
  overflow: hidden;
}

.picker-item {
  height: 60rpx;
  line-height: 60rpx;
  padding: 0 30rpx;
  font-size: 28rpx;
}

.footer {
  flex: 0 0 120rpx;
  display: flex;
  justify-content: space-around;
  background-color: #f5f5f5;
}

button {
  width: 100rpx;
  height: 60rpx;
  font-size: 28rpx;
}
</style>

3. 关键代码解释

树形数据结构：使用嵌套对象表示省市区层级关系，通过level字段区分层级
动态加载：通过fetchRegionData函数模拟数据获取，实际开发中应替换为API调用
递归加载：loadChildren函数实现层级递归加载，避免一次性加载所有数据
状态管理：使用ref管理当前层级、选中ID和父级ID列表
交互逻辑：selectRegion处理选择事件，prevLevel实现返回上一级功能

五、完整案例

1. 项目结构

src/
├── pages/
│   └── select/
│       └── index.vue
├── components/
│   └── RegionPicker.vue
├── types/
│   └── region.ts
├── utils/
│   └── region.ts

2. 父组件调用示例

<template>
  <view class="container">
    <RegionPicker 
      :initial-level="1"
      @confirm="handleConfirm"
    />
  </view>
</template>

<script lang="ts">
import { defineComponent } from 'vue';
import RegionPicker from '@/components/RegionPicker.vue';

export default defineComponent({
  name: 'SelectPage',
  components: { RegionPicker },
  methods: {
    handleConfirm(region: any) {
      uni.showToast({
        title: `选择结果：${region.name}`,
        icon: 'none'
      });
    }
  }
});
</script>

3. 数据接口封装（utils/region.ts）

import axios from 'axios';

export interface RegionResponse {
  code: number;
  data: Array<{
    id: string;
    name: string;
    level: number;
    parentId: string;
  }>;
}

export const getRegionList = async (parentId: string = '110000', level: number = 1): Promise<RegionResponse> => {
  const response = await axios.get(`https://api.example.com/regions`, {
    params: { parentId, level }
  });
  return response.data;
};

六、源码解析

1. 核心逻辑流程

初始化时加载省级数据
点击某省时加载市级数据
点击某市时加载区级数据
选择完毕后触发confirm事件

2. 递归加载机制

const loadChildren = async (parentId: string, level: number) => {
  const response = await getRegionList(parentId, level);
  
  if (response.code === 200) {
    return response.data.map(item => ({
      id: item.id,
      name: item.name,
      level: item.level,
      parentId: item.parentId
    }));
  }
  
  throw new Error('获取地区数据失败');
};

3. 类型安全处理

interface RegionTreeNode {
  id: string;
  name: string;
  level: number;
  children?: RegionTreeNode[];
  parentId?: string;
}

七、进阶使用

1. 增加搜索功能

<template>
  <view class="search-bar">
    <input type="text" v-model="searchQuery" placeholder="搜索地区" />
  </view>
</template>

<script lang="ts">
export default {
  setup() {
    const searchQuery = ref<string>('');
    
    const filterData = (data: RegionTreeNode[]) => {
      return data.filter(item => 
        item.name.includes(searchQuery.value)
      );
    };
    
    return { searchQuery, filterData };
  }
};
</script>

2. 增加数据缓存

const regionCache = new Map<string, RegionTreeNode[]>();

const getRegionList = async (parentId: string, level: number): Promise<RegionTreeNode[]> => {
  if (regionCache.has(`${parentId}-${level}`)) {
    return regionCache.get(`${parentId}-${level}`)!;
  }
  
  const response = await axios.get(`https://api.example.com/regions`, {
    params: { parentId, level }
  });
  
  if (response.code === 200) {
    const data = response.data.map(item => ({
      id: item.id,
      name: item.name,
      level: item.level,
      parentId: item.parentId
    }));
    
    regionCache.set(`${parentId}-${level}`, data);
    return data;
  }
  
  throw new Error('获取地区数据失败');
};

3. 增加虚拟滚动优化

<template>
  <scroll-view :scroll-y="true" class="picker-container">
    <view v-for="item in currentLevelData" :key="item.id" 
      class="picker-item"
      @click="selectRegion(item)">
      {{ item.name }}
    </view>
  </scroll-view>
</template>

<script lang="ts">
import { ref, computed } from 'vue';

export default {
  setup() {
    const currentLevelData = ref<RegionTreeNode[]>([]);
    const visibleItems = ref<number>(10); // 每页显示数量
    
    const getVisibleItems = computed(() => {
      return currentLevelData.value.slice(0, visibleItems.value);
    });
    
    return { currentLevelData, visibleItems, getVisibleItems };
  }
};
</script>

八、性能与工程实践

1. 性能优化方案

优化措施	说明
虚拟滚动	只渲染当前可见的列表项，降低DOM节点数量
数据缓存	使用Map缓存已获取的地区数据，避免重复请求
分页加载	每次加载固定数量的地区数据，避免一次性加载过多数据
懒加载	仅在用户滚动到某一级时才加载下一级数据

2. 异常处理机制

const fetchRegionData = async (parentId: string, level: number): Promise<RegionTreeNode[]> => {
  try {
    const response = await axios.get(`https://api.example.com/regions`, {
      params: { parentId, level }
    });
    
    if (response.code === 200) {
      return response.data.map(item => ({
        id: item.id,
        name: item.name,
        level: item.level,
        parentId: item.parentId
      }));
    }
    
    throw new Error('获取地区数据失败');
  } catch (error) {
    console.error('获取地区数据异常:', error);
    return [];
  }
};

3. 安全考虑

数据验证：确保返回的行政区划数据符合预期结构
接口安全：使用HTTPS加密传输，防止数据泄露
权限控制：对敏感接口进行身份验证和权限校验
输入过滤：对用户输入进行XSS过滤处理

九、常见问题与踩坑

1. 常见错误

错误现象	原因分析	解决方案
选择后无法返回	未正确维护父级ID列表	在selectRegion方法中正确更新parentIds
数据加载缓慢	一次性加载过多数据	使用分页或虚拟滚动技术
无法选择区级	未正确处理level判断	确保level递增逻辑正确
点击无响应	未正确绑定点击事件	检查@click事件绑定是否正确

2. 高级问题

数据不一致问题：当行政区划变更时，需要及时更新数据
性能瓶颈：对于超大规模数据，需要引入更复杂的优化策略
多级联动问题：需要确保层级之间的父子关系正确

十、最佳实践

使用TypeScript：确保类型安全，提高代码可维护性
采用分层架构：分离数据获取、业务逻辑和UI层
使用虚拟滚动：优化长列表性能
实现数据缓存：避免重复请求，提高响应速度
添加搜索功能：提升用户体验
进行单元测试：确保核心逻辑的正确性
使用状态管理：管理复杂的组件状态

十一、总结

本方案通过实现一个基于Vue3+TypeScript的省市区选择器组件，深入探讨了动态数据加载、递归结构处理和性能优化等关键技术点。在实际开发中，该组件适用于：

需要动态加载的省市区选择场景
需要支持多级联动的复杂选择场景
需要高性能表现的大型项目

但需要注意避免在以下场景使用：

需要立即显示全部数据的场景
需要严格数据校验的金融类系统
对性能要求不高的小型项目

通过合理使用该组件，可以显著提升H5页面的交互体验和开发效率。在实际开发中，建议根据具体业务需求选择合适的实现方式，并结合性能测试进行优化调整。

uniapp vue3+ts H5 省市区选择器组件

uniapp vue3+ts H5 省市区选择器组件

一、背景与问题

二、基本原理

三、环境准备

四、核心实现

1. 树形数据结构定义

2. 组件核心逻辑

3. 关键代码解释

五、完整案例

1. 项目结构

2. 父组件调用示例

3. 数据接口封装（utils/region.ts）

六、源码解析

1. 核心逻辑流程

2. 递归加载机制

3. 类型安全处理

七、进阶使用

1. 增加搜索功能

2. 增加数据缓存

3. 增加虚拟滚动优化

八、性能与工程实践

1. 性能优化方案

2. 异常处理机制

3. 安全考虑

九、常见问题与踩坑

1. 常见错误

2. 高级问题

十、最佳实践

十一、总结

评论已关闭

推荐阅读