插件介绍

腾讯位置服务为小程序开发者提供小程序原生地址输入插件功能，支持智能地址新增、修改，支持地址输入、地址选择、智能地址解析、微信地址导入等功能；支撑小程序开发者快速构建地址管理模块。

接入指引

1、插件申请接入：

在腾讯微信公众平台中， “微信小程序官方后台-设置-第三方设置-插件管理” 里点击 “添加插件”，搜索 “地图地址输入服务” 选择后点击“添加”，通过后，小程序开发者可在小程序内使用该插件。 插件详细开发文档可查看地图地址输入服务插件。

2、设置定位授权：

地图选点插件需要小程序提供定位授权才能够正常使用定位功能：

// app.json
{
  "permission": {
    "scope.userLocation": {
      "desc": "你的位置信息将用于小程序定位"
    }
  }
}

3、引入插件包：

3.1 小程序传入插件配置：

// config.js

// 配置通过函数方式导出到插件，支持异步函数
module.exports = async () => ({
  /** 地图的key */
  key: (await getKey()) ?? 'XXXXX-XXXXX-XXXXX-XXXXX-XXXXX',
  /** 主题色 */
  theme: '#FF0000',
  /** 是否展示智能填写 */
  aiInput: true,
  /** 跳转的链接 */
  navigateUrl: '/pages/path/to/page',
});

插件相关参数说明

依赖的WebService API服务

SaveAddressData 类型说明

3.2 小程序传入插件配置：

插件 appId：wx57d7ae552cbb3084

// app.json
{
  "plugins": {
    "address-form": {
      "version": "[plugin-version]", // 插件版本
      "provider": "wx57d7ae552cbb3084",
      "export": "config.js" // 引入步骤3.1的配置文件
    }
  }
}

4、使用插件：

4.1 新增地址

新增地址时需跳转至插件页面，页面路径为plugin://address-form/index，示例代码如下：

wx.navigateTo({ url: 'plugin://address-form/index' });

4.2 编辑地址

编辑地址时需在 url 中拼接edit字段，示例代码如下：

/** 所在区域项 */
interface Area {
  /** 行政区划名 */
  name?: string;
  /** 行政区划码 */
  id?: string;
}
/** 编辑地址信息 */
interface EditInfo {
  /** 收件人 */
  receiver?: string;
  /** 手机号 */
  phone?: string;
  /** 所在地区，回填逻辑优先匹配id，若无匹配项再匹配name */
  area?: Area[];
  /** 详细地址 */
  address?: string;
  /** 地址标签 */
  label?: string;
  /** 是否为默认地址 */
  default?: boolean;
}

const info: EditInfo = {};

wx.navigateTo({ url: `plugin://address-form/index?edit=${JSON.stringify(info)}` });

编辑数据的 EditInfo 类型说明

4.3 保存地址回调方式

在步骤 3.1 中已描述了支持的三种回调方式，如下分别进行示例说明：

方式一：onClose 回调函数

说明：onClose方法会提前作为配置项 export 到插件，由插件页面主动调用

// 3.1的config.js插件配置项文件

import { SaveAddressInfoApi } from 'apis';

module.exports = {
  ..., // 其他配置项
  async onClose(data: SaveAddressData) {
    // 模拟编辑完成后将编辑信息通过小程序接口保存至后端
    try {
      await SaveAddressInfoApi({ data });
      wx.showToast({ title: '保存成功', icon: 'none' });
    } catch {
      wx.showToast({ title: '保存失败', icon: 'none' });
    }
  },
};

方式二：redirectUrl 页面跳转

说明：配置 redirectUrl 会调用wx.redirectTo()实现跳转并将编辑的地址信息通过 payload 字段传递给跳转的页面，示例如下：

// 3.1的config.js插件配置项文件

module.exports = {
  ..., // 其他配置项
  redirectUrl: '/pages/info/info'
}

// /pages/info/info页面

Page({
  onLoad({ payload }) {
    const info: SaveAddressData = JSON.parse(payload);
    console.log(info.receiver); // 收件人
    console.log(info.phone); // 手机号
    console.log(info.area); // 所在区域
    console.log(info.address); // 详细地址
    console.log(info.label); // 标签
    console.log(info.default); // 是否为默认地址
  },
});

方式三：navigateUrl 页面跳转

说明：该方式与方式二的区别仅为页面跳转调用的函数不同，navigateUrl 会调用wx.navigateTo()实现跳转，其他部分均可直接参考方式二的回调方式

注意：上述保存地址回调方式优先级：onClose > redirectUrl > navigateUrl

部分页面效果图

问题反馈

如果在使用插件过程中遇到问题，可以通过提交工单反馈。