支付宝小程序API 选择城市

my.chooseCity

简介

my.chooseCity 是打开城市选择列表的 API。

扫码体验

选择城市.jpeg

示例代码

<!-- API-DEMO page/API/choose-city/choose-city.axml-->
<view class="page">
  <view class="page-description">选择城市 API</view>
  <view class="page-section">
    <view class="page-section-title">my.chooseCity</view>
    <view class="page-section-demo">
      <button type="primary" onTap="chooseCity">选择城市</button>
    </view>
  </view>
  <view class="page-description">修改当前定位城市的名称 API</view>
  <view class="page-section">
    <view class="page-section-title">my.setLocatedCity</view>
    <view class="page-section-demo">
      <button type="primary" onTap="setLocatedCity">修改当前定位城市的名称</button>
    </view>
  </view>
</view>

// API-DEMO page/choose-city/choose-city.js
Page({
  chooseCity() {
    my.chooseCity({
      showLocatedCity: true,
      showHotCities: true,
      success: (res) => {
        my.alert({
          title: 'chooseCity response: ' + JSON.stringify(res),
        });
      },
    });
  },
  setLocatedCity() {
    my.onLocatedComplete({
      success: (res) => {
        my.setLocatedCity({
          locatedCityId:res.locatedCityId,//res.locatedCityId
          locatedCityName:'修改后的城市名', 
          success: (res) => {
            my.alert({ content: '修改当前定位城市成功' + JSON.stringify(res), });
          },
          fail: (error) => {
            my.alert({ content: '修改当前定位城市失败' + JSON.stringify(error), });
          },
        });
      },
      fail: (error) => {
        my.alert({ content: 'onLocatedComplete失败' + JSON.stringify(error), });
      }
    });
    my.chooseCity({
      showLocatedCity: true,
      showHotCities: true,
      setLocatedCity: true,
      success: (res) => {
        my.alert({
          title: 'chooseCity response: ' + JSON.stringify(res),
        });
      },
    });
  },
});

入参

Object 类型，属性如下：

属性	类型	必填	描述
showLocatedCity	Boolean	否	是否显示当前定位城市，默认 false。
showHotCities	Boolean	否	是否显示热门城市，默认 true。
setLocatedCity	Boolean	否	是否修改当前定位城市，默认 false，如果 showLocatedCity 为 false，此设置无效。
cities	Object Array	否	自定义城市列表，列表内对象字段见下方自定义城市列表 cities 表。
hotCities	Object Array	否	自定义热门城市列表，列表内对象字段同 cities。
customHistoryCities	Object Array	否	自定义历史访问城市列表，列表内对象字段同 cities。
success	Function	否	调用成功的回调函数。
fail	Function	否	调用失败的回调函数。
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）。

自定义城市列表 cities

cities 内对象字段如下所示：

属性	类型	必填	描述
city	String	是	城市名。
adCode	String	是	行政区划代码。不同行政区域对应的代码可参见中华人民共和国县以上行政区划代码。
spell	String	是	城市名对应拼音拼写，方便用户搜索。

示例代码：

//.js
my.chooseCity({
  cities: [
    {
      city: '朝阳区',
      adCode: '110105',
      spell: 'chaoyang'
    },
    {
      city: '海淀区',
      adCode: '110108',
      spell: 'haidian'
    },
    {
      city: '丰台区',
      adCode: '110106',
      spell: 'fengtai'
    },
    {
      city: '东城区',
      adCode: '110101',
      spell: 'dongcheng'
    },
    {
      city: '西城区',
      adCode: '110102',
      spell: 'xicheng'
    },
    {
      city: '房山区',
      adCode: '110111',
      spell: 'fangshan'
    }
  ],
  hotCities: [
    {
      city: '朝阳区',
      adCode: '110105'
    },
    {
      city: '海淀区',
      adCode: '110108'
    },
    {
      city: '丰台区',
      adCode: '110106'
    }
  ],
  success: (res) => {
    my.alert({
      content: res.city + ':' + res.adCode
    });
  },
});

success 回调函数

说明：如果用户没有选择任何城市，直接点击了返回，将不会触发回调函数。

