Vue3 + Element Plus 实现省市区街道四级联动组件（附完整代码）

最新推荐文章于 2026-04-08 09:28:46 发布

原创

最新推荐文章于 2026-04-08 09:28:46 发布 · 1k 阅读

从零构建企业级Vue3地址选择器：四级联动组件的深度实践与性能优化

在电商、物流、用户管理等众多业务场景中，地址选择功能几乎是表单系统的标配。一个体验流畅、数据准确、易于集成的地址选择组件，能显著提升用户填写效率，减少因地址错误带来的后续问题。过去，我们可能习惯于使用第三方库，但面对定制化需求、性能瓶颈或特殊交互时，自己动手打造一个专属组件，往往能带来更佳的掌控感和灵活性。

今天，我们就深入探讨如何基于 Vue 3 的 Composition API 和 Element Plus UI 库，从零开始构建一个功能完备、性能优异的省市区街道四级联动地址选择器。这不仅仅是一个简单的下拉框组合，我们将融入拼音首字母分组、智能模糊搜索、动态Tab导航等高级特性，并重点剖析数据加载策略、状态管理和性能优化等核心问题。无论你是需要为下一个项目集成此功能，还是希望深入理解复杂组件的设计思路，这篇文章都将提供详实的路径。

1. 项目架构与核心技术选型

在动手编码之前，合理的架构设计和技术选型是成功的基石。我们需要明确组件的核心目标：它必须是一个独立的、可复用的 Vue 3 组件，能够无缝嵌入任何使用 Element Plus 的项目中。

1.1 环境准备与依赖安装

首先，确保你有一个基于 Vue 3 和 Vite（或 Webpack）构建的项目。Element Plus 是我们的 UI 基础，它提供了丰富的表单组件和一致的视觉风格。

# 在现有Vue3项目中安装Element Plus
npm install element-plus
# 或
yarn add element-plus

# 安装中文转拼音库，用于省份首字母分组
npm install chinese-to-pinyin
# 或
yarn add chinese-to-pinyin

# 安装Lodash-es，用于安全的深拷贝操作（非必须，但推荐）
npm install lodash-es
# 或
yarn add lodash-es

接下来，在 main.js 或 main.ts 中全局引入 Element Plus 及其样式。

// main.js
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import App from './App.vue'

const app = createApp(App)
app.use(ElementPlus)
app.mount('#app')

1.2 地址数据源的选择与处理

地址数据的准确性和完整性是组件的生命线。我们通常需要一个包含省、市、区、街道四级编码和名称的 JSON 数据。一个广受认可的开源数据源是 Administrative-divisions-of-China 项目。

获取数据的方式：

前端静态引入：将 JSON 文件下载到项目 public 或 src/assets 目录。这种方式简单，但会增大初始包体积（数据文件约2-3MB）。
异步按需加载：将 JSON 文件放在 public 目录，组件初始化时通过 fetch 或 axios 动态加载。这能优化首屏加载速度。
后端API接口：由后端提供地址查询接口。这种方式最灵活，数据更新无需前端发版，且能实现更复杂的查询逻辑（如根据IP定位）。

提示：对于大多数内部管理系统或对首屏体积不敏感的应用，采用第一种方式最简单直接。如果追求极致性能，可以考虑将数据拆分为省、市、区、街道多个文件，实现真正的按需加载。

我们假设采用第一种方式。下载 pcas-code.json 文件后，将其放入项目合适位置，例如 src/data/pcas-code.json。其数据结构通常如下所示：

[
  {
    "code": "110000",
    "name": "北京市",
    "children": [
      {
        "code": "110100",
        "name": "北京市",
        "children": [
          {
            "code": "110101",
            "name": "东城区",
            "children": [
              { "code": "110101001", "name": "东华门街道" },
              // ... 更多街道
            ]
          }
          // ... 更多区
        ]
      }
    ]
  }
  // ... 更多省份
]

2. 核心组件设计与实现

我们将组件命名为 AddressSelector。其核心交互是：用户点击输入框，弹出一个浮层。浮层默认显示按拼音首字母分组的省份列表，选择省份后，Tab页切换到该省份下的城市列表，以此类推，直至选择街道。

2.1 组件模板结构

我们使用 Element Plus 的 ElPopover 作为浮层容器，ElInput 作为触发和显示输入框，ElTabs 来管理不同层级的选择视图。

<template>
  <ElPopover
    ref="popoverRef"
    :visible="popoverVisible"
    :width="isSearchMode ? 460 : 320"
    placement="bottom-start"
    trigger="click"
    :popper-class="'address-selector-popover'"
  >
    <template #reference>
      <ElInput
        v-model="displayText"
        :placeholder="placeholder"
        :size="size"
        clearable
        @click="handleInputClick"
        @clear="handleClear"
        readonly <!-- 使其只读，避免直接输入，专注于选择交互 -->
      >
        <template #suffix>
          <ElIcon><ArrowDown /></ElIcon>
        </template>
      </ElInput>
    </template>

    <!-- 浮层内容区 -->
    <div class="selector-content">
      <!-- 搜索模式 -->
      <div v-if="isSearchMode" class="search-panel">
        <ElInput
          v-model="searchKeyword"
          placeholder="输入省份、城市或区县名称..."
          @input="handleSearchInput"
          clearable
        />
        <div class="search-results">
          <div
            v-for="item in searchResults"
            :key="item.fullCode"
            class="result-item"
            @click="selectSearchResult(item)"
          >
            {
  
  { item.fullName }}
          </div>
          <div v-if="searchRe

标签