更新记录

1.0.0（2026-06-11） 下载此版本

跨端收货地址管理模版，支持列表、新增、编辑、删除、设为默认，内置主题配色，适配小程序、H5、Android、iOS

平台兼容性

收货地址管理模版 · 使用说明

跨端 uni-app 前端项目模板，提供完整的收货地址管理能力，适合电商、外卖、生鲜、O2O 等业务场景快速接入。

一、插件简介

本模版开箱即用，默认使用本地缓存存储地址数据，无需后端即可运行演示。包含以下能力：

二、环境要求

三、安装与导入

方式一：从插件市场导入（推荐）

1. 打开 DCloud 插件市场，搜索并下载本模版
2. 在 HBuilderX 中选择导入到本地目录
3. 使用 HBuilderX 打开导入后的项目

方式二：解压源码导入

1. 解压下载的 zip 包
2. HBuilderX：文件 → 导入 → 从本地目录导入
3. 选择项目根目录（包含 manifest.json、pages.json 的目录）

模版 manifest.json 中不含 DCloud AppID 和微信小程序 AppID，导入后需自行配置（见下文）。

四、首次运行配置

1. 配置 AppID

打开 manifest.json：

• 基础配置：点击「重新获取」配置 DCloud AppID
• 微信小程序：填写你的小程序 AppID（如需运行到微信）

2. 微信小程序位置权限（使用地图选点时必配）

模版已在 manifest.json 中预置以下配置，请根据业务修改 scope.userLocation 说明文案：

"mp-weixin": {
  "requiredPrivateInfos": ["chooseLocation", "getLocation"],
  "permission": {
    "scope.userLocation": {
      "desc": "为了更好的为你提供服务，获取您的位置信息"
    }
  }
}

同时需在微信公众平台 → 开发管理 → 接口设置中开通地理位置相关接口。

3. 运行项目

H5 本地开发端口可在 vue.config.js 中修改（默认 9001）。

五、页面说明

页面跳转示例

// 打开地址列表
uni.navigateTo({ url: '/pages/index/index' })

// 新增地址
uni.navigateTo({ url: '/pages/address/edit' })

// 编辑地址（id 需 encodeURIComponent）
uni.navigateTo({
  url: `/pages/address/edit?id=${encodeURIComponent(addressId)}`
})

六、目录结构

address-template/
├── pages/
│   ├── index/index.vue              # 地址列表页
│   └── address/edit.vue             # 新增/编辑页
├── components/
│   ├── address-item/                # 地址卡片组件
│   └── address-theme-picker/        # 主题选择弹层
├── utils/
│   ├── address.js                   # 地址 CRUD（核心数据层）
│   ├── address-theme.js             # 主题工具与预设
│   └── storage.js                   # 本地缓存封装
├── config/
│   └── address-theme.js             # 主题全局配置
├── store/modules/
│   ├── theme.js                     # 主题 Vuex
│   └── system.js                    # 系统信息
├── mixins/
│   └── addressTheme.js              # 主题 mixin（页面/组件复用）
├── static/
│   └── address-theme.scss           # 主题 CSS 变量
├── uni_modules/uview-next/          # UI 依赖（必须保留）
├── App.vue
├── main.js
├── pages.json
└── manifest.json

七、主题配置

编辑 config/address-theme.js：

export default {
  // 预设主题：orange | red | blue | green | purple
  theme: 'orange',

  // 自定义配色（设置后优先级高于 theme）
  custom: null,
  // custom: {
  //   primary: '#1677ff',
  //   primaryDark: '#0958d9',
  //   primaryLight: '#e6f4ff'
  // },

  // 用户切换主题后是否写入本地缓存
  persist: true,

  // 列表页导航栏是否显示主题设置图标（上线建议 false）
  showThemePicker: true
}

代码中动态切换主题

// 切换预设主题
this.$store.dispatch('setAddressTheme', 'blue')

// 设置自定义主题
this.$store.dispatch('setAddressCustomTheme', {
  primary: '#1677ff',
  primaryDark: '#0958d9',
  primaryLight: '#e6f4ff'
})

// 恢复默认
this.$store.dispatch('resetAddressTheme')

在自定义页面中使用主题

import addressThemeMixin from '@/mixins/addressTheme'

export default {
  mixins: [addressThemeMixin],
  // template 中绑定 :style="themeVars" 即可使用 CSS 变量
}

可用 CSS 变量示例：--addr-primary、--addr-bg、--addr-text 等，详见 static/address-theme.scss。

八、数据层 API

所有地址操作集中在 utils/address.js，默认读写本地缓存，存储 Key 为 ADDRESS_LIST。

导出方法

使用示例

import {
  getAddressList,
  getAddressById,
  saveAddress,
  deleteAddress,
  setDefaultAddress
} from '@/utils/address'

// 获取列表
const list = getAddressList()

// 新增
await saveAddress({
  name: '张三',
  phone: '***',
  province: '广东省',
  city: '深圳市',
  district: '南山区',
  regionCodes: ['440000', '440300', '440305'],
  detail: '科技园南路XX号',
  isDefault: true
})

// 更新
await saveAddress({
  id: 'addr_xxx',
  name: '张三',
  phone: '***',
  province: '广东省',
  city: '深圳市',
  district: '南山区',
  regionCodes: ['440000', '440300', '440305'],
  detail: '更新后的详细地址',
  isDefault: false
})

