更新记录

1.0.0（2026-11-03）

腾讯地图选点

平台兼容性

uni-app x(4.31)

其他

dl-qqmap-picker 腾讯地图选点（uni-app x / UTS）

将「腾讯地图选点」封装为可复用的 uni_modules UTS 插件，以页面跳转方式使用：宿主调用 openLocationPicker() 跳转插件全屏选点页，选点结果以 Promise 返回。

特性

• 地图选点 + 周边推荐列表（腾讯地图 place/v1/explore）
• 底部面板可拖拽展开/折叠（占屏比例），地图与面板联动动画
• 独立搜索页（place/v1/suggestion），支持主地点与子地点、历史记录
• 全端适配：web 走 JSONP、APP 走 uni.request，传输差异封装在 common/mapHttp.uts
• 敏感配置（LBS key、检索半径等）全部由宿主传入，插件零硬编码
• 蒸汽（Vapor）模式兼容

安装

1. 将插件目录整体拷贝到宿主项目的 uni_modules/ 下，即得到 uni_modules/dl-qqmap-picker/。
2. 完成本 readme 的「宿主前置条件」。

使用（页面跳转模式）

import { openLocationPicker } from '@/uni_modules/dl-qqmap-picker/index.uts';
import type { PickedPoi } from '@/uni_modules/dl-qqmap-picker/common/index.uts';

const poi: PickedPoi | null = await openLocationPicker({
    mapKey: 'YOUR_TENCENT_LBS_KEY', // 必填
    initialLatitude: 39.90923,
    initialLongitude: 116.397428,
    searchRadius: 1000,
    showSearch: true,
});

if (poi != null) {
    console.log('选中的点位', poi);
} else {
    console.log('用户取消选点');
}

打开选点页参数（LocationPickerOptions）

选点结果（PickedPoi）

宿主页面注册

uni-app x 中 uni_modules 自带的页面也需在宿主 pages.json 显式注册，否则导航报 page is not found：

{
  "path": "uni_modules/dl-qqmap-picker/pages/map-picker/map-picker",
  "style": {
                // #ifndef MP-ALIPAY
                "navigationBarTitleText": "地图选点",
                "navigationStyle": "custom",
                // #endif
                // #ifdef MP-ALIPAY
                "allowsBounceVertical": "NO",
                "transparentTitle": "auto",
                // #endif
                "disableScroll": true
            }
},
{
  "path": "uni_modules/dl-qqmap-picker/pages/map-search/map-search",
  "style": {
                // #ifndef MP-ALIPAY
                "navigationBarTitleText": "地图选点",
                "navigationStyle": "custom",
                // #endif
                // #ifdef MP-ALIPAY
                "allowsBounceVertical": "NO",
                "transparentTitle": "auto",
                // #endif
                "disableScroll": true
            }
}

两页均建议 disableScroll: true、navigationStyle: "custom"（页面自带 dl-navbar 导航栏）。若宿主同时存在同名 dl-navbar 组件，需确认插件页面能解析到插件内 components/dl-navbar。

宿主前置条件

1. 地图模块与 key：在 manifest.json 配置 <map> 所需内容——
   • app-android / app-ios：勾选 uni-map 模块；
   • web：在 web.sdkConfigs.maps.tencent.key 配置腾讯地图 JS SDK key（用于 <map> 渲染）。
2. 位置权限：开启 <map> 与 uni.getLocation 所需的位置权限/隐私声明（APP 端遵循隐私政策）。
3. 选点页与搜索页用到的腾讯 WebService key（mapKey）在宿主运行时经 openLocationPicker 传入，非 manifest 配置项。

目录结构

dl-qqmap-picker/
├── index.uts                      # 入口：openLocationPicker(options)
├── package.json                   # uni_modules 插件元数据
├── readme.md
├── common/
│   ├── index.uts                  # 公共类型与常量
│   └── mapHttp.uts                # 平台差异 HTTP 传输（web JSONP / 其他 uni.request）
├── components/
│   └── dl-navbar/dl-navbar.uvue   # 插件自带导航栏
├── pages/
│   ├── map-picker/map-picker.uvue # 选点页（核心，全屏）
│   └── map-search/map-search.uvue # 独立搜索页
└── static/
    ├── point.png                  # 地图中心指针图标 由于uni-app x目前只支持unicode，故使用图片图标
    └── fonts/iconfont.ttf         # 图标字体（自包含）

已知限制 / 验证点

• uni_modules 页面路径与 easycom 自动注册依赖 uni-app x 的 uni_modules 规范，部署前请在宿主实际编译验证一次。
• iOS 端如果地图上提示‘鉴权失败，请检查你的Key’，请检查manifest.json配置的Key是否正确且授权并重新构建自定义基座。