属性	类型	描述
city	String	城市名。
adCode	String	行政区划代码。
longitude	Number	经度（注意：仅用户选择当前定位城市才会返回）。支付宝客户端 10.1.32 及以上版本开始支持。
latitude	Number	纬度（注意：仅用户选择当前定位城市才会返回）。支付宝客户端 10.1.32 及以上版本开始支持。

my.onLocatedComplete

简介

my.onLocatedComplete 是自定义 onLocatedComplete 函数，可以监听该页面地理位置定位完的回调，只针对 my.chooseCity 中属性 setLocatedCity 为 true 的情况。

使用限制

IDE 模拟器暂不支持调试，请以真机调试结果为准。

扫码体验

示例代码

<!-- API-DEMO page/API/choose-city/choose-city.axml-->
<view class="page">
  <view class="page-description">选择城市 API</view>
  <view class="page-section">
    <view class="page-section-title">my.chooseCity</view>
    <view class="page-section-demo">
      <button type="primary" onTap="chooseCity">选择城市</button>
    </view>
  </view>
  <view class="page-description">修改当前定位城市的名称 API</view>
  <view class="page-section">
    <view class="page-section-title">my.setLocatedCity</view>
    <view class="page-section-demo">
      <button type="primary" onTap="setLocatedCity">修改当前定位城市的名称</button>
    </view>
  </view>
</view>

// API-DEMO page/choose-city/choose-city.js
Page({
  chooseCity() {
    my.chooseCity({
      showLocatedCity: true,
      showHotCities: true,
      success: (res) => {
        my.alert({
          title: 'chooseCity response: ' + JSON.stringify(res),
        });
      },
    });
  },
  setLocatedCity() {
    my.onLocatedComplete({
      success: (res) => {
        my.setLocatedCity({
          locatedCityId:res.locatedCityId,//res.locatedCityId
          locatedCityName:'修改后的城市名', 
          success: (res) => {
            my.alert({ content: '修改当前定位城市成功' + JSON.stringify(res), });
          },
          fail: (error) => {
            my.alert({ content: '修改当前定位城市失败' + JSON.stringify(error), });
          },
        });
      },
      fail: (error) => {
        my.alert({ content: 'onLocatedComplete失败' + JSON.stringify(error), });
      }
    });
    my.chooseCity({
      showLocatedCity: true,
      showHotCities: true,
      setLocatedCity: true,
      success: (res) => {
        my.alert({
          title: 'chooseCity response: ' + JSON.stringify(res),
        });
      },
    });
  },
});

入参

属性	类型	描述
success	Function	调用成功的回调函数。
fail	Function	调用失败的回调函数。
complete	Function	调用结束的回调函数（调用成功、失败都会执行）。

返回值

属性	类型	描述
longitude	Number	当前定位城市经度。
latitude	Number	当前定位城市经度。
locatedCityId	String	当前定位城市 id，setLocatedCity 的时候带上。

返回值示例代码

{
    longitude:100.3,
    latitude:30.1,
    locatedCityId:""
}

my.setLocatedCity

简介

my.setLocatedCity 是用于修改 my.chooseCity 中的默认定位城市的名称的 API。

使用限制

IDE 模拟器暂不支持调试，请以真机调试结果为准。

扫码体验

示例代码

<!-- .axml -->
<view class="page">
  <view class="page-description">选择城市</view>
  <view class="page-section">
    <view class="page-section-title">chooseCity</view>
    <view class="page-section-demo">
      <button type="primary" onTap="chooseCity">选择城市</button>
      <button type="primary" onTap="noChooseCity">没有热门/当前城市</button>
      <button type="primary" onTap="selfChooseCity">自定义选择的城市</button>
      <button type="primary" onTap="self_chooseCity">自定义选择的城市</button>
      <button type="primary" onTap="setLocatedCity">setLocatedCity</button>
    </view>
  </view>
</view>

