插件介绍

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

接入指引

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',
});

插件相关参数说明

属性	类型	说明	是否必须传入	默认值
key	string	插件依赖腾讯位置服务的相关WebService API服务，需要在腾讯位置服务官网注册 key ,并确认具备相关服务额度以确保插件功能正常，相关WebService API服务服务见下表。	是	‘’
theme	string	主题色，支持如下格式：’#FFFFFF’、’#ffffff’、‘rgb(255, 255, 255)’、‘rgba(255, 255, 255, 0.5)’	否	‘#0067FF’
aiInput	boolean	是否启用"智能解析"功能；	否	false
onClose	(data: SaveAddressData) => void	保存地址回调方式一：点击保存后会调用传入的 onClose 方法，并调用wx.navigateBack({ delta: 1 })返回到小程序页面	否	-
redirectUrl	string	保存地址回调方式二：点击保存后会调用wx.redirectTo()方法，地址编辑数据通过payload传递	否	-
navigateUrl	string	保存地址回调方式三：点击保存后会调用wx.navigateTo()方法，地址编辑数据通过payload传递	否	-

依赖的WebService API服务

服务名	相关功能点	调用时机	说明	官方文档
获取省市区列表	所在地区	进入插件页 onLoad	获取省级、市级、区级的行政区划信息	https://lbs.qq.com/service/webService/webServiceGuide/search/webServiceDistrict#2
获取下级行政区划	所在地区	选中三级行政区后	获取用户选中的区县（三级）其下乡镇/街道（四级）信息	https://lbs.qq.com/service/webService/webServiceGuide/search/webServiceDistrict#3
关键词输入提示	详细地址	选中所在地区后输入详细地址	对用户输入的详细地址提供联想地址	https://lbs.qq.com/service/webService/webServiceGuide/search/webServiceSuggestion
智能地址解析	智能填写	智能填写识别	提供文字自动识别地址信息的能力，并将识别的地址信息填写到对应的模块。	https://lbs.qq.com/service/webService/webServiceGuide/address/SmartGeocoder

SaveAddressData 类型说明

属性	类型	说明	默认值
receiver	string	收件人	‘’
phone	string	手机号	‘’
area	{name: string; id: string}[]	所在地区的行政区划信息，name 为行政区划名，id 为行政区划码	[]
address	string	详细地址	‘’
label	string	地址标签	‘’
default	boolean	是否为默认地址	false

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 类型说明

属性	类型	说明	默认值
receiver	string	收件人，会校验字符串长度为[1, 25]	‘’
phone	string	手机号，会校验手机号长度为 11	‘’
area	{name: string; id: string}[]	所在地区的行政区划信息，回填逻辑优先匹配 id，若无匹配项再匹配 name	[]
address	string	详细地址，会校验长度为 [2, 120]	‘’
label	string	地址标签，默认标签有’家’、‘公司’、‘学校’，可额外自定义一个标签	‘’
default	boolean	是否为默认地址	false

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

部分页面效果图

问题反馈

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