// 删除
await deleteAddress('addr_xxx')

// 设为默认
await setDefaultAddress('addr_xxx')

地址数据结构

{
  id: 'addr_1700000000_abc123',   // 唯一标识，自动生成
  name: '张三',                    // 收货人，2-20 字
  phone: '***',           // 手机号，11 位
  province: '广东省',              // 省
  city: '深圳市',                  // 市
  district: '南山区',              // 区
  regionCodes: ['440000', '440300', '440305'], // 省市区编码
  detail: '科技园南路XX号',         // 详细地址，5-120 字
  isDefault: true,                // 是否默认
  latitude: 22.54,                // 纬度（地图选点，可选）
  longitude: 113.94,              // 经度（地图选点，可选）
  createTime: 1700000000000,      // 创建时间戳
  updateTime: 1700000000000       // 更新时间戳
}

九、接入后端 API

模版默认本地存储，生产环境建议对接服务端。只需修改 utils/address.js 中的 CRUD 方法，保持方法签名和返回结构不变，页面层无需改动。

改造思路

// utils/address.js 示例（伪代码）

import request from '@/config/request' // 自行封装

export async function getAddressList() {
  const res = await request.get('/api/address/list')
  return res.data || []
}

export async function saveAddress(address) {
  if (address.id) {
    return request.put(`/api/address/${address.id}`, address)
  }
  return request.post('/api/address', address)
}

export async function deleteAddress(id) {
  return request.delete(`/api/address/${id}`)
}

export async function setDefaultAddress(id) {
  return request.post(`/api/address/${id}/default`)
}

接入后建议

1. 登录后将用户 ID 加入缓存 Key，实现多用户隔离，例如 ADDRESS_LIST_${userId}
2. 列表页 onShow 中调用 loadList() 刷新数据（已内置）
3. 保留 validateAddress 做前端校验，减少无效请求

十、集成到已有项目

若只需地址模块而非完整项目，可按以下步骤迁移：

1. 复制文件

将以下目录 / 文件复制到你的项目：

pages/index/index.vue
pages/address/edit.vue
components/address-item/
components/address-theme-picker/
utils/address.js
utils/address-theme.js
utils/storage.js
config/address-theme.js
store/modules/theme.js
mixins/addressTheme.js
static/address-theme.scss

并确保 uni_modules/uview-next 已安装（或项目中已有 uView Next）。

2. 注册路由

在 pages.json 中添加：

{
  "path": "pages/index/index",
  "style": {
    "navigationBarTitleText": "收货地址",
    "navigationStyle": "custom"
  }
},
{
  "path": "pages/address/edit",
  "style": {
    "navigationBarTitleText": "编辑地址",
    "navigationStyle": "custom"
  }
}

3. 配置 easycom（若无）

"easycom": {
  "^u-(.*)": "@/uni_modules/uview-next/components/u-$1/u-$1.vue"
}

4. 初始化主题

在 App.vue 的 onLaunch 中调用：

this.$store.dispatch('initAddressTheme')

并在 store 中合并 theme.js 模块（参考本模版 store/index.js 的自动合并写法）。

5. 引入样式

在 App.vue 中：

@import "@/uni_modules/uview-next/index.scss";
@import "@/static/address-theme.scss";

十一、平台差异说明

十二、组件说明

address-item（地址卡片）

<address-item
  :item="addressItem"
  @edit="handleEdit"
  @delete="handleDelete"
  @set-default="handleSetDefault"
/>

address-theme-picker（主题选择器）

<address-theme-picker ref="themePicker" />

this.$refs.themePicker.open()

十三、常见问题

Q1：编辑页提示「地址不存在或已被删除」？

• 确认跳转时 URL 中的 id 使用了 encodeURIComponent
• 确认本地缓存未被清空
• 检查 utils/address.js 是否被修改导致 ID 匹配逻辑变化

Q2：微信小程序地图选点失败？

1. 检查 manifest.json 中 requiredPrivateInfos 和 permission 配置
2. 在微信公众平台开通地理位置接口
3. 真机调试时确认已授权位置权限

Q3：如何关闭主题设置入口？

将 config/address-theme.js 中 showThemePicker 设为 false。

Q4：如何修改主题色而不让用户切换？

// config/address-theme.js
export default {
  theme: 'blue',
  custom: null,
  persist: false,
  showThemePicker: false
}

或直接设置 custom 固定品牌色。

Q5：数据存在哪里？如何清空？

• 存储 Key：ADDRESS_LIST
• 主题 Key：ADDRESS_THEME_NAME、ADDRESS_THEME_CUSTOM
• 开发阶段可在微信开发者工具 → Storage 面板手动清除，或调用 uni.removeStorageSync('ADDRESS_LIST')

Q6：能否用于 Vue 3 项目？

本模版基于 Vue 2 开发。Vue 3 项目需自行升级语法（Composition API、Vuex → Pinia 等），或仅迁移 utils/address.js 数据层逻辑。

十四、隐私与权限

十五、版本记录

v1.0.0

• 地址列表、新增、编辑、删除、设为默认
• 省市区选择、地图选点（微信/App）
• 5 套预设主题 + 自定义配色
• 本地缓存存储

许可证

MIT