// .js
Page({
  data: {
    localcity: '天津',
  },
  chooseCity() {
    my.chooseCity({
      showLocatedCity: true,
      showHotCities: true,
      success: (res) => {
        my.alert({ title: `chooseAlipayContact response: ${JSON.stringify(res)}` })
      },
      fail: (error) => {
        my.alert({ content: `选择失败${JSON.stringify(error)}` })
      },
      complete: () => {
        my.showToast({ content: 'complete回调' })
      },
    })
  },
  noChooseCity() {
    my.chooseCity({
      showLocatedCity: false,
      showHotCities: false,
      success: (res) => {
        my.alert({ title: `操作成功: ${JSON.stringify(res)}` })
      },
      fail: (error) => {
        my.alert({ content: `选择失败${JSON.stringify(error)}` })
      },
    })
  },
  selfChooseCity() {
    my.chooseCity({
      cities: [
        {
          city: '朝阳区',
          adCode: '110105',
          spell: 'chaoyang',
        },
        {
          city: '海淀区',
          adCode: '110108',
          spell: 'haidian',
        },
        {
          city: '丰台区',
          adCode: '110106',
          spell: 'fengtai',
        },
        {
          city: '东城区',
          adCode: '110101',
          spell: 'dongcheng',
        },
        {
          city: '西城区',
          adCode: '110102',
          spell: 'xicheng',
        },
        {
          city: '房山区',
          adCode: '110111',
          spell: 'fangshan',
        },
      ],
      hotCities: [
        {
          city: '朝阳区',
          adCode: '110105',
        },
        {
          city: '海淀区',
          adCode: '110108',
        },
        {
          city: '丰台区',
          adCode: '110106',
        },
      ],
      success: (res) => {
        my.alert({ title: `操作成功: ${JSON.stringify(res)}` })
      },
      fail: (error) => {
        my.alert({ content: `选择失败${JSON.stringify(error)}` })
      },
    })
  },


  self_chooseCity() {
    my.chooseCity({
      showLocatedCity: true,
      showHotCities: true,
      cities: [
        {
          city: '朝阳区',
          adCode: '110105',
          spell: 'chaoyang',
        },
        {
          city: '海淀区',
          adCode: '110108',
          spell: 'haidian',
        },
        {
          city: '丰台区',
          adCode: '110106',
          spell: 'fengtai',
        },
        {
          city: '东城区',
          adCode: '110101',
          spell: 'dongcheng',
        },
        {
          city: '西城区',
          adCode: '110102',
          spell: 'xicheng',
        },
      ],
      hotCities: [
        {
          city: '朝阳区',
          adCode: '110105',
        },
        {
          city: '海淀区',
          adCode: '110108',
        },
        {
          city: '丰台区',
          adCode: '110106',
        },
      ],
      success: (res) => {
        my.alert({ title: `操作成功: ${JSON.stringify(res)}` })
      },
      fail: (error) => {
        my.alert({ content: `选择失败${JSON.stringify(error)}` })
      },
    })
  },


  multiLevelSelect() {
    my.multiLevelSelect({
      title: '请选择城市', // 级联选择标题
      list: [
        {
          name: '杭州市', // 条目名称
          subList: [
            {
              name: '西湖区',
              subList: [
                {
                  name: '文一路',
                },
                {
                  name: '文二路',
                },
                {
                  name: '文三路',
                },
              ],
            },
            {
              name: '滨江区',
              subList: [
                {
                  name: '滨河路',
                },
                {
                  name: '滨兴路',
                },
                {
                  name: '白马湖动漫广场',
                },
              ],
            },
          ], // 级联子数据列表
        },
      ],
      success: (result) => {
        console.log(result)
        my.alert({ content: `级联${JSON.stringify(result)}` })
      },
      fail: (error) => {
        my.alert({ content: `调用失败${JSON.stringify(error)}` })
      },
    })
  },


  setLocatedCity() {
    my.chooseCity({
      showLocatedCity: true,
      showHotCities: true,
      setLocatedCity: true,
      success: (res) => {
        this.setData({
          localcity: res.city,
        })
        my.alert({ title: `chooseAlipayContact response: ${JSON.stringify(res)}` })
      },
      fail: (error) => {
        my.alert({ content: `选择失败${JSON.stringify(error)}` })
      },
      complete: () => {
        my.showToast({ content: 'complete回调' })
      },
    })
    my.onLocatedComplete({
      success: (res) => {
        my.setLocatedCity({
          locatedCityId: res.locatedCityId,
          locatedCityName: this.data.localcity,
          success: (result) => {
            console.log(result)
          },
          fail: (error) => {
            my.alert({
              content: `修改当前定位城市失败${JSON.stringify(error)}`,
            })
          },
        })
      },
      fail: (error) => {
        my.alert({
          content: `onLocatedComplete失败${JSON.stringify(error)}`,
        })
      },
    })
  },
})

入参

属性	类型	必填	描述
locatedCityId	String	是	当前定位城市 ID，my.chooseCity 接口的 onLocatedComplete 返回。
locatedCityName	String	是	当前定位城市的名称。
locatedCityAdCode	String	否	当前定位城市的行政区划代码，不传值时以控件默认拿到的为准。
locatedCityPinyin	String	否	当前定位城市的拼音，不传值时以控件默认拿到的为准。
success	Function	否	调用成功的回调函数。
fail	Function	否	调用失败的回调函数。
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）。

success 返回值

属性	类型	描述
locatedCityName	String	当前定位城市的名称。

fail 返回值

属性	类型	描述
error	String	错误码。
errorMessage	String	错误描述。

错误码

错误码	描述	解决方案
11	参数类型错误。	检查参数类型是否正确。
12	必填参数为空。	请确认参数 locatedCityId、locatedCityName 是否已填写。
13	locatedCityId 不匹配。	请确保与 my.chooseCity 接口的 onLocatedComplete 的 locatedCityId 保持一致。

my.regionPicker

简介

my.regionPicker 是多级省市区选择器 API，自带省市区数据源。

使用限制

基础库 1.23.0 或更高版本；支付宝客户端 10.1.90 或更高版本，若版本较低，建议采取兼容处理。
IDE 模拟器暂不支持调试，请以真机调试结果为准。

示例代码

<!-- .axml -->
<view class="page">
  <view class="page-description">多级省市区选择器</view>
  <view class="page-section">
    <view class="page-section-title">regionPicker</view>
    <view class="page-section-demo">
      <button type="primary" onTap="regionPicker">选择城市</button>
    </view>
  </view>
</view>

Page({
    regionPicker() {
        my.regionPicker({
            mergeOptions: {


                // 新增
                add: [{
                    "pid": "1",
                    "name": "新省",
                    "nextId": "1111",
                    "id": "110000",
                    "subList": [{
                        "name": "北京市",
                        "id": "110100",
                        "subList": [{
                            "name": "东城区",
                            "id": "110101"
                        }]
                    }]
                }],


                // 删除
                remove: [{
                    "id": "110000"
                }],


                // 更新
                update: [{
                    "name": "北京",
                    "id": "110000",
                    "subList": [{
                        "name": "北京市",
                        "id": "110100",
                        "subList": [{
                            "name": "东城区",
                            "id": "110101"
                        }]
                    }]
                }]
            },
            success: (res) =>{
                my.alert({
                    title: 'regionPicker response: ' + JSON.stringify(res),
                })
              },
        });
      }
    })

入参

名称	类型	必填	描述
title	String	否	标题。
customItem	String	否	可为每一列的顶部添加一个自定义的选项。
mergeOptions	Object	否	自定义修改城市数据，支持删除、添加和更新城市信息。
selectedItem	Array	否	表示选中的省市区，默认选中每一列的第一个值
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数

mergeOptions 对象

说明： mergeOptions 对城市信息的删除、添加、更新操作不会全局生效，仅单次生效。

属性	类型	描述
remove	Array	删除城市信息。
add	Array	添加城市信息。
update	Array	更新城市信息

remove 对象

属性	类型	描述
id	String	需要移除的省份 ID。

add 对象

属性	类型	描述
pid	String	插入点之上的省份 ID。
nextId	String	插入点之下的省份 ID。
id	String	增加对象的 ID。
name	String	增加对象的名称。
subList	Array	省内完整的市和区信息。示例："subList": [{"name": "北京市","id": "110100","subList": [{"name": "东城区","id": "110101"}]

update 对象

属性	类型	描述
id	String	更新对象的 ID。
name	String	增加对象的名称。
subList	Array	省内完整的市和区信息。示例："subList": [{"name": "北京市","id": "110100","subList": [{"name": "东城区","id": "110101"}]

success 返回值

属性	类型	描述
data	Array	选择的省市区名称数组。

fail 返回值

属性	类型	描述
error	String	错误码。
errorMessage	String	错误描述。

错误码

错误码	说明	解决方案
11	用户取消选择	重新选择即可。
10001	用户没有选择数据	重新选中数据即可。