更新记录

1.0.0（2026-11-05）

• 新增完整业务串联示例：搜索选择起终点、真实驾车分段预览、Navi独立重新算路并由用户启动模拟。
• 新增示例页面一次性交接归属与可信来源返回，旧页面迟到失败、隐藏与卸载不会清除后来准备的行程。
• 新增前台圆形围栏会话、真实SDK注册与关系观察、精确自有移除、状态和能力查询及完整示例；首条关系可能是初始状态，不提供后台或进程恢复。
• 新增围栏原始超时预算、迟到隔离、隐藏/撤隐私清理及鸿蒙定位/导航双向资源门禁，区分SDK名单观察与系统资源停止。
• 新增插件屏幕网格聚合、原生热力瓦片和海量点层，支持独立显隐、替换、读取、移除与点击关联。
• 新增专属点沿输入路径移动、真实SDK活动和终态、按请求停止，以及地图区域临时PNG、完整度三态和自有图片回收。
• 新增高级地图能力/实例状态、标准组件13方法与advanced-event，以及完整地图进阶演示；取消后的未确认原生管线继续保留占用。
• 新增离线城市目录、单项下载/暂停/恢复/删除、真实阶段和缓存状态、会话身份与退出清理，以及完整离线地图演示；SDK 11+ 需高阶服务授权。
• 新增驾车巡航启动、停止、真实统计/设施/电子眼/拥堵事件与独立位置确认，复用标准导航组件。
• 新增导航和巡航内置播报初始配置、运行开关与真实配置读取。
• 新增独立中文系统语音、按请求停止、能力和占用查询、隐藏/撤回隐私清理及完整巡航语音演示。
• 新增隐私配置、原生 SDK 初始化和重复初始化处理。
• 新增平台能力与运行状态查询。
• 新增 uni-app x 首页与接入配置演示页。
• 新增三端原生地图标准组件、相机控制、可视区域与地图类型切换。
• 新增实时路况、指南针、比例尺、统一缩放按钮及四类手势配置。
• 新增地图加载、相机变化、点击、长按、错误与销毁事件。
• 新增独立多实例、暂停恢复、销毁重建及隐私撤回时统一清理。
• 新增地图三标签演示页与统一线性图标资源。
• 新增前台定位权限检查、权限申请、应用授权设置及单次定位。
• 新增定位请求 ID、取消、超时、同类排它与迟到结果处理。
• 新增定位坐标、精度、可用运动指标和地址结果，附定位演示页。
• 新增按类型与 ID 管理标记、折线、圆和多边形，支持完整替换、样式、显隐与清理。
• 新增本地 PNG/JPEG 图片标记、实际位置读取、标记点击、气泡点击与拖动事件。
• 新增默认气泡控制、覆盖物能力与实际清单、坐标范围适配及覆盖物演示页。
• 新增前台持续与后台定位会话、运行条件检查、通知许可申请及按会话启停。
• 新增原生有界轨迹、状态与位置事件、前后台恢复、首点期限和隐私撤回清理。
• 新增持续定位多标签演示页、实际轨迹地图及鸿蒙宿主后台能力配置示例。
• 新增输入提示、新版POI关键词/周边/矩形/多边形搜索、单地点详情及五组扩展字段。
• 新增搜索请求ID、并发关联、超时/取消/迟到隔离、原生等待与retired状态查询及能力边界。
• 新增地点搜索完整示例、真实列表/地图/详情联动、分页与统一图标。
• 新增正向/逆向地理编码、结构化地址与周边道路/路口/POI/AOI、行政区树和完整边界查询。
• 新增多起点距离矩阵、逐项错误与输入编号关联、独立地理请求取消/超时/回执状态。
• 新增SDK距离/面积计算、来源坐标至GCJ-02转换，以及地图实例本地逻辑像素双向投影。
• 新增地理信息三标签与地图工具四标签完整示例，提供嵌套结果分页、行政树和边界浏览、真实地图联动及首页入口。
• 新增驾车、步行、骑行、公交和货车原生路线规划，支持策略、多方案、途经点、避让和车辆参数。
• 新增完整路段、交通/城市扩展、公交步行/线路备选/铁路/出租及出入口结果，保留空值和单位来源。
• 新增独立路线请求取消/超时/隐私处理、能力与资源状态，以及五种方式完整演示和真实分段地图预览。
• 新增驾车导航标准组件、Navi独立算路与真实路径组、行前预览与选路、GPS和模拟模式、内置导航语音及核心状态事件。
• 新增导航概览、跟随、路况、取消等待、前台退出与结束重建、纯能力/占用查询及导航配置/展示完整示例。
• 新增步行、骑行和燃油货车导航，按出行方式应用真实算路、预览选路、GPS/模拟与原生视图。
• 新增各方式速度与交通图层能力、完整货车尺寸重量参数、固定方式实例和状态结果关联。

平台兼容性

uni-app(5.34)

uni-app x(5.34)

lizhao 高德地图

为 uni-app x 提供高德原生地图、覆盖物与高级图层、前台及后台定位、地点和地理信息查询、五种方式路线规划、驾车/步行/骑行/燃油货车 GPS 与模拟导航、巡航、系统语音、离线底图与前台圆形围栏。包含测量、坐标转换、地图截图及搜索到模拟导航的完整示例，使用统一隐私、初始化和错误处理接口。

功能特色

适合哪些场景

下载与导入

从基础到进阶

基础功能配置示例（简单示例）

在 uni-app x 页面按钮中调用。apiKey 替换为宿主的当前平台 Key，隐私状态必须来自宿主实际展示和用户选择。

import { setMapPrivacy, initializeMap } from '@/uni_modules/lizhao-map'

function configureMap(apiKey: string) {
  try {
    setMapPrivacy({ shown: true, contains: true, agreed: true })
    const result = initializeMap({ apiKey: apiKey })
    console.log(result.errMsg, result.platform, result.sdkVersion)
    console.log(result.initialized, result.authVerified)
  } catch (error) {
    const failure = error as IUniError
    console.log(failure.errSubject, failure.errCode, failure.errMsg)
    console.log(failure.data, failure.cause)
  }
}

initialized=true 表示本地 SDK 配置完成。authVerified 当前始终为 false；插件不会根据配置或地图/定位回调推断已完成独立 Key 鉴权。实际 SDK 服务错误可通过请求结果和数字诊断检查。

高级示例

先在接入页完成隐私与初始化，然后在页面中放置地图。父容器须有明确高度。ready 来自原生地图加载回调，不表示联网鉴权已经得到独立验证。

<template>
  <view class="map-area">
    <LizhaoMap @map-event="onMapEvent" />
  </view>
</template>

<script setup lang="ts">
import LizhaoMap from '@/uni_modules/lizhao-map/components/lizhao-map/lizhao-map.uvue'
import type { MapEventDetail } from '@/uni_modules/lizhao-map'

function onMapEvent(event: MapEventDetail): void {
  if (event.type === 'ready') console.log('地图已就绪', event.instanceId)
  if (event.type === 'error') console.log(event.errCode, event.errMsg)
}
</script>

<style>
.map-area { height: 300px; }
</style>

以下查询可用于页面恢复。availableFeatures 仅列出本插件当前开放的功能。

import { getMapStatus, getMapCapabilities } from '@/uni_modules/lizhao-map'

function inspectMap() {
  const status = getMapStatus()
  console.log(status.platform, status.sdkVersion)
  console.log(status.initialized, status.keyConfigured, status.authVerified)
  console.log(status.privacy.shown, status.privacy.contains, status.privacy.agreed)

  const capabilities = getMapCapabilities()
  console.log(capabilities.platform, capabilities.supported)
  console.log(capabilities.availableFeatures, capabilities.minimumOSVersion)
  console.log(capabilities.coordinateType)
  if (!capabilities.supported) {
    console.log('请在支持的平台使用原生接入功能')
  }
}

进阶示例

使用组件 ref 操作同一个实例。以下函数分别演示标准、卫星、夜间三种地图，以及合法的 0 和 false。提交完整参数对象，实际缩放和角度可能受平台 SDK 限制，应读取实际结果。

import type { MapViewContext, MapType } from '@/uni_modules/lizhao-map'

function changeMap(context: MapViewContext, mapType: MapType): void {
  context.setCamera({ latitude: 31.2304, longitude: 121.4737, zoom: 13, tilt: 0, bearing: 0 })
  context.setOptions({
    mapType: mapType, traffic: false, compass: true, scale: true,
    gestures: { scroll: true, zoom: true, rotate: false, tilt: false }
  })
}

function compareLayers(context: MapViewContext): void {
  changeMap(context, 'normal')
  // 在对应按钮中分别调用，切换后观察地图。
  // changeMap(context, 'satellite')
  // changeMap(context, 'night')
}

隐私撤回会使初始化状态失效，并销毁本插件已经创建的所有地图。以下三个配置分别演示缺少展示、缺少高德说明和用户拒绝，实际业务只提交当前真实状态。再次同意并初始化后，需要移除旧组件并创建新组件。

import { setMapPrivacy, getMapStatus } from '@/uni_modules/lizhao-map'

function demonstratePrivacyStates() {
  setMapPrivacy({ shown: false, contains: false, agreed: false })
  console.log(getMapStatus().initialized)
  setMapPrivacy({ shown: true, contains: false, agreed: false })
  console.log(getMapStatus().privacy.contains)
  setMapPrivacy({ shown: true, contains: true, agreed: false })
  console.log(getMapStatus().privacy.agreed)
}

完整示例

以下为可放入 .uvue 的地图操作页。先在接入配置页初始化。相机属性是目标值，事件读数单独保存，避免拖动地图时反复回写目标。

<template>
  <view class="demo">
    <view class="map-area">
      <LizhaoMap v-if="mounted" :key="generation" ref="map"
        :camera="camera" :options="options" :active="active" :zoom-controls="true"
        @map-event="onMapEvent" />
    </view>
    <text>{{ message }}</text>
    <text>{{ actualCamera }}</text>
    <text>{{ boundsText }}</text>
    <text>{{ pointText }}</text>
    <button :disabled="!ready" @click="applyConfiguration">应用相机和图层</button>
    <button :disabled="!ready" @click="inspectView">读取实际相机和范围</button>
    <button :disabled="!ready" @click="toggleActive">{{ active ? '暂停地图' : '恢复地图' }}</button>
    <button :disabled="!mounted" @click="removeMap">销毁地图</button>
    <button :disabled="rebuilding" @click="rebuildMap">重建地图</button>
  </view>
</template>

<script setup lang="ts">
import { ref, nextTick, onUnmounted } from 'vue'
import { onShow, onHide, onUnload } from '@dcloudio/uni-app'
import LizhaoMap from '@/uni_modules/lizhao-map/components/lizhao-map/lizhao-map.uvue'
import { getMapStatus } from '@/uni_modules/lizhao-map'
import type { MapCamera, MapEventDetail, MapViewContext, MapViewOptions } from '@/uni_modules/lizhao-map'

const map = ref<MapViewContext | null>(null)
const mounted = ref(false)
const generation = ref(0)
const rebuilding = ref(false)
const active = ref(true)
const ready = ref(false)
const message = ref('请先完成接入配置')
const actualCamera = ref('')
const boundsText = ref('')
const pointText = ref('')
const camera = ref<MapCamera>({ latitude: 39.9042, longitude: 116.4074, zoom: 12, tilt: 0, bearing: 0 })
const options = ref<MapViewOptions>({
  mapType: 'normal', traffic: false, compass: true, scale: true,
  gestures: { scroll: true, zoom: true, rotate: true, tilt: true }
})
let leaving = false

function onMapEvent(event: MapEventDetail): void {
  if (leaving) return
  if (event.type === 'error') {
    if (event.errCode !== 9101009) ready.value = false
    message.value = `${event.errCode}: ${event.errMsg}`
    return
  }
  message.value = `${event.instanceId}: ${event.type}`
  if (event.type === 'ready') ready.value = true
  if (event.type === 'destroyed') ready.value = false
  if (event.type === 'ready' || event.type === 'camera-change') {
    actualCamera.value = `${event.latitude}, ${event.longitude}; zoom=${event.zoom}, tilt=${event.tilt}, bearing=${event.bearing}`
  }
  if (event.type === 'map-click' || event.type === 'map-long-press') {
    pointText.value = `${event.type}: ${event.pointLatitude}, ${event.pointLongitude}`
  }
}

function withMap(operation: (context: MapViewContext) => void): void {
  const context = map.value
  if (context === null || !ready.value) return
  try {
    operation(context)
  } catch (error) {
    const failure = error as IUniError
    message.value = `${failure.errCode}: ${failure.errMsg}`
  }
}

function applyConfiguration(): void {
  camera.value = { latitude: 31.2304, longitude: 121.4737, zoom: 13, tilt: 30, bearing: 90 }
  options.value = { ...options.value, mapType: 'night', traffic: true }
  withMap(context => {
    context.setCamera(camera.value)
    context.setOptions(options.value)
  })
}

function inspectView(): void {
  withMap(context => {
    const value = context.getCamera()
    const bounds = context.getBounds()
    actualCamera.value = `${value.latitude}, ${value.longitude}; zoom=${value.zoom}, tilt=${value.tilt}, bearing=${value.bearing}`
    boundsText.value = `西南 ${bounds.southwest.latitude}, ${bounds.southwest.longitude}; 东北 ${bounds.northeast.latitude}, ${bounds.northeast.longitude}`
  })
}

function toggleActive(): void {
  active.value = !active.value
  withMap(context => context.setActive(active.value))
}

function removeMap(): void {
  try { map.value?.destroy() }
  catch (_) { message.value = '销毁异常，请检查原生环境' }
  finally { mounted.value = false; ready.value = false }
}

async function rebuildMap(): Promise<void> {
  if (rebuilding.value || leaving) return
  rebuilding.value = true
  mounted.value = false
  ready.value = false
  try {
    await nextTick()
    if (leaving) return
    generation.value += 1
    mounted.value = getMapStatus().initialized
    message.value = mounted.value ? '等待地图就绪' : '请先完成接入配置'
  } finally { rebuilding.value = false }
}

onShow(() => {
  active.value = true
  if (!mounted.value && getMapStatus().initialized) mounted.value = true
})
onHide(() => { active.value = false })
onUnload(() => { leaving = true })
onUnmounted(() => { active.value = false; mounted.value = false; map.value = null })
</script>

<style>
.demo { flex: 1; padding: 16px; }
.map-area { height: 300px; }
</style>

完整输入表单、三类地图切换、手势开关、第二实例、事件读数和有容量限制的日志见 example/uniappx/map.uvue。

单次定位与地图初始化分别调用。先在接入配置页同意真实隐私政策并初始化，然后检查/申请权限，最后由用户点击获取一次位置。权限拒绝会作为 success 中的真实权限状态返回；只有定位失败才调用该定位请求的 fail。

import { getMapLocationPermission, requestMapLocationPermission, getMapLocation,
  cancelMapLocationRequest, openMapLocationSettings } from '@/uni_modules/lizhao-map'
import type { MapLocationResult, MapFail } from '@/uni_modules/lizhao-map'

function inspectPermission(): void {
  const result = getMapLocationPermission()
  console.log(result.requestId, result.platform, result.state)
  console.log(result.accuracy, result.serviceEnabled, result.canAskAgain)
}

function requestPermission(): string {
  return requestMapLocationPermission({
    timeoutMs: 60000,
    success: result => {
      console.log(result.requestId, result.state, result.accuracy)
      if (result.state === 'granted') console.log('可以由用户主动获取位置')
      else if (result.canAskAgain) console.log('用户准备好后可再次申请')
      else console.log('请查看应用授权设置或系统限制')
    },
    fail: showFailure,
    complete: () => console.log('权限等待结束')
  })
}

function locateOnce(): string {
  return getMapLocation({
    accuracy: 'high', timeoutMs: 10000, needAddress: false,
    success: showLocation,
    fail: showFailure,
    complete: () => console.log('本次定位请求结束')
  })
}

function showLocation(result: MapLocationResult): void {
  console.log(result.requestId, result.platform, result.coordinateType)
  console.log(result.latitude, result.longitude, result.accuracy)
  console.log(result.altitude ?? '未返回', result.speed ?? '未返回', result.bearing ?? '未返回')
  console.log(result.timestamp == null ? '未返回时间' : new Date(result.timestamp).toISOString())
  console.log(result.provider, result.isMock == null ? '未提供模拟标记' : result.isMock)
  const address = result.address
  if (address !== null) {
    console.log(address.formattedAddress, address.country, address.province, address.city, address.district)
    console.log(address.street, address.streetNumber, address.adCode, address.cityCode, address.poiName)
  } else console.log('未请求或未返回地址')
}

function showFailure(error: MapFail): void {
  const diagnostic = error.data as { requestId?: string; nativeErrorCode?: number | null } | null
  console.log(error.errSubject, error.errCode, error.errMsg)
  console.log(diagnostic?.requestId, diagnostic?.nativeErrorCode)
  if (error.errCode === 9101014) console.log('已取消等待')
  if (error.errCode === 9101012) console.log('请在系统设置中开启定位服务，再返回检查')
}

function cancelRequest(requestId: string): void {
  cancelMapLocationRequest(requestId)
}

function openApplicationSettings(): string {
  return openMapLocationSettings({
    success: result => console.log(result.requestId, result.platform, result.opened),
    fail: showFailure,
    complete: () => console.log('设置跳转请求结束，返回页面后重新检查权限')
  })
}

将返回的请求 ID 保存在页面实例内，取消时传回该 ID。回调保证在调用返回后交付；同类请求在进程内排它，未结束时再次发起返回 9101016。设置请求成功仅表示系统受理跳转，不表示用户已经改过授权。

在需要地址的按钮中调用 getMapLocation({ accuracy: 'balanced', timeoutMs: 20000, needAddress: true, success: showLocation, fail: showFailure })。请求精度是期望策略，实际精度与系统精确/大致授权分别显示。Android 大致权限下，balanced 自动使用可工作的单次策略，不扩大 OS 授权。

等待地图 ready 后，在同一个 ref 上绘制与更新。iconBase64 传入本地 PNG/JPEG 的 base64 内容；不填写时使用 SDK 默认标记。以下函数放入页面脚本，由按钮或 ready 分支调用，不能在组件创建前调用。

import type { MapViewContext, MapEventDetail, MapMarkerIcon } from '@/uni_modules/lizhao-map'

function drawOverlays(context: MapViewContext, iconBase64: string): void {
  const icon: MapMarkerIcon | null = iconBase64 === '' ? null : { imageBase64: iconBase64, width: 32, height: 32 }
  try {
    context.upsertMarkers([
      { id: 'start', position: { latitude: 39.9042, longitude: 116.4074 },
        title: '起点', snippet: '长按拖动后查看真实坐标', visible: true, draggable: true,
        rotation: 0, opacity: 1, zIndex: 2, anchorX: 0.5, anchorY: 1, icon: icon },
      { id: 'end', position: { latitude: 39.9142, longitude: 116.4274 }, title: '终点', snippet: '第二个标记' }
    ])
    context.upsertPolylines([{ id: 'path', points: [
      { latitude: 39.9042, longitude: 116.4074 }, { latitude: 39.9092, longitude: 116.4174 },
      { latitude: 39.9142, longitude: 116.4274 }
    ], strokeColor: '#14878f', strokeWidth: 4, strokeOpacity: 0.8, dashed: true, visible: true, zIndex: 1 }])
    context.upsertCircles([{ id: 'service', center: { latitude: 39.9092, longitude: 116.4174 }, radius: 600,
      strokeColor: '#14878f', strokeWidth: 2, strokeOpacity: 1, fillColor: '#14878f', fillOpacity: 0.18,
      visible: true, zIndex: 0 }])
    context.upsertPolygons([{ id: 'area', points: [
      { latitude: 39.9022, longitude: 116.4114 }, { latitude: 39.9072, longitude: 116.4114 },
      { latitude: 39.9072, longitude: 116.4214 }, { latitude: 39.9022, longitude: 116.4214 }
    ], strokeColor: '#c66a28', strokeWidth: 2, strokeOpacity: 1, fillColor: '#c66a28', fillOpacity: 0.15,
      visible: true, zIndex: 1 }])
    context.fitCoordinates([
      { latitude: 39.8992, longitude: 116.4014 }, { latitude: 39.9192, longitude: 116.4334 }
    ], 32)
    const capability = context.getOverlayCapabilities()
    console.log(capability.multipleCallouts, capability.customMarkerImage, capability.markerDrag)
    context.setMarkerCallout('start', true, true)
    if (capability.multipleCallouts) context.setMarkerCallout('end', true, false)
    else console.log('当前只支持单个默认气泡，再打开一个会替换前一个')
    const summary = context.getOverlaySummary()
    console.log(summary.markerIds, summary.polylineIds, summary.circleIds, summary.polygonIds)
  } catch (error) {
    const failure = error as IUniError
    console.log(failure.errCode, failure.errMsg)
  }
}

function onOverlayEvent(context: MapViewContext, event: MapEventDetail): void {
  const id = event.overlayId ?? ''
  if (event.type === 'marker-click' || event.type === 'marker-callout-click') {
    console.log(event.instanceId, event.overlayType, id, event.pointLatitude, event.pointLongitude)
  }
  if (event.type === 'marker-drag-start' || event.type === 'marker-drag' || event.type === 'marker-drag-end') {
    console.log(event.type, id, event.pointLatitude, event.pointLongitude)
  }
  if (event.type === 'marker-drag-end' && id !== '') {
    try {
      const actual = context.getMarkerPosition(id)
      console.log('拖动后原生读数', actual.latitude, actual.longitude)
    } catch (error) { console.log((error as IUniError).errCode) }
  }
}

function updateAndRemoveOverlays(context: MapViewContext): void {
  try {
    const position = context.getMarkerPosition('start')
    context.setMarkerCallout('start', false)
    // 整条替换而非局部 patch；0 和 false 都是有效值。
    context.upsertMarkers([{ id: 'start', position: position, visible: false, opacity: 0,
      rotation: 0, draggable: false, anchorX: 0, anchorY: 0, zIndex: 0, icon: null }])
    context.removeOverlays([{ type: 'polyline', id: 'path' }, { type: 'circle', id: 'service' }, { type: 'polygon', id: 'area' }])
    console.log(context.getOverlaySummary().markerIds)
    context.clearOverlays()
    console.log(context.getOverlaySummary())
  } catch (error) { console.log((error as IUniError).errCode, (error as IUniError).errMsg) }
}

upsert 按当前地图、覆盖物类型和 ID 定位对象，是整条替换：省略 title、icon 或样式时恢复默认。隐藏标记会关闭其气泡。移除不存在 ID 是空操作；读取不存在标记返回 9101017。默认气泡是否能同时显示多个以 getOverlayCapabilities 为准，不支持时用 exclusive=false 请求显示会明确失败；关闭不受此限制。

持续定位由用户在前台点击后启动，不隐式申请定位或通知许可。先在定位示例完成前台授权。以下示例适用于已完成隐私和 SDK 初始化的页面；后台模式先核对真实条件，配置未知时仍须由系统正式启动校验。

import { ref } from 'vue'
import { onShow, onHide, onUnload } from '@dcloudio/uni-app'
import {
  startMapLocationSession, stopMapLocationSession, getMapLocationSessionState,
  getMapLocationSessionTrack, clearMapLocationSessionTrack,
  getMapLocationBackgroundStatus, requestMapLocationNotificationPermission,
  cancelMapLocationRequest
} from '@/uni_modules/lizhao-map'
import type { MapLocationSessionTrack, MapFail } from '@/uni_modules/lizhao-map'

const track = ref<MapLocationSessionTrack | null>(null)
const message = ref('尚未开始')
let ownedSessionId = ''
let notificationRequestId = ''
let pageVisible = true
let disposed = false

function explain(error: MapFail) {
  if (!disposed && pageVisible) message.value = error.errCode.toString() + ' · ' + error.errMsg
}

// 绑定到独立“申请通知”按钮；拒绝作为正常状态返回。iOS为not-required。
function requestNotification() {
  if (notificationRequestId.length > 0) return
  notificationRequestId = requestMapLocationNotificationPermission({
    timeoutMs: 60000,
    success: result => {
      if (!disposed && pageVisible) message.value = result.state +
        '；频道=' + (result.channelEnabled == null ? '不适用或尚未创建' : result.channelEnabled ? '已开启' : '已关闭') +
        '；可再次申请=' + result.canAskAgain.toString()
    },
    fail: explain,
    complete: () => { notificationRequestId = '' }
  })
}

function begin(background: boolean) {
  try {
    if (background) {
      const access = getMapLocationBackgroundStatus()
      message.value = access.reason + '；配置=' + access.configurationState
      if (!access.supported || !access.canStart) return
      // requiresSettings=true时由用户单独点击openMapLocationSettings进入系统设置。
    }
    ownedSessionId = startMapLocationSession({
      mode: background ? 'background' : 'foreground', accuracy: 'high',
      intervalMs: 2000, distanceFilter: 0, needAddress: false,
      startupTimeoutMs: 10000, maxPoints: 500,
      androidNotification: { id: 2611706, title: '位置记录进行中', text: '正在使用位置信息，点击返回应用' },
      onEvent: event => {
        if (disposed || !pageVisible) return
        const state = event.state
        message.value = state.phase + '；累计=' + state.receivedPointCount.toString() +
          '；保留=' + state.storedPointCount.toString() + '；未保留=' + state.discardedPointCount.toString()
        if (event.type == 'error' && event.error != null) explain(event.error)
        if (event.type == 'location' && event.point != null) {
          const point = event.point
          // receivedAt是接收时间；location.timestamp为原始位置时间，可能为null或0。
          const fix = point.location
          message.value = fix.latitude.toString() + ',' + fix.longitude.toString() +
            '；精度=' + fix.accuracy.toString() + '米；序号=' + point.sequence.toString()
        }
      }
    })
  } catch (error) { explain(error as MapFail) }
}

function readTrack() {
  if (ownedSessionId.length == 0) return
  try { track.value = getMapLocationSessionTrack(ownedSessionId) }
  catch (error) { explain(error as MapFail) }
}
function clearTrack() {
  if (ownedSessionId.length == 0) return
  try { clearMapLocationSessionTrack(ownedSessionId); readTrack() }
  catch (error) { explain(error as MapFail) }
}
function stop() {
  if (ownedSessionId.length == 0) return
  try { stopMapLocationSession(ownedSessionId); readTrack() }
  catch (error) { explain(error as MapFail) }
}

onHide(() => { pageVisible = false })
onShow(() => {
  pageVisible = true
  if (disposed) return
  try {
    const state = getMapLocationSessionState()
    if (state.sessionId == ownedSessionId && ownedSessionId.length > 0) {
      message.value = state.phase + '；停止原因=' + state.stopReason
      readTrack() // 补齐后台期间原生缓存的点；不依赖后台JS定时器。
    }
  } catch (error) { explain(error as MapFail) }
})
onUnload(() => {
  disposed = true
  pageVisible = false
  if (notificationRequestId.length > 0) cancelMapLocationRequest(notificationRequestId)
  if (ownedSessionId.length > 0) stopMapLocationSession(ownedSessionId)
})

begin(false)只在前台持续；App退后台会停止。begin(true)在满足条件时继续原生定位，不承诺进程被系统终止后恢复。停止可能先进入stopping，待 SDK 与系统后台资源真实释放后才进入终态，此时重新开始前仍会返回9101016。轨迹最多2000点；应用长期存档应自行在前台按序号导出。

单次定位的成功或取消回调表示结果等待已结束，底层 SDK 可能仍在清理。若紧接着开始新的单次或持续定位收到9101016，应等待资源释放后重试，不能通过重复创建管理器绕过互斥。

地点搜索不需要先申请定位权限。以下输入中心均为手动查询条件，返回地点只有在 position !== null 时才能绘制。先在配置页完成真实隐私同意和当前平台 Key 初始化，再按按钮调用四种模式之一。

import { searchMapPois } from '@/uni_modules/lizhao-map'
import type { MapPoiSearchMode, MapPoiSearchOptions, MapPoiSearchResult } from '@/uni_modules/lizhao-map'

function queryPlaces(mode: MapPoiSearchMode, page: number,
  showResult: (result: MapPoiSearchResult) => void): string {
  const options: MapPoiSearchOptions = {
    mode, keyword: '咖啡', types: '050000', page, pageSize: 20,
    includeFields: ['children', 'business', 'indoor', 'navi', 'photos'], timeoutMs: 10000,
    success: result => {
      console.log(result.requestId, result.platform, result.coordinateType)
      console.log(result.query, result.count, result.items.length)
      // count 保留 SDK 原始计数；当前页为空不等于请求失败。
      if (result.items.length === 0) console.log('本页没有地点，请调整条件或返回上一页')
      if (result.suggestions !== null) {
        console.log(result.suggestions.keywords)
        for (const city of result.suggestions.cities) {
          console.log(city.name, city.cityCode, city.adCode, city.count)
        }
      }
      showResult(result)
    },
    fail: error => console.log(error.errCode, error.data),
    complete: () => console.log('本次等待结束')
  }
  if (mode === 'keyword') {
    options.city = '杭州'; options.cityLimit = true
    options.center = { latitude: 30.2741, longitude: 120.1551 }; options.sort = 'distance'
  } else if (mode === 'nearby') {
    options.keyword = ''; options.types = ''; options.city = ''; options.cityLimit = false
    options.center = { latitude: 30.2741, longitude: 120.1551 }
    options.radius = 0; options.sort = 'distance'
    // radius=0 原样传给 SDK，不回退为3000；是否有地点以服务响应为准。
  } else if (mode === 'rectangle') {
    options.sort = 'comprehensive'
    options.rectangle = {
      southWest: { latitude: 30.25, longitude: 120.13 },
      northEast: { latitude: 30.29, longitude: 120.18 }
    }
  } else {
    options.sort = 'comprehensive'
    options.polygon = [
      { latitude: 30.25, longitude: 120.13 },
      { latitude: 30.29, longitude: 120.13 },
      { latitude: 30.29, longitude: 120.18 },
      { latitude: 30.25, longitude: 120.18 }
    ] // 公开参数不重复首尾；插件在需要的 SDK 边界闭合。
  }
  return searchMapPois(options)
}

// 四个按钮分别调用 queryPlaces('keyword'/'nearby'/'rectangle'/'polygon', 1, showResult)。
// 翻页时使用成功结果的 query 条件与 query.page + 1；条件改变后重置为第1页。

提示可能是品牌词、线路或地点。不要把提示名称当成坐标；仅有 ID 的提示也不保证可用于 POI 详情。详情使用实际搜索结果 ID，并按 requestId 关联请求；原厂可能返回别名 poi.id。

import { getMapInputTips, getMapPoiDetail } from '@/uni_modules/lizhao-map'
import type { MapPoi, MapInputTip } from '@/uni_modules/lizhao-map'

function readPoi(poi: MapPoi): void {
  console.log(poi.id, poi.name, poi.type, poi.typeCode, poi.address)
  console.log(poi.province, poi.provinceCode, poi.city, poi.cityCode, poi.district, poi.adCode)
  console.log(poi.position, poi.distanceToCenterMeters) // null不变成0；估算距离不是路线距离。
  if (poi.business !== null) {
    const value = poi.business
    console.log(value.businessArea, value.openingHoursToday, value.openingHoursWeek)
    console.log(value.telephone, value.tags, value.rating, value.averageCost)
    console.log(value.parkingType, value.alias, value.cpId) // 评分/消费保留SDK文本。
  }
  if (poi.indoor !== null) {
    console.log(poi.indoor.hasIndoorMap, poi.indoor.poiId, poi.indoor.floor, poi.indoor.floorName)
    // floor=0、hasIndoorMap=false均为合法值；floor=null表示SDK未提供。
  }
  if (poi.navi !== null) console.log(poi.navi.poiId, poi.navi.entry, poi.navi.exit, poi.navi.gridCode)
  for (const child of poi.children) {
    console.log(child.id, child.name, child.address, child.type, child.typeCode, child.position)
  }
  for (const photo of poi.photos) console.log(photo.title, photo.url)
}
function requestDetail(realPoiId: string): string {
  return getMapPoiDetail({
    id: realPoiId, includeFields: ['children', 'business', 'indoor', 'navi', 'photos'], timeoutMs: 15000,
    success: result => {
      console.log(result.requestId, result.platform, result.coordinateType)
      console.log(result.requestedId, result.includeFields); readPoi(result.poi)
    },
    fail: error => console.log(error.errCode === 9101021 ? '未找到此地点' : '详情失败', error.errCode, error.data),
    complete: () => console.log('详情等待结束')
  })
}
function requestTips(selectTip: (tip: MapInputTip) => void): string {
  return getMapInputTips({
    keyword: '咖啡', city: '杭州', cityLimit: false, types: '050000',
    center: { latitude: 30.2741, longitude: 120.1551 }, timeoutMs: 10000,
    success: result => {
      console.log(result.requestId, result.platform, result.coordinateType)
      console.log(result.keyword, result.city, result.cityLimit, result.types, result.center)
      if (result.tips.length === 0) console.log('提示为空，请换一个关键词')
      for (const tip of result.tips) {
        console.log(tip.id, tip.name, tip.district, tip.adCode, tip.address, tip.typeCode, tip.position)
        selectTip(tip) // 交给列表选择；position=null时只允许按词继续搜索。
      }
    },
    fail: error => console.log(error.errCode, error.data),
    complete: () => console.log('提示等待结束')
  })
}

页面应只取消自己持有的 ID。下例可放入页面脚本，展示并发隔离、重复查询保护、地图联动、迟到结果隔离和退出清理。将 showPage(context) 绑定搜索按钮，把地图 ready 后得到的 ref 传入；列表选择调用 choose(index, context)，并由界面单独展示列表与错误。

import { onHide, onShow, onUnload } from '@dcloudio/uni-app'
import { searchMapPois, cancelMapSearchRequest, getMapSearchCapabilities, getMapSearchState } from '@/uni_modules/lizhao-map'
import type { MapViewContext, MapPoi, MapFail } from '@/uni_modules/lizhao-map'

let visible = true, disposed = false, generation = 0
let ownedRequestId = '', items: MapPoi[] = []
function inspectSearch(): void {
  const capabilities = getMapSearchCapabilities()
  console.log(capabilities.platform, capabilities.supported, capabilities.inputTips, capabilities.poiModes)
  console.log(capabilities.poiDetail, capabilities.optionalFields, capabilities.poiSuggestions)
  console.log(capabilities.cancellation, capabilities.maxPage, capabilities.maxPageSize)
  console.log(capabilities.maxPolygonVertices, capabilities.maxPendingRequests, capabilities.note)
  const state = getMapSearchState()
  console.log(state.platform, state.pendingRequestIds, state.retiredRequestCount, state.maxPendingRequests)
}
function cancelOwned(): void {
  generation++
  const id = ownedRequestId; ownedRequestId = ''
  if (id !== '') cancelMapSearchRequest(id)
}
function showPage(context: MapViewContext): void {
  if (!visible || disposed || ownedRequestId !== '') return
  const current = ++generation
  try {
    ownedRequestId = searchMapPois({
      mode: 'keyword', keyword: '', types: '050000', city: '杭州', cityLimit: false,
      sort: 'comprehensive', page: 1, pageSize: 20, includeFields: [], timeoutMs: 10000,
      success: result => {
        if (disposed || !visible || current !== generation || result.requestId !== ownedRequestId) return
        items = result.items; context.clearOverlays()
        const markers = items.filter(value => value.position !== null).map((value, index) => ({
          id: 'result-' + index, position: value.position!, title: value.name, snippet: value.address
        }))
        if (markers.length > 0) context.upsertMarkers(markers)
        if (markers.length === 1) context.setCamera({ ...markers[0].position, zoom: 16, tilt: 0, bearing: 0 })
        if (markers.length > 1) context.fitCoordinates(markers.map(value => value.position), 32)
      },
      fail: error => { if (!disposed && visible && current === generation) explain(error) },
      complete: () => { if (current === generation) ownedRequestId = '' }
    })
  } catch (error) { ownedRequestId = ''; explain(error as MapFail) }
}
function choose(index: number, context: MapViewContext): void {
  const value = items[index]
  if (value !== undefined && value.position !== null) {
    context.setCamera({ ...value.position, zoom: 16, tilt: 0, bearing: 0 })
  }
}
function explain(error: MapFail): void { console.log(error.errCode, error.errMsg, error.data) }
onHide(() => { visible = false; cancelOwned() })
onShow(() => { visible = true; inspectSearch() })
onUnload(() => { disposed = true; visible = false; cancelOwned(); items = [] })

同一页面可分别保存提示、列表和详情 ID，最多共4个原生自有记录。取消或超时后 Android/鸿蒙仍可能保留等待 SDK 回执的记录，不能通过循环重试绕过上限；原始示例页同时演示三类请求独立状态、取消、并发操作和完整字段读取。

地理信息与地点搜索使用独立请求通道。以下示例分别演示地址匹配、逆编码、行政区和多起点矩阵；在页面按钮调用 runGeo(...)，页面隐藏/退出时只取消本例持有的ID。

import { onHide, onShow, onUnload } from '@dcloudio/uni-app'
import { geocodeMapAddress, reverseGeocodeMapCoordinate, searchMapDistricts, getMapDistanceMatrix,
  cancelMapGeoRequest, getMapGeoCapabilities, getMapGeoState } from '@/uni_modules/lizhao-map'
import type { MapGeocodeAddress, MapReverseGeocodeAddress, MapDistrictNode, MapDistanceMatrixResult, MapFail } from '@/uni_modules/lizhao-map'

let geoVisible = true, geoDisposed = false
const ownedGeoIds: string[] = []
function finishGeo(id: string): void { const index = ownedGeoIds.indexOf(id); if (index >= 0) ownedGeoIds.splice(index, 1) }
function cancelGeo(): void { const ids = ownedGeoIds.splice(0); for (const id of ids) cancelMapGeoRequest(id) }
function explainGeo(error: MapFail): void { if (geoVisible && !geoDisposed) console.log(error.errCode, error.errMsg, error.data) }
function runGeo(kind: 'geocode' | 'reverse' | 'district' | 'matrix'): string {
  if (!geoVisible || geoDisposed) return ''
  let id = ''
  const complete = () => finishGeo(id)
  if (kind === 'geocode') id = geocodeMapAddress({
    address: '浙江省杭州市西湖区文三路', city: '杭州', country: '中国', timeoutMs: 10000,
    success: result => {
      if (!geoVisible || geoDisposed || !ownedGeoIds.includes(result.requestId)) return
      console.log(result.requestId, result.platform, result.coordinateType, result.query, result.count)
      if (result.items.length === 0) console.log('没有地址匹配，请补全结构化地址')
      for (const item of result.items) readGeocode(item)
    }, fail: explainGeo, complete
  })
  if (kind === 'reverse') id = reverseGeocodeMapCoordinate({
    position: { latitude: 30.2741, longitude: 120.1551 }, radius: 0, includeNearby: true,
    poiTypes: '050000|060000', overseaSort: 'distance', timeoutMs: 10000,
    success: result => {
      if (!geoVisible || geoDisposed || !ownedGeoIds.includes(result.requestId)) return
      console.log(result.requestId, result.platform, result.coordinateType, result.query)
      if (result.address === null) console.log('SDK未提供地址，不生成空地址或坐标')
      else readReverseAddress(result.address)
    }, fail: explainGeo, complete
  })
  if (kind === 'district') id = searchMapDistricts({
    keywords: '杭州', subDistrict: 1, showBoundary: true, page: 1, pageSize: 20, timeoutMs: 15000,
    success: result => {
      if (!geoVisible || geoDisposed || !ownedGeoIds.includes(result.requestId)) return
      console.log(result.requestId, result.platform, result.coordinateType, result.query, result.count)
      for (const node of result.items) readDistrict(node)
    }, fail: explainGeo, complete
  })
  if (kind === 'matrix') id = getMapDistanceMatrix({
    origins: [{ latitude: 30.2741, longitude: 120.1551 }, { latitude: 30.28, longitude: 120.16 }],
    destination: { latitude: 30.285, longitude: 120.17 }, mode: 'driving', strategy: 4,
    includeExtensions: false, timeoutMs: 15000,
    success: result => {
      if (!geoVisible || geoDisposed || !ownedGeoIds.includes(result.requestId)) return
      readMatrix(result)
    }, fail: explainGeo, complete
  })
  ownedGeoIds.push(id) // 回调在返回ID后交付，不会先于此行执行。
  return id
}
function readGeocode(item: MapGeocodeAddress): void {
  console.log(item.formattedAddress, item.province, item.city, item.cityCode, item.district, item.adCode)
  console.log(item.township, item.neighborhood, item.building, item.country, item.postCode, item.level, item.position)
  if (item.position === null) console.log('此匹配没有可绘制坐标')
}
function readReverseAddress(item: MapReverseGeocodeAddress): void {
  console.log(item.formattedAddress)
  const component = item.addressComponent
  if (component !== null) {
    console.log(component.country, component.countryCode, component.province, component.city, component.cityCode)
    console.log(component.district, component.adCode, component.township, component.townCode, component.neighborhood, component.building)
    if (component.streetNumber !== null) {
      const street = component.streetNumber
      console.log(street.street, street.number, street.position, street.direction, street.distanceMeters)
    }
    for (const area of component.businessAreas) console.log(area.name, area.position)
  }
  for (const road of item.roads) console.log(road.id, road.name, road.position, road.direction, road.distanceMeters)
  for (const road of item.intersections) console.log(road.position, road.distanceMeters, road.direction,
    road.firstRoadId, road.firstRoadName, road.secondRoadId, road.secondRoadName)
  for (const poi of item.pois) console.log(poi.id, poi.name, poi.type, poi.typeCode, poi.address, poi.province,
    poi.provinceCode, poi.city, poi.cityCode, poi.district, poi.adCode, poi.telephone, poi.direction,
    poi.businessArea, poi.position, poi.distanceMeters)
  for (const aoi of item.aois) console.log(aoi.id, aoi.name, aoi.adCode, aoi.position, aoi.areaSquareMeters, aoi.distanceMeters, aoi.type)
}
function readDistrict(node: MapDistrictNode): void {
  console.log(node.name, node.level, node.cityCode, node.adCode, node.center, node.children.length)
  for (const boundary of node.boundaries) {
    console.log('实际边界点数', boundary.length)
    // 绘制时使用真实顶点；大边界按覆盖物上限分段，不截断查询结果。
    const first = boundary[0], last = boundary[boundary.length - 1]
    if (first !== undefined && last !== undefined) console.log(first.latitude, first.longitude, last.latitude, last.longitude)
  }
  for (const child of node.children) readDistrict(child)
}
function readMatrix(result: MapDistanceMatrixResult): void {
  console.log(result.requestId, result.platform, result.coordinateType, result.query)
  for (const item of result.items) {
    console.log(item.originId, item.destinationId, item.originIndex, item.destinationIndex)
    if (item.success) console.log(item.distanceMeters, '米', item.durationSeconds, '秒', item.errorCode, item.reason)
    else console.log('该起点失败', item.errorCode, item.reason, item.distanceMeters, item.durationSeconds)
  }
}
function inspectGeo(): void {
  const value = getMapGeoCapabilities()
  console.log(value.platform, value.supported, value.geocode, value.reverseGeocode, value.district, value.distance)
  console.log(value.areaModes, value.coordinateSources, value.mapProjection, value.distanceMatrixModes, value.cancellation)
  console.log(value.maxPendingRequests, value.maxMatrixOrigins, value.maxDistrictDepth, value.maxDistrictPage, value.maxDistrictPageSize)
  console.log(value.maxAreaVertices, value.maxDistrictNodes, value.maxBoundaryPoints, value.note)
  const state = getMapGeoState()
  console.log(state.platform, state.pendingRequestIds, state.retiredRequestCount, state.maxPendingRequests)
}
onHide(() => { geoVisible = false; cancelGeo() })
onShow(() => { geoVisible = true; inspectGeo() })
onUnload(() => { geoDisposed = true; geoVisible = false; cancelGeo() })

逆编码 includeNearby=false 使用基础信息，此时 poiTypes 留空且 overseaSort 保持默认。overseaSort='score' 只在扩展查询中传入，并按原厂说明仅海外生效。行政区 subDistrict=0 表示不返回下级；设置1、2、3分别请求对应深度，showBoundary=false 可减少数据。矩阵可将mode改为straight/walking，非驾车strategy保持4且不向服务发送；步行距离受原厂覆盖和服务范围限制，逐项读取错误。

本地工具需要已同意隐私和SDK初始化，不申请定位或占用在线四槽。以下代码绑定到地图ready后的操作按钮；map-local屏幕点以当前地图左上角为原点，单位为逻辑px。

import { calculateMapDistance, calculateMapArea, convertMapCoordinate } from '@/uni_modules/lizhao-map'
import type { MapViewContext, MapCoordinateSource, MapFail } from '@/uni_modules/lizhao-map'

function useSdkTools(context: MapViewContext, fromType: MapCoordinateSource): void {
  try {
    const from = { latitude: 30.2741, longitude: 120.1551 }
    const to = { latitude: 30.28, longitude: 120.16 }
    const distance = calculateMapDistance({ from, to })
    console.log(distance.platform, distance.coordinateType, distance.distanceMeters, '米', distance.method)
    const rectangle = calculateMapArea({ mode: 'rectangle', rectangle: { southWest: from, northEast: to } })
    const polygon = calculateMapArea({ mode: 'polygon', polygon: [from, { latitude: 30.28, longitude: 120.1551 }, to] })
    for (const area of [rectangle, polygon]) console.log(area.platform, area.coordinateType, area.mode, area.areaSquareMeters, '平方米', area.method)
    const converted = convertMapCoordinate({ position: from, fromType })
    console.log(converted.platform, converted.inputPosition, converted.fromType, converted.toType, converted.position)
    console.log(converted.changed, converted.dataAvailable, converted.method)
    if (!converted.changed) console.log('数值未变：可能同系、区域差异或SDK回退，不能据此验证转换成功')
    const pixel = context.coordinateToScreen(to)
    const roundTrip = context.screenToCoordinate({ x: pixel.x, y: pixel.y })
    const localOrigin = context.screenToCoordinate({ x: 0, y: 0 })
    console.log(pixel.x, pixel.y, '地图内逻辑px', roundTrip.latitude, roundTrip.longitude, localOrigin)
  } catch (error) {
    const failure = error as MapFail
    console.log(failure.errCode, failure.errMsg, failure.data)
  }
}

fromType从gcj02/wgs84/bd09/mapbar/mapabc/soso/aliyun/google选择；目标只提供GCJ-02，不虚构SDK没有的逆向转换。gcj02为identity复制。SDK可能对同系、区域外或内部异常原样返回；changed仅表示数值变化，dataAvailable仅表示SDK对输出GCJ-02坐标的数据覆盖判断，不是Key或转换正确性验证。SDK距离/面积是估算，三端算法和浮点可能不同；不等于驾车路线长度或测绘精度。

路线请求先返回ID，回调异步交付。下例使用驾车全部参数；避让道路与避让面互斥，要演示避让面时清空avoidRoad。坐标必须为GCJ-02，起终点POI ID可不填。

import { planMapRoute, cancelMapRouteRequest, getMapRouteCapabilities, getMapRouteState } from '@/uni_modules/lizhao-map'
import type { MapRouteResult, MapRouteOptions, MapRouteMode, MapCoordinate, MapViewContext } from '@/uni_modules/lizhao-map'

let routeRequest = ''
let routeResult: MapRouteResult | null = null
const routeFrom = { position: { latitude: 39.908823, longitude: 116.397470 }, poiId: '' }
const routeTo = { position: { latitude: 39.984120, longitude: 116.307484 }, poiId: '' }

function loadDrivingRoute() {
  if (routeRequest.length > 0) return
  routeRequest = planMapRoute({
    mode: 'driving', from: routeFrom, to: routeTo, timeoutMs: 10000,
    driving: { strategy: 32, waypoints: [{ latitude: 39.941, longitude: 116.36 }],
      avoidPolygons: [], avoidRoad: '示例道路', plate: '', carType: 0,
      useFerry: true, includeTraffic: true, includeCities: true },
    success: result => {
      routeResult = result
      console.log(result.requestId, result.platform, result.coordinateType, result.mode, result.provider)
      console.log(result.query, result.origin, result.destination, result.taxiCostYuan)
      console.log(result.navigationReusable, result.scalarPresenceKnown)
      if (result.routes.length === 0) console.log('本次查询没有方案')
      for (const route of result.routes) {
        console.log(route.id, route.index, route.distanceMeters, route.durationSeconds, route.durationSource)
        console.log(route.strategyDescription, route.restrictionCode, route.tollsYuan, route.tollDistanceMeters, route.trafficLights)
        for (const step of route.steps ?? []) {
          console.log(step.instruction, step.orientation, step.road, step.distanceMeters, step.durationSeconds)
          console.log(step.action, step.assistantAction, step.roadType, step.tollsYuan, step.tollDistanceMeters, step.tollRoad, step.trafficLights)
          console.log(step.polyline, step.cities, step.traffic)
        }
      }
    },
    fail: error => { console.log(error.errCode, error.errMsg, error.data) },
    complete: () => { routeRequest = '' }
  })
}
function stopRouteRequest() {
  if (routeRequest.length > 0) cancelMapRouteRequest(routeRequest)
}
function inspectRouteSupport() {
  const caps = getMapRouteCapabilities()
  console.log(caps.platform, caps.supported, caps.modes, caps.drivingStrategyValues, caps.transitStrategyValues, caps.truckStrategyValues)
  console.log(caps.alternativeCounts, caps.maxTransitAlternatives, caps.truckSizeValues, caps.indoorWalking, caps.trafficModes, caps.cityModes)
  console.log(caps.navigationReusable, caps.scalarPresenceKnown, caps.cancellation, caps.maxPendingRequests, caps.maxWaypoints)
  console.log(caps.maxAvoidPolygons, caps.maxAvoidVertices, caps.maxRoutes, caps.maxSteps, caps.maxTransitSegments, caps.maxAuxiliaryItems, caps.maxGeometryPoints, caps.note)
  const state = getMapRouteState()
  console.log(state.platform, state.pendingRequestIds, state.retiredRequestCount, state.maxPendingRequests)
}

按选定方式只传对应参数组，其他组不传。以下函数分别展示步行、骑行、公交与货车的全部配置；起终点和POI ID由调用者传入真实值。公交策略6要求两端POI ID均非空。

import { planMapRoute, getMapRouteCapabilities } from '@/uni_modules/lizhao-map'
import type { MapRouteMode, MapRouteOptions, MapRouteEndpoint, MapRouteResult } from '@/uni_modules/lizhao-map'

function planOtherRoute(mode: MapRouteMode, from: MapRouteEndpoint, to: MapRouteEndpoint, receive: (result: MapRouteResult) => void): string {
  const caps = getMapRouteCapabilities()
  const options: MapRouteOptions = { mode, from, to, timeoutMs: 10000,
    success: receive, fail: error => console.log(error.errCode, error.errMsg, error.data), complete: () => console.log('本次等待结束') }
  if (mode === 'walking') options.walking = { alternativeRoute: 3, indoor: caps.indoorWalking }
  if (mode === 'riding') options.riding = { alternativeRoute: 3 }
  if (mode === 'transit') options.transit = {
    originCityCode: '010', destinationCityCode: '010', strategy: 0, includeNightBuses: false,
    alternativeRoute: 5, maxTransfers: 4, includeAllSubwayExits: true,
    originAdCode: '110101', destinationAdCode: '110108', date: '', time: '09:30'
  }
  if (mode === 'truck') options.truck = {
    strategy: 1, waypoints: [], size: 2, heightMeters: 1.6, widthMeters: 2.5,
    grossWeightTons: 0.9, ratedLoadTons: 10, axles: 2, plateProvince: '', plateNumber: '',
    includeTraffic: caps.trafficModes.includes('truck'), includeCities: caps.cityModes.includes('truck')
  }
  if (mode === 'driving') options.driving = {
    strategy: 32, avoidRoad: '', avoidPolygons: [{ points: [
      { latitude: 39.93, longitude: 116.37 }, { latitude: 39.93, longitude: 116.38 }, { latitude: 39.94, longitude: 116.38 }
    ] }]
  }
  return planMapRoute(options)
}

方案选择保留真实分段。公交每段busLines是备选线路，选一条绘制；铁路只展示站点和车次，SDK没有轨道几何。不要把空几何补为起终点直线。以下函数展示一次方案选择与换乘字段读取；context来自已ready的地图实例。

import type { MapRouteResult, MapCoordinate, MapPolyline, MapViewContext } from '@/uni_modules/lizhao-map'

function drawSelectedRoute(result: MapRouteResult, index: number, context: MapViewContext) {
  const route = result.routes[index]
  if (route == null) return
  const lines: MapPolyline[] = []
  const points: MapCoordinate[] = []
  function append(segment: MapCoordinate[]) {
    if (segment.length < 2) return
    if (!segment.some(point => point.latitude !== segment[0].latitude || point.longitude !== segment[0].longitude)) {
      console.log('本段坐标相同，只保留结果字段，不提交退化折线')
      return
    }
    if (segment.length > 5000) { console.log('当前分段超过单覆盖物5000点，请按保留边界点方式拆段'); return }
    const line: MapPolyline = { id: 'route-' + lines.length.toString(), points: segment, strokeColor: '#2377E8', strokeWidth: 5 }
    lines.push(line)
    for (const point of segment) points.push(point)
  }
  for (const step of route.steps ?? []) append(step.polyline)
  const transit = route.transit
  if (transit != null) {
    console.log(transit.costYuan, transit.nightBus, transit.walkingDistanceMeters, transit.busDistanceMeters)
    for (const segment of transit.segments) {
      if (segment.walking != null) {
        console.log(segment.walking.origin, segment.walking.destination, segment.walking.distanceMeters, segment.walking.durationSeconds)
        for (const step of segment.walking.steps) append(step.polyline)
      }
      for (const line of segment.busLines) console.log(line.id, line.name, line.type, line.cityCode, line.distanceMeters, line.durationSeconds,
        line.departureStop, line.arrivalStop, line.viaStopCount, line.viaStops, line.firstTimeText, line.lastTimeText)
      if (segment.busLines.length > 0) append(segment.busLines[0].polyline)
      if (segment.taxi != null) {
        console.log(segment.taxi.origin, segment.taxi.destination, segment.taxi.originName, segment.taxi.destinationName,
          segment.taxi.distanceMeters, segment.taxi.durationSeconds, segment.taxi.priceText, segment.taxi.priceYuan)
        append(segment.taxi.polyline)
      }
      if (segment.railway != null) {
        console.log(segment.railway.id, segment.railway.name, segment.railway.trip, segment.railway.type, segment.railway.distanceMeters, segment.railway.durationSeconds)
        console.log(segment.railway.departureStation, segment.railway.arrivalStation, segment.railway.viaStops, segment.railway.spaces, segment.railway.alternatives)
      }
      console.log(segment.entrance, segment.exit)
    }
  }
  context.clearOverlays()
  if (lines.length > 0) {
    for (let start = 0; start < lines.length; start += 500) context.upsertPolylines(lines.slice(start, start + 500))
  }
  else console.log('此方案没有可绘制的真实分段')
  // 只用真实轨迹中的四个极值点适配视口，绘制仍保留各段完整几何。
  const fit: MapCoordinate[] = []
  if (points.length > 0) {
    let north = points[0], south = points[0], east = points[0], west = points[0]
    for (const point of points) {
      if (point.latitude > north.latitude) north = point
      if (point.latitude < south.latitude) south = point
      if (point.longitude > east.longitude) east = point
      if (point.longitude < west.longitude) west = point
    }
    fit.push(north, south, east, west)
    if (Math.abs(north.latitude) <= 85 && Math.abs(south.latitude) <= 85 && east.longitude - west.longitude < 180) context.fitCoordinates(fit, 24)
    else console.log('当前轨迹超出自动视口适配范围')
  }
}

驾车导航：真实算路、选路与结束重建

先完成上面的隐私与初始化。两种导航模式创建引擎时都会定位；下例只在用户点击后创建。取消是取消插件等待，旧 SDK 请求可能继续占用资源。模拟用于演示；GPS 还须精确位置。完整输入、状态与分页结果可直接查看插件内两张导航示例页。

<template>
  <view class="example">
    <lizhao-map-navi v-if="mounted" :key="viewKey" ref="navi" class="navigation" :active="active" :traffic="traffic" @navi-event="onNaviEvent" />
    <scroll-view class="controls" direction="vertical">
      <button class="action" @click="requestPermission">主动申请前台定位</button>
      <button class="action" @click="createView">创建新的导航实例</button>
      <input class="plate" v-model="plate" placeholder="可选：本次实际车牌" />
      <button class="action" @click="calculate">按手动坐标算路</button>
      <button class="action" @click="calculateFromHere">按 SDK 当前位置算路</button>
      <button class="action" @click="readRoutes">读取并选择真实方案</button>
      <button class="action" @click="start('emulator')">以 60 km/h 开始模拟</button>
      <button class="action" @click="start('gps')">开始 GPS 导航</button>
      <button class="action" @click="run(view => view.cancelCalculation())">取消本次算路等待</button>
      <button class="action" @click="run(view => view.showOverview())">全览实际路线</button>
      <button class="action" @click="run(view => view.followVehicle())">导航中跟随车辆</button>
      <button class="action" @click="toggleTraffic">切换真实路况图层</button>
      <button class="action" @click="readState">读取实例与全局状态</button>
      <button class="action" @click="run(view => view.stop())">停止并结束本次实例</button>
      <button class="action" @click="run(view => view.setActive(false))">结束前台使用</button>
      <button class="action" @click="run(view => view.destroy())">销毁本次实例</button>
      <text class="output">{{ output }}</text>
    </scroll-view>
  </view>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { onHide, onShow, onUnload } from '@dcloudio/uni-app'
import { getMapStatus, getMapLocationPermission, requestMapLocationPermission, cancelMapLocationRequest, getMapNaviCapabilities, getMapNaviState } from '@/uni_modules/lizhao-map'
import type { MapNaviViewContext, MapNaviCalculateOptions, MapNaviEvent, MapNaviMode } from '@/uni_modules/lizhao-map'

const navi = ref<MapNaviViewContext | null>(null)
const mounted = ref(false), active = ref(true), traffic = ref(false), viewKey = ref(0)
const plate = ref(''), output = ref('请先完成接入配置，再主动检查权限。')
let visible = true, exited = false, permissionId = ''
let privacyTimer: ReturnType<typeof setInterval> | null = null
function checkPrivacy(): void {
  if (exited || !visible) return
  const privacy = getMapStatus().privacy
  if (!privacy.shown || !privacy.contains || !privacy.agreed) {
    plate.value = ''; output.value = '隐私条件未满足，已清除本页车牌与结果。'
    try { navi.value?.setActive(false) } catch (_) {}
  }
}
function run(operation: (view: MapNaviViewContext) => void): void {
  if (exited || !visible) return
  try { if (navi.value === null) throw new Error('请先创建实例'); operation(navi.value) }
  catch (error) { const value = error as { errCode?: number }; output.value = '操作未完成，请检查状态与参数；错误码：' + (value.errCode ?? '未创建') }
}
function requestPermission(): void {
  if (exited || !visible || permissionId !== '') return
  permissionId = requestMapLocationPermission({
    timeoutMs: 60000,
    success: result => { if (!exited && visible) output.value = `权限 ${result.state} / 精度 ${result.accuracy} / 服务 ${result.serviceEnabled}` },
    fail: error => { if (!exited && visible) output.value = '授权未完成：' + error.errCode },
    complete: () => { permissionId = '' }
  })
}
function createView(): void {
  if (exited || !visible) return
  const capabilities = getMapNaviCapabilities(), status = getMapStatus(), permission = getMapLocationPermission(), global = getMapNaviState()
  if (!capabilities.supported || !status.initialized || !status.privacy.agreed || permission.state !== 'granted' || !permission.serviceEnabled || global.busy) {
    output.value = '请检查平台、初始化、前台授权和系统服务；回收中不能创建新实例。'
    return
  }
  viewKey.value += 1; active.value = true; mounted.value = true
}
function query(): MapNaviCalculateOptions {
  return {
    start: { position: { latitude: 39.9042, longitude: 116.4074 }, name: '起点', poiId: '' },
    end: { position: { latitude: 39.9841, longitude: 116.3075 }, name: '终点', poiId: '' },
    waypoints: [{ position: { latitude: 39.938, longitude: 116.36 }, name: '途经点', poiId: '' }],
    strategy: 10,
    vehicle: { vehicleType: 0, plateNumber: plate.value.trim(), avoidRestrictions: plate.value.trim() !== '' },
    timeoutMs: 30000
  }
}
function calculate(): void { run(view => { output.value = '请求ID：' + view.calculate(query()) }) }
function calculateFromHere(): void { const options = query(); options.start = null; run(view => { output.value = '当前位置请求：' + view.calculate(options) }) }
function readRoutes(): void {
  run(view => {
    const result = view.getRoutes(), route = result.routes[0]
    if (route == null) return
    view.selectRoute(route.routeId)
    output.value = `本代${result.generation}，${result.coordinateType}；SDK键${route.sdkRouteId}，路径标识${route.nativePathId ?? '未提供'}；${route.distanceMeters ?? '未知'}米/${route.durationSeconds ?? '未知'}秒，费用${route.tollCostYuan ?? '未知'}元，红绿灯${route.trafficLightCount ?? '未知'}，标签${route.labels.join('、')}，真实轨迹${route.polyline.length}点`
  })
}
function start(mode: MapNaviMode): void {
  run(view => { if (mode === 'gps') view.start({ mode: 'gps' }); else view.start({ mode: 'emulator', emulatorSpeedKmh: 60 }) })
}
function toggleTraffic(): void { run(view => { const next = !traffic.value; view.setTraffic(next); traffic.value = next }) }
function readState(): void { run(view => { const state = view.getState(), global = getMapNaviState(); output.value = `${state.phase}/${state.releaseState}；当前模式${state.mode ?? '未启动'}，待回执${state.pendingCalculation}；全局占用${global.busy}` }) }
function onNaviEvent(event: MapNaviEvent): void {
  if (exited || !visible) return
  if (event.type === 'ready') output.value = '原生视图已就绪，请主动算路。'
  else if (event.type === 'calculate-start') output.value = '等待导航 SDK 真实方案：' + event.requestId
  else if (event.type === 'calculate-success' || event.type === 'route-selected' || event.type === 'route-updated') {
    if (event.routes !== null) output.value = `${event.routes.routes.length}个真实方案，所选${event.routes.selectedRouteId}；请核对地图轨迹`
  } else if (event.type === 'progress' && event.info !== null) {
    const info = event.info
    output.value = `${info.currentRoad} → ${info.nextRoad}；剩余${info.remainingDistanceMeters ?? '未知'}米/${info.remainingDurationSeconds ?? '未知'}秒，本段${info.stepRemainingDistanceMeters ?? '未知'}米/${info.stepRemainingDurationSeconds ?? '未知'}秒，平台转向码${info.maneuverCode ?? '未提供'}`
  } else if (event.type === 'location' && event.location !== null) {
    output.value = `${event.location.coordinateType}：${event.location.latitude},${event.location.longitude}；${event.location.speedKmh ?? '未知'}km/h`
  } else if (event.type === 'gps-signal') output.value = `GPS原因${event.reason}，平台等级${event.gpsSignalLevel ?? '未提供'}`
  else if (event.type === 'waypoint') output.value = '途经点 SDK 原索引：' + (event.waypointIndex ?? '未提供')
  else if (event.type === 'off-route' || event.type === 'traffic-reroute') output.value = 'SDK触发重算：' + event.type
  else if (event.type === 'navigation-start') output.value = 'SDK已报告导航开始：' + event.state.mode
  else if (event.type === 'error') output.value = `${event.errCode} ${event.errMsg}，原生码${event.nativeErrorCode ?? '未提供'}`
  else if (event.type === 'arrive' || event.type === 'emulator-end' || event.type === 'stop' || event.type === 'destroyed' || event.type === 'calculate-cancel' || event.type === 'close-request') {
    output.value = `本次状态${event.type}，释放${event.state.releaseState}；再次使用需重建，不能复用旧凭据`
  }
}
onShow(() => { visible = true; checkPrivacy(); if (privacyTimer === null) privacyTimer = setInterval(checkPrivacy, 1000) })
onHide(() => { visible = false; try { navi.value?.setActive(false) } catch (_) {} })
onUnload(() => { exited = true; if (privacyTimer !== null) clearInterval(privacyTimer); privacyTimer = null; if (permissionId !== '') cancelMapLocationRequest(permissionId) })
</script>

<style>
.example { flex: 1; height: 100%; background-color: #f3f6f7; }
.navigation { width: 100%; height: 300px; }
.controls { flex: 1; padding: 12px; }
.action { min-height: 44px; margin-bottom: 8px; font-family: sans-serif; font-size: 14px; }
.plate { height: 44px; margin-bottom: 8px; padding: 10px; font-family: sans-serif; font-size: 14px; background-color: #ffffff; }
.output { font-family: sans-serif; font-size: 14px; line-height: 24px; color: #365766; white-space: normal; }
</style>

vehicleType 还可取2纯电客车/4插混客车，策略仅采用下表十项。车牌是本机用户输入，示例未写真实标识；不用车牌限行时设空车牌和 avoidRestrictions:false。模拟速度可选10/60/120等整速；GPS不传模拟速度。一个实例只启动一次，结束后应先核对全局释放，再按新key重建。原生 adapter 类 MapNaviController 供App自定义标准组件使用；普通页面优先直接使用 lizhao-map-navi，以获得完整挂载、ready交付与卸载清理。

步行、骑行与货车导航

下面是可替换上例的最小多方式页面；请先在接入配置中完成隐私、初始化和前台定位授权。切换方式前先停止并移除当前实例，再选择方式创建。页面隐藏时停止并移除自己的实例，重新显示后需主动创建，不自动恢复。步行和骑行不传客车、货车或途经点；货车参数与路线搜索中的参数互相独立。

<template>
  <view class="multi-navi">
    <view class="transport-options">
      <button v-for="item in choices" :key="item.value" class="multi-action" :disabled="mounted" @click="transport = item.value">{{ item.label }}</button>
    </view>
    <button class="multi-action" :disabled="mounted" @click="create">创建 {{ transport }} 导航</button>
    <lizhao-map-navi v-if="mounted" :key="revision" ref="navi" class="multi-map" :transport="transport" :active="active" :traffic="traffic" @navi-event="onEvent" />
    <button class="multi-action" :disabled="!prepared" @click="start('emulator')">按本方式速度模拟</button>
    <button class="multi-action" :disabled="!prepared" @click="start('gps')">开始 GPS 导航</button>
    <button class="multi-action" :disabled="!mounted" @click="stop">停止并移除本实例</button>
    <text class="multi-output">{{ output }}</text>
  </view>
</template>
<script setup lang="ts">
import { ref, onBeforeUnmount } from 'vue'
import { onHide } from '@dcloudio/uni-app'
import { getMapNaviCapabilities, getMapNaviState, getMapStatus, getMapLocationPermission } from '@/uni_modules/lizhao-map'
import type { MapNaviTransport, MapNaviMode, MapNaviViewContext, MapNaviCalculateOptions, MapNaviEvent } from '@/uni_modules/lizhao-map'
const choices: Array<{ value: MapNaviTransport; label: string }> = [
  { value: 'driving', label: '驾车' }, { value: 'walking', label: '步行' },
  { value: 'riding', label: '骑行' }, { value: 'truck', label: '货车' }
]
const transport = ref<MapNaviTransport>('walking'), navi = ref<MapNaviViewContext | null>(null)
const mounted = ref(false), active = ref(true), traffic = ref(false), prepared = ref(false), revision = ref(0)
const output = ref('选择方式后创建；切换方式需要先结束旧实例。')
function create(): void {
  const capabilities = getMapNaviCapabilities(), state = getMapNaviState(), status = getMapStatus(), permission = getMapLocationPermission()
  if (!capabilities.transports.includes(transport.value)) { output.value = '当前平台未开放此方式'; return }
  if (!status.initialized || !status.privacy.agreed || !status.privacy.shown || !status.privacy.contains || permission.state !== 'granted' || !permission.serviceEnabled || state.busy) {
    output.value = '请完成接入与定位授权，并等待旧导航资源释放'; return
  }
  revision.value++; prepared.value = false; active.value = true; traffic.value = false; mounted.value = true
}
function query(): MapNaviCalculateOptions {
  const base: MapNaviCalculateOptions = {
    start: { position: { latitude: 39.993308, longitude: 116.473199 }, name: '起点', poiId: '' },
    end: { position: { latitude: 39.998877, longitude: 116.481234 }, name: '目的地', poiId: '' }, timeoutMs: 30000
  }
  if (transport.value === 'walking' || transport.value === 'riding') return { ...base, strategy: 1001 }
  if (transport.value === 'truck') return { ...base, strategy: 10, waypoints: [], truck: {
    vehicleType: 1, plateNumber: '', avoidRestrictions: false, size: 2, heightMeters: 1.6, widthMeters: 2.5,
    lengthMeters: 6, grossWeightTons: 10, ratedLoadTons: 2, axles: 2, includeWeight: true
  } }
  return { ...base, strategy: 10, waypoints: [], vehicle: { vehicleType: 0, plateNumber: '', avoidRestrictions: false } }
}
function onEvent(event: MapNaviEvent): void {
  if (!mounted.value || !active.value) return
  output.value = event.state.transport + ' · ' + event.type + ' · ' + event.errCode
  if (event.type === 'ready') { try { navi.value?.calculate(query()) } catch (_) { output.value = '算路未受理，请检查参数与状态' } }
  if (event.routes !== null) output.value = event.routes.transport + ' · 实际方案数 ' + event.routes.routes.length
  prepared.value = event.state.phase === 'prepared' && event.state.releaseState === 'owned'
  if (event.type === 'error') output.value = event.errMsg
}
function start(mode: MapNaviMode): void {
  if (!mounted.value || !active.value || !prepared.value) return
  if (mode === 'gps' && getMapLocationPermission().accuracy !== 'full') { output.value = 'GPS导航需要精确位置授权'; return }
  const profile = getMapNaviCapabilities().transportProfiles.find(item => item.transport === transport.value)
  if (profile === undefined) { output.value = '未取得本方式能力'; return }
  try {
    navi.value?.start(mode === 'gps' ? { mode: 'gps' } : { mode: 'emulator', emulatorSpeedKmh: profile.emulatorSpeedDefaultKmh })
    output.value = '已提交启动，请等待真实 navigation-start 事件'
  } catch (_) { output.value = '启动未受理，请核对权限、路线与本方式参数' }
}
function stop(): void { try { navi.value?.stop() } catch (_) { output.value = '停止未确认，请核对全局回收状态' } finally { prepared.value = false; active.value = false; mounted.value = false } }
onHide(stop)
onBeforeUnmount(() => { try { navi.value?.destroy() } catch (_) {} })
</script>
<style>
.multi-navi { flex: 1; }
.transport-options { flex-direction: row; flex-wrap: wrap; }
.multi-map { height: 300px; width: 100%; }
.multi-action { min-height: 44px; margin: 4px; font-size: 14px; }
.multi-output { margin: 12px; font-size: 14px; line-height: 24px; white-space: normal; }
</style>

读取 transportProfiles 可取得本方式速度、途经点上限与 trafficLayer。iOS步行/骑行的交通图层能力为false，不能打开组件traffic或调用setTraffic；这不会影响真实路线预览和导航。鸿蒙步行/骑行使用公开普通算路接口，取消、超时或退出后若无法安全确认回执归属，资源可能持续占用；请读取全局状态，仍未释放时需重启应用。货车服务、真实GPS/模拟与内置语音需要有效高德Key、相应服务和匹配原生环境。

巡航与中文系统语音

巡航需要先在接入配置完成隐私、初始化及精确定位授权；系统语音只需要真实隐私同意、前台和可用中文系统资源。下面保留两者的资源边界：播报前先结束自己的导航组件，读取两类占用，不能用空闲倒计时代替释放确认。完整字段及失败处理见 example/uniappx/cruise.uvue。

<template>
  <view>
    <view v-if="mounted" class="cruise-map">
      <LizhaoMapNavi ref="view" transport="driving" :voice-enabled="false" @navi-event="onNavi" />
    </view>
    <button @click="create">创建巡航实例（初始静音）</button>
    <button :disabled="!ready" @click="startCruise">启动设施和电子眼检测</button>
    <button :disabled="!ready" @click="enableVoice">启用本实例播报</button>
    <button @click="closeCruise">结束自己的巡航</button>
    <button @click="speak">播报中文提示</button>
    <button @click="stopSpeech">停止自己的播报</button>
    <button @click="refresh">读取释放状态</button>
    <text>{{ output }}</text>
  </view>
</template>
<script setup lang="ts">
import { ref, onBeforeUnmount } from 'vue'
import { onHide } from '@dcloudio/uni-app'
import LizhaoMapNavi from '@/uni_modules/lizhao-map/components/lizhao-map-navi/lizhao-map-navi.uvue'
import { getMapNaviState, getMapSpeechState, getMapSpeechCapabilities, speakMapText, stopMapSpeech } from '@/uni_modules/lizhao-map'
import type { MapNaviViewContext, MapNaviEvent } from '@/uni_modules/lizhao-map'
const view = ref<MapNaviViewContext | null>(null)
const mounted = ref(false), ready = ref(false), output = ref('等待主动操作')
let speechId = '', leaving = false
function fail(error: unknown): void { if (!leaving) output.value = '操作未完成：' + String((error as { errCode?: number }).errCode ?? 9101024) }
function refresh(): void { try { const n = getMapNaviState(), s = getMapSpeechState(); output.value = '导航占用=' + n.busy + '；语音占用=' + s.busy + '；语音回收=' + s.releaseState } catch (e) { fail(e) } }
function create(): void {
  try { if (getMapNaviState().busy || getMapSpeechState().busy) { refresh(); return }; mounted.value = true } catch (e) { fail(e) }
}
function startCruise(): void { try { view.value?.startCruise({ mode: 3, startupTimeoutMs: 60000 }); ready.value = false } catch (e) { fail(e) } }
function enableVoice(): void { try { view.value?.setVoiceEnabled(true); output.value = '内置播报配置=' + view.value?.getState().voiceEnabled } catch (e) { fail(e) } }
function onNavi(e: MapNaviEvent): void {
  if (leaving) return
  if (e.type === 'ready') ready.value = true
  if (e.type === 'cruise-start') output.value = '已收到巡航专属回执；位置确认=' + e.state.locationConfirmed
  if (e.cruise !== null) {
    const c = e.cruise
    if (c.kind === 'statistics') output.value = c.statistics === null ? '本次统计未提供' : '距离=' + String(c.statistics.distanceMeters) + '米；时间=' + String(c.statistics.elapsedSeconds) + '秒'
    else if (c.kind === 'facilities' || c.kind === 'cameras') output.value = c.facilities === null ? '本次未提供设施数组' : '本次设施数=' + c.facilities.length
    else output.value = c.congestion === null ? '本次拥堵已清除' : c.congestion.roadName + '：' + String(c.congestion.lengthMeters) + '米'
  }
  if (e.type === 'error') output.value = e.errMsg
}
function closeCruise(): void { try { view.value?.stop() } catch (e) { fail(e) }; mounted.value = false; ready.value = false }
function speak(): void {
  try {
    const cap = getMapSpeechCapabilities()
    if (!cap.supported || getMapNaviState().busy || getMapSpeechState().busy) { refresh(); return }
    speechId = speakMapText({ text: '请确认当前位置与道路情况。', language: 'zh-CN', timeoutMs: 60000, onEvent: e => {
      if (leaving || e.requestId !== speechId) return
      output.value = e.type + '；实际语言=' + String(e.state.actualLanguage) + '；错误=' + e.errCode
      if (e.type === 'complete' || e.type === 'stop' || e.type === 'error') refresh()
    } })
  } catch (e) { fail(e) }
}
function stopSpeech(): void { try { if (speechId !== '') stopMapSpeech(speechId); refresh() } catch (e) { fail(e) } }
onHide(() => { closeCruise(); stopSpeech() })
onBeforeUnmount(() => { leaving = true; try { if (speechId !== '') stopMapSpeech(speechId) } catch (_) {} })
</script>
<style>
.cruise-map { height: 280px; width: 100%; }
</style>

cruise-starting 只表示已提交；专属统计、设施、电子眼或拥堵的真实回执（包含真实空/清除）才确认 cruising。统计可能需要移动才返回；只有位置不能证明巡航专属数据已生效。停止后此实例不能再次启动。语音回调终态仍可能 busy=true，再次使用前读状态；主动停止立即取消自己的排队用户回调，资源回收由 getMapSpeechState() 确认。

离线城市目录和单项管理

先完成隐私和地图初始化。固定 SDK 11+ 的离线地图需要高德高阶服务开通，supported=true 只表示接口可用，不能证明 Key 已获授权。离线包用于底图，搜索、定位和导航分别按其 SDK 条件运行。完整目录筛选、任务、手动地图坐标和日志见 example/uniappx/offline.uvue。

import { startMapOfflineSession, stopMapOfflineSession, getMapOfflineCatalog,
  downloadMapOfflineCity, pauseMapOfflineCity, resumeMapOfflineCity, removeMapOfflineCity,
  getMapOfflineState, getMapOfflineCapabilities } from '@/uni_modules/lizhao-map'
import type { MapOfflineAction, MapOfflineCity, MapOfflineEvent } from '@/uni_modules/lizhao-map'

let sessionId = '', operationId = '', selected: MapOfflineCity | null = null
function failure(error: unknown): void { console.log('离线操作失败', error) }
function receive(event: MapOfflineEvent): void {
  if (event.sessionId !== sessionId) return
  if (event.type === 'ready' && event.catalog !== null) {
    const catalog = event.catalog
    console.log('目录', catalog.generation, catalog.version, catalog.cities.length)
    selected = catalog.cities.length > 0 ? catalog.cities[0] : null
    if (selected !== null) console.log(selected.id, selected.name, selected.cityCode, selected.adCode, selected.actions)
  }
  if (event.operationId !== '' && event.operationId !== operationId) return
  if (event.city !== null) {
    selected = event.city
    console.log('实际阶段', selected.status, selected.nativeStatus, selected.nativeDownloadStatus,
      selected.progressPercent, selected.packageBytes, selected.downloadedBytes, selected.expectedDownloadBytes)
  }
  if (event.type === 'download-complete') console.log('SDK确认已完成', event.reason)
  if (event.type === 'paused') console.log('SDK确认已暂停')
  if (event.type === 'removed') console.log('所选项SDK缓存已移除', event.reason)
  if (event.type === 'error') console.log(event.errCode, event.nativeErrorCode, event.reason)
  console.log('owner与管线', event.state.busy, event.state.pending, event.state.releaseState)
}
export function openOffline(): void {
  try {
    const capabilities = getMapOfflineCapabilities()
    if (!capabilities.supported) { console.log(capabilities.note); return }
    console.log(capabilities.requiresAdvancedService, capabilities.deleteConfirmation)
    sessionId = startMapOfflineSession({ timeoutMs: 30000, onEvent: receive })
  } catch (error) { failure(error) }
}
export function refreshOfflineCatalog(): void {
  try {
    const catalog = getMapOfflineCatalog(sessionId)
    selected = catalog.cities.find(city => city.id === selected?.id) ?? null
    console.log('真实快照', catalog.timestamp, catalog.cities)
  } catch (error) { failure(error) }
}
export function operateOffline(action: MapOfflineAction): void {
  try {
    const city = selected
    if (city === null || !city.actions.includes(action)) return
    const options = { sessionId: sessionId, cityId: city.id,
      timeoutMs: action === 'download' || action === 'resume' ? 900000 : 60000 }
    if (action === 'download') operationId = downloadMapOfflineCity(options)
    if (action === 'pause') operationId = pauseMapOfflineCity(options)
    if (action === 'resume') operationId = resumeMapOfflineCity(options)
    // UI先明确提示删除范围并确认，再调用这一分支；确认后重新核对会话和城市身份。
    if (action === 'remove') operationId = removeMapOfflineCity(options)
  } catch (error) { failure(error) }
}
// 页面退出时调用。主动停止立即静默自己的回调；已下载数据保留。
export function closeOffline(): void {
  const ownId = sessionId
  sessionId = ''; operationId = ''; selected = null
  try { stopMapOfflineSession(ownId) } catch (error) { failure(error) }
  try { console.log('实际回收状态', getMapOfflineState()) } catch (error) { failure(error) }
}

城市 id 是当前会话目录中的不透明凭据；新会话应重取，不能用城市区号或行政区码替代。busy 表示会话拥有资源，目录就绪时仍为 true；pending 才表示未决 SDK 任务。会话最多一项任务，暂停可以接管自己下载/恢复的停止意图。返回操作 ID 仅代表受理，真实完成以对应事件为准。

Android/鸿蒙的阶段百分比可能从下载 100 回到解压 0，100 不能当作完成，也不能反推字节。iOS 的网络下载完成也不等于解压完成。解压阶段不保证能暂停；暂停先遇到完整安装时可能返回 download-complete。请求尚未提交 SDK 就被取消时返回错误 9101014，不伪报已暂停。

鸿蒙固定 SDK 的下载回执没有请求 ID。同一城市失败后重试，若在新活动确认前收到与旧初态相同的错误，插件无法可靠归属该回执，会发 error（9101027，reason='ambiguous-download-receipt'）结束用户等待，并保留 busy=true / releaseState='uncertain'。后续只处理自己任务的安全停止与确认；没有可确认回执时不能强制重建，可能需要重启应用。重复暂停不会替换已经等待确认的暂停请求。

聚合、热力、海量点、点移动与地图截图

在已完成隐私和初始化的 App 中，等待本组件 map-event 的 ready 后操作。以下代码可放入一个页面；完整参数、状态与日志示例见 example/uniappx/advanced-map/advanced-map.uvue。

宿主须在页面 onHide 设置 active=false，在 onShow 恢复，退出时卸载组件。Android、鸿蒙的高级地图前台门禁依赖这项生命周期转发；iOS另检查系统App状态。foregroundOnly=true 表示前台使用约束，不表示各端都自动观察整个App后台，也不提供后台点移动、截图或自动续播。

<template>
  <view>
    <LizhaoMap ref="map" style="height: 300px;" :active="active"
      @map-event="onMapEvent" @advanced-event="onAdvancedEvent" />
    <button :disabled="!ready" @click="installLayers">创建三种数据层</button>
    <button :disabled="!ready" @click="inspectClusters">读取聚合</button>
    <button :disabled="!ready" @click="changeVisibility">隐藏/显示聚合</button>
    <button :disabled="!ready" @click="removeCluster">移除聚合</button>
    <button :disabled="!ready" @click="movePoint">移动专属点</button>
    <button :disabled="moveId === ''" @click="stopMove">停止本次移动</button>
    <button :disabled="!ready" @click="snapshotMap">截取地图</button>
    <button :disabled="snapshotId === ''" @click="cancelSnapshot">取消截图等待</button>
    <button :disabled="savedImageId === ''" @click="removeImage">删除本图临时文件</button>
    <button :disabled="!ready" @click="readState">读取高级状态</button>
    <button :disabled="!ready" @click="clearAdvanced">清理高级资源</button>
    <text>{{ message }}</text>
  </view>
</template>
<script setup lang="ts">
import { ref } from 'vue'
import { onHide, onShow, onUnload } from '@dcloudio/uni-app'
import LizhaoMap from '@/uni_modules/lizhao-map/components/lizhao-map/lizhao-map.uvue'
import { getMapAdvancedCapabilities } from '@/uni_modules/lizhao-map'
import type { MapViewContext, MapEventDetail, MapAdvancedEvent } from '@/uni_modules/lizhao-map'
const map = ref<MapViewContext | null>(null), active = ref(true), ready = ref(false), message = ref('等待地图就绪')
const moveId = ref(''), snapshotId = ref(''), savedImageId = ref('')
let leaving = false, visible = true
const cap = getMapAdvancedCapabilities()
console.log(cap.platform, cap.supported, cap.clusterAlgorithm, cap.heatmapRadiusUnit, cap.note)
function run(operation: (view: MapViewContext) => void): void {
  if (leaving || !cap.supported || !ready.value || map.value === null) return
  try { operation(map.value) }
  catch (error) { const failure = error as { errCode?: number }; message.value = `操作失败：${failure.errCode ?? 9101028}` }
}
function onMapEvent(event: MapEventDetail): void { if (!leaving) ready.value = event.type === 'ready' || ready.value && event.type !== 'error' && event.type !== 'destroyed' }
function installLayers(): void { run(view => {
  const points = [
    { id: '0', coordinate: { latitude: 39.9042, longitude: 116.4074 } },
    { id: '地点二', coordinate: { latitude: 39.906, longitude: 116.409 } }
  ]
  view.setMarkerClusters({ id: 'clusters', points, gridSize: 60, visible: true })
  view.setHeatmap({ id: 'heat', points: points.map((point, index) => ({ coordinate: point.coordinate, weight: index === 0 ? 0 : 1 })), radius: 12, opacity: 0, visible: false })
  view.setMultiPoints({ id: 'multi', points, iconSize: 12, visible: true })
}) }
function inspectClusters(): void { run(view => { const groups = view.getMarkerClusters('clusters'); message.value = groups.map(group => `${group.id}：${group.count}项 ${group.memberIds.join(',')}，${group.coordinate.latitude},${group.coordinate.longitude}`).join('\n') || '当前视口内没有聚合点' }) }
function changeVisibility(): void { run(view => { view.setAdvancedLayerVisible({ kind: 'cluster', id: 'clusters' }, !visible); visible = !visible }) }
function removeCluster(): void { run(view => view.removeAdvancedLayer({ kind: 'cluster', id: 'clusters' })) }
function movePoint(): void { run(view => { moveId.value = view.startPointMove({ points: [{ latitude: 39.9042, longitude: 116.4074 }, { latitude: 39.906, longitude: 116.409 }], durationSeconds: 20, timeoutMs: 50000 }) }) }
function stopMove(): void { run(view => { view.stopPointMove(moveId.value); moveId.value = ''; readState() }) }
function snapshotMap(): void { run(view => { snapshotId.value = view.takeMapSnapshot({ timeoutMs: 30000 }) }) }
function cancelSnapshot(): void { run(view => { view.cancelMapSnapshot(snapshotId.value); snapshotId.value = ''; readState() }) }
function removeImage(): void { run(view => { view.removeMapSnapshot(savedImageId.value); savedImageId.value = '' }) }
function readState(): void { run(view => { const state = view.getAdvancedState(); message.value = JSON.stringify({ platform: state.platform, instanceId: state.instanceId, active: state.active, ready: state.ready, layers: state.layers, move: state.move, snapshot: state.snapshot, snapshots: state.snapshots, retiredMoves: state.retiredMoves, errCode: state.errCode, nativeErrorCode: state.nativeErrorCode, reason: state.reason }) }) }
function clearAdvanced(): void { run(view => { view.clearAdvancedLayers(); moveId.value = ''; snapshotId.value = ''; savedImageId.value = ''; readState() }) }
function onAdvancedEvent(event: MapAdvancedEvent): void {
  if (leaving) return
  console.log(event.type, event.instanceId, event.requestId, event.layerKind, event.layerId, event.layerGeneration, event.sequence, event.timestamp, event.state)
  if (event.type === 'cluster-click' && event.cluster !== null) console.log(event.cluster.coordinate, event.cluster.memberIds, event.cluster.count)
  if (event.type === 'multipoint-click' && event.point !== null) console.log(event.point.id, event.point.coordinate)
  if (event.move !== null) console.log(event.move.phase, event.move.busy, event.move.pending, event.move.releaseState, event.move.markerPresent, event.move.durationSeconds, event.move.remainingDistanceMeters, event.move.elapsedSeconds, event.move.passedPointCount, event.move.position, event.move.positionSource)
  if (event.type === 'move-complete' || event.type === 'move-error') moveId.value = ''
  if (event.type === 'snapshot-ready' && event.snapshot !== null) {
    savedImageId.value = event.snapshot.id
    const image = event.snapshot
    message.value = `${image.width}×${image.height}物理像素，完整度：${image.complete === null ? 'SDK未确认' : image.complete ? '完整' : '未完整'}，原状态${image.renderStatus ?? '无'}，时间${image.timestamp}，临时路径${image.path}`
  }
  if (event.type === 'snapshot-ready' || event.type === 'snapshot-error') snapshotId.value = ''
  if (event.errCode !== 0) message.value = `错误${event.errCode}，原码${event.nativeErrorCode ?? '无'}，${event.reason}；占用以event.state为准`
}
onShow(() => { if (!leaving) active.value = true })
onHide(() => { if (!leaving) active.value = false })
onUnload(() => { leaving = true }) // 组件卸载释放自己的资源，不在onUnload重置响应式挂载条件
</script>

takeMapSnapshot() 也允许省略整个参数。同步返回的 ID 只表示本请求已受理；移动活动、完成或截图由 advanced-event 通知。取消会立即停止向用户交付该请求，但 SDK 没有取消能力时仍保留 busy/pending。截图成功可以是未完整渲染的 PNG，不能把状态 0 或 complete=null 当成完整；临时图需要长期保存时，应在组件销毁前由宿主自行复制。

前台围栏完整调用

先完成隐私与SDK初始化，并由用户主动取得精确定位授权、开启系统定位服务。围栏启动不会弹授权框；ready只表示本地通道准备完成。以下页面手动输入GCJ-02中心，不自动提交预设城市。完整示例包含三标签、真实记录、按需地图、参数、状态和有界日志。

<template>
  <view>
    <input v-model="businessId" placeholder="业务ID，1至64字符" />
    <input v-model="latitude" placeholder="GCJ-02纬度" />
    <input v-model="longitude" placeholder="GCJ-02经度" />
    <button @click="start">准备会话</button>
    <button :disabled="!ready" @click="add">注册圆形围栏</button>
    <button :disabled="sessionId.length === 0" @click="remove">移除输入ID</button>
    <button @click="refresh">读取自有记录与管理状态</button>
    <button @click="stop">结束本会话</button>
    <text>{{ message }}</text>
    <text v-for="item in records" :key="item.requestId">{{ item.id }} · {{ item.phase }} · {{ item.lastRelation ?? '尚无关系回执' }}</text>
  </view>
</template>
<script setup lang="ts">
import { ref } from 'vue'
import { onHide, onUnload } from '@dcloudio/uni-app'
import { startMapGeofenceSession, addMapCircleGeofence, removeMapGeofence, stopMapGeofenceSession,
  getMapGeofences, getMapGeofenceState, getMapGeofenceCapabilities } from '@/uni_modules/lizhao-map'
import type { MapGeofenceEvent, MapGeofenceInfo } from '@/uni_modules/lizhao-map'
const businessId = ref(''), latitude = ref(''), longitude = ref(''), sessionId = ref('')
const ready = ref(false), message = ref('等待操作'), records = ref<MapGeofenceInfo[]>([])
let exited = false
function report(error: unknown) { const value = error as { errCode?: number }; message.value = `操作失败：${value.errCode ?? 9101029}` }
function receive(event: MapGeofenceEvent) {
  if (exited || event.sessionId !== sessionId.value) return
  if (event.type === 'ready') ready.value = true
  else if (event.type === 'registered') message.value = `SDK已确认注册；请求 ${event.requestId}`
  else if (event.type === 'status') message.value = `${event.fence?.lastRelation ?? '未知'}；${event.firstObservation === true ? '首次关系观察，可能是初态' : '后续SDK关系观察'}`
  else if (event.type === 'removed') message.value = 'SDK名单已观察不到该自有圆；这不证明OS定位线程停止'
  else message.value = `围栏错误 ${event.errCode}；原生码 ${event.nativeErrorCode ?? '未提供'}`
  if (event.state === null) message.value += '；管理状态未知，请重新读取'
  refresh()
}
function start() {
  try {
    const cap = getMapGeofenceCapabilities()
    if (!cap.supported) { message.value = cap.note; return }
    sessionId.value = startMapGeofenceSession({ startupTimeoutMs: 30000, onEvent: receive })
    ready.value = false; message.value = '会话已受理，等待本地ready'
  } catch (error) { report(error) }
}
function add() {
  if (latitude.value.trim().length === 0 || longitude.value.trim().length === 0) { message.value = '请完整填写中心坐标'; return }
  try {
    const requestId = addMapCircleGeofence({ sessionId: sessionId.value, id: businessId.value,
      center: { latitude: Number(latitude.value), longitude: Number(longitude.value) }, radiusMeters: 1000, timeoutMs: 30000 })
    message.value = `注册已受理：${requestId}，等待真实SDK回执`
  } catch (error) { report(error) }
}
function remove() { try { removeMapGeofence({ sessionId: sessionId.value, id: businessId.value }); refresh() } catch (error) { report(error) } }
function refresh() {
  try {
    const state = getMapGeofenceState()
    ready.value = ready.value && state.sessionId === sessionId.value && state.phase === 'ready' && state.deliveryMode === 'open'
    if (sessionId.value.length > 0) records.value = getMapGeofences(sessionId.value)
  } catch (error) { report(error) }
}
function stop() {
  try { stopMapGeofenceSession(sessionId.value); ready.value = false; refresh() } catch (error) { report(error) }
}
onHide(() => { if (!exited) stop() })
onUnload(() => { exited = true; try { stopMapGeofenceSession(sessionId.value) } catch (_) {} })
</script>

业务ID在同一会话内不可覆盖，正常移除并确认名单缺失后才可重用。remove立即静默该项尚未交付的注册/关系数据；未决SDK注册仍保留占用，迟到结果只用于清理。stop先静默整会话，不交付后续关闭成功事件，调用方主动读状态。再次启动需真实busy=false，后台返回不自动续启。

搜索到模拟导航的完整串联

宿主注册完整示例路由后可直接打开：

uni.navigateTo({ url: '/uni_modules/lizhao-map/example/uniappx/journey' })

Search策略32与Navi策略10分别属于不同引擎，不互转数值。当前Search方案只用于预览，不将其path.id、结果DTO或轨迹点组当成Navi路径凭据；新算路结果可能不同。模拟也可能使用SDK内部定位，不能绕过现有授权或资源门禁。

页面交接复用示例内navigation-demo-state.ts。它深拷贝起终点、可用POI标识和模拟设置，只保存在当前进程；URL只带不透明handoff关联ID，不携坐标、地点名、搜索正文或载荷。展示页只按准确ID消费一次，来源只信本地交接记录。旧页的迟到失败或卸载只能清自己的ID，不能清后来准备的行程；进入子页引发父页隐藏时不提前清掉待消费数据。

从串联页进入后，“退出”返回原串联页；空态/恢复入口也保留可信来源。直接重开旧URL或刷新使进程内交接缺失时，不会自动恢复旧坐标、创建导航或启动模拟，需重新准备。关键词、坐标、地点标识与交接ID不进入示例日志。完整独立搜索、五方式路线、四方式/GPS/货车参数仍在各自页面。

模块化示例

可将初始化封装为以下业务函数，页面直接传入 Key 与真实隐私状态。

import { setMapPrivacy, initializeMap } from '@/uni_modules/lizhao-map'
import type { MapPrivacyOptions } from '@/uni_modules/lizhao-map'

export function startMap(apiKey: string, privacy: MapPrivacyOptions) {
  setMapPrivacy(privacy)
  return initializeMap({ apiKey: apiKey })
}

多个 LizhaoMap 组件会生成独立实例。每个实例使用各自的 ref、camera、options；通过 event.instanceId 记录事件，不把一个实例的相机目标回写到另一个实例。

API 用途速查

配置、状态/能力读取、SDK本地工具和组件ref方法为同步接口；地点搜索和四类地理查询返回ID后异步交付结果。地图加载及变化通过 map-event 通知。相机/边界读取与投影需要等待ready，组件卸载释放原生地图与监听。

字段读取代码见高级示例，errMsg 与初始化结果见简单示例。

地图组件与方法参数

camera、options 均传完整对象；省略整个属性时使用组件默认值。传入 false 或 0 会保留该值。

属性传递、ref 方法与页面显示/隐藏代码见完整示例。destroy() 无参数，重复调用安全；销毁后 getter 或更新方法返回 9101008。重建时先 v-if=false，等待 nextTick 后创建新的组件，不能向已绑定的同一个 native-view 再绑定另一原生地图。

边界跨越日期变更线时，西南经度可能大于东北经度。读取四项边界和实际相机的代码见完整示例 inspectView。

地图事件

组件统一通过 @map-event 返回 MapEventDetail。

ready 表示加载就绪，恢复渲染时可能再次返回；camera-change 在相机变化结束时返回。组件等待约 25 秒未就绪会通知 9101010，随后原生加载成功仍可返回 ready。处理各类型、读取全部字段见完整示例和地图页的“实例与事件”标签。

标记事件为 marker-click、marker-callout-click、marker-drag-start、marker-drag、marker-drag-end。拖动读数来自原生对象，替换/移除后的旧对象事件会丢弃；高频拖动事件请自行按业务需要节流。onOverlayEvent 演示全部分支。当前不提供线/圆/多边形点击事件。

标准组件适配器

MapViewController 是标准组件使用的 App 原生容器适配器。普通页面使用上述组件和 ref 即可；需要自行封装标准组件时，必须在 native-view 的 init 事件中创建，每个元素只绑定一次。

// 仅限 App 标准组件脚本；camera/options 参数来自组件属性。
import { MapViewController } from '@/uni_modules/lizhao-map'
import type { MapCamera, MapViewOptions } from '@/uni_modules/lizhao-map'

function bindMap(element: UniNativeViewElement, camera: MapCamera, options: MapViewOptions) {
  const controller = new MapViewController(element, camera, options)
  controller.setActive(true)
  return controller
}

function releaseMap(controller: MapViewController): void {
  controller.release()
}

适配器提供同样的 MapViewContext 方法，另有 release() 供组件卸载时调用；iOS 会清理 SDK 监听与 JS 交付路由，失去引用的原生代理由运行时回收。适配器通过元素的 mapstate 事件传递上述字段，标准组件转发为 map-event。完整事件接线、卸载和错误处理见 components/lizhao-map/lizhao-map.uvue。

前台权限与单次定位参数

权限只读检查无参数、不弹系统框、不读取位置、不创建高德定位对象。申请权限要求三项隐私均同意，但不要求 SDK 初始化；单次定位另要求初始化完成、前台定位权限与系统定位服务可用，不隐式请求权限。

0 超时是无效参数，不会替换成默认值；false 地址配置会保留。定位成功只交付一次，超时/取消/结束后注销监听并丢弃迟到结果。取消权限等待不会关闭系统权限框；取消已打开的设置请求也不会关闭系统页面。

权限与定位输出

字段读取、拒绝分支和 null/0/false 判断见完整示例。页面隐藏或退出应取消自己保存的请求 ID，并设置非响应式退出标记来丢弃旧页面回调；响应式数据在 onUnmounted 清理，避免退出过程重新渲染。

覆盖物方法与参数

以下方法均通过地图组件 ref 调用。变更、summary、实际标记位置和范围适配需等待 ready；能力可在实例已创建时读取。每批不超过 500 项。ID 在每个地图、每种覆盖物内独立；一批重复同类 ID 不合法，不同类型可用相同 ID。参数错误整批不会调用原生变更，图片格式/实际尺寸由原生进一步检查。

clearOverlays()、getOverlaySummary()、getOverlayCapabilities() 无参数。clear 只移除本插件当前地图创建的四类对象，不清除 SDK 自有图层；销毁或撤回隐私会同时释放覆盖物、图片和监听。SDK 执行中发生异常可能部分变更，使用 summary 检查当前对象后重试/clear，不将同步批次视为数据库事务。

标记字段：

不请求网络图片，不接受 SVG 或任意文件路径。示例 PNG 与界面 SVG 使用同组图形；接入者可以使用自身本地图片内容。title/snippet 都为空或标记隐藏时，显示气泡返回参数错误；关闭气泡不要求有文字。SDK 默认气泡布局由平台提供，多气泡须读取实际能力，不能将多次调用自动当作多开成功。

当前三端固定 SDK 的默认气泡均只支持单个选中标记，本插件 multipleCallouts=false；customMarkerImage 与 markerDrag 为 true，仍需在匹配的原生集成环境验收。自定义多个同时可见气泡不属于默认气泡接口，当前没有模拟该能力。

iOS 程序化显示屏幕外标记的默认气泡时，SDK 可能调整地图中心；需要保持视口时先将标记放入当前范围，再显示气泡。iOS 拖动过程按屏幕刷新读取原生标记的实际坐标，只有坐标变化才发事件，隐藏、移除和销毁均停止读取。

图形的共同样式与几何：

所有数值须为有限数，0 与 false 不被默认值覆盖。尺寸为公开逻辑像素：Android 按 density、鸿蒙按 vp2px 转换到 SDK 像素，iOS 使用点。zIndex 仅用于同一渲染层，标记层与线面层不承诺相互穿插。

完整赋值、读取、能力分支、事件、替换和清理代码见 drawOverlays、onOverlayEvent、updateAndRemoveOverlays，逐项操作见覆盖物演示页。参数错误与原生错误均抛统一 MapFail，页面应捕获并保留原来成功的状态，不提前显示操作成功。

持续会话参数与输出

startMapLocationSession(options)受理后返回新会话ID；前置或参数失败同步抛MapFail。stopMapLocationSession(sessionId)、getMapLocationSessionTrack(sessionId)、clearMapLocationSessionTrack(sessionId)的参数如下；停止旧ID为空操作，读取/清空旧ID为9101019。getMapLocationSessionState()与getMapLocationBackgroundStatus()无参数。

requestMapLocationNotificationPermission(options)返回可取消请求ID，success/fail/complete在返回后交付。拒绝进入success且state=denied；取消等待不关闭系统弹窗。

清空不删除宿主已导出的文件；隐私撤回停止会话并清空原生位置缓冲，此后读取轨迹返回9101002。后续成功受理新会话才替换旧轨迹，失败启动不覆盖上次结果。位置timestamp保留SDK原始值，0和false均有效，不可用为null。lastFixReceivedAt在合法点被间隔/距离过滤时仍刷新，用于识别最近采样；计数只计算通过过滤的点。iOS的intervalMs用于交付过滤，不承诺降低系统采样频率。

地点搜索参数

getMapInputTips(options)、searchMapPois(options)、getMapPoiDetail(options)受理后返回请求ID，回调在函数返回后交付；参数和前置失败也通过fail/complete结束。success与fail互斥，complete至多一次。能力/状态读取为同步纯查询；cancelMapSearchRequest(requestId)传入自己持有的请求ID，对已结束或非本插件ID为空操作。

矩形/多边形不能同时传city、cityLimit=true、center或其他几何对象，排序为comprehensive。坐标顺序在公开类型中始终是 { latitude, longitude }，不要直接复制原厂经度在前的字符串。示例代码已覆盖关键词+城市限制+距离排序、无过滤周边+半径0、矩形、多边形、仅类型搜索、基础/五组字段和单ID详情。

搜索输出与平台差异

单请求提示上限100条，POI列表上限为pageSize，单POI子项最多1000条、照片100条、单值文本4096字符、序列化结果2MiB。超界或字段无效返回9101020，不静默裁剪后声称完整。取消仅终止本插件等待；Android/鸿蒙SDK没有对应公开取消入口，已发请求保留内部回执记录至SDK返回，届时释放槽。iOS按该请求独占的SDK实例调用真实取消方法，不影响其他调用者。上述行为均不承诺撤销已经发送至远端的数据。

地理信息和SDK工具参数

四类地理异步API先返回ID，参数/前置失败也在返回后通过fail/complete交付；回调至多一次，隐藏/退出按页面保存的ID取消。地理查询自有四槽（含retired），与地点搜索通道分别管理。本地工具为同步API，非法输入、环境或SDK异常抛MapFail。下表中点均为 { latitude, longitude }、GCJ-02；转换来源点依fromType解释。

行政区没有有效level过滤参数，按查询结果的level读取，不从已废弃setter推断支持。逆编码仅处理给定坐标；若输入来自WGS-84/百度等，请先按真实来源转换。矩阵的整体请求成功仍可含失败行，不以success回调替代每个item.success判断。

地理信息和工具输出

正向候选和每类逆向集合最多1000，行政区总节点5000/深度8/边界总点200000，面积500顶点；基础文本4096字符、最终UTF-8结果16MiB。达到客户端防御上限或坏字段返回9101022，不静默裁剪。例页对大结果按层级/分组浏览，地图单图形超过5000点时以真实点分段或明确显示限制，查询数据保持完整。

投影需要当前实例可用、ready和有效视口。Android/Harmony原生物理像素经密度转换，iOS使用本地UIKit points；整数像素量化、相机旋转/倾斜会影响往返，不能要求坐标严格相等。屏幕点属于当前地图，不是全屏/页面坐标，不复用其他地图实例的投影结果。

路线规划参数

字符串统一trim且拒绝控制字符。不接受其他方式组参数，不静默丢弃未支持开关。途经上限依据固定客户端校验和iOS搜索更新说明；部分旧Android/鸿蒙注释仍写6，服务能否返回16点方案须以实际账号/地区验证。

策略表示SDK规划偏好，不保证实际方案的耗时、收费或通行结果。示例页可在请求前查看当前值含义并展开选择。以下数值已与固定SDK常量核对；语义依据官方驾车策略、公交策略、货车策略。公交0是新版推荐模式，不能套用旧版“最快捷”的说明。

路线输出与平台差异

SDK模型没有可靠数值presence：已请求且该端可用的合法0/false保留；未请求/不适用/不支持/父对象缺失为null。0不能证明远端确实给了该字段。Android/鸿蒙驾车总时长读取Cost，iOS读取原厂扁平映射。鸿蒙骑行只有各步时长全可用时求和并标steps-sum，缺项为null/unavailable；步行/骑行有错键的roadType为null。

驾车restrictionCode 0为无/已规避、1无法规避；货车0未知、1已规避、2起点/3途经/4区域/5终点限行。铁路waitMinutes保留SDK原数值：鸿蒙固定版本注释写秒，但真实parser原样读取wait，官方铁路换乘字段写分钟，因此按分钟解释；此注释冲突仍须真实服务验证。

客户端防御上限按整个结果累计：20方案、20000步骤、1000公交段、20000辅助项、200000几何点，文本4096字符、最终UTF-8 16MiB。坏字段/超界返回9101023，不截断成功数据。没有轨迹的部分保持缺失并在预览提示。每请求独占SDK对象，Android/鸿蒙取消/超时仍保留retired记录到实际回执，无回执可能持续占四槽；iOS只取消自身搜索实例。重新同意隐私不会恢复旧结果。

导航组件、方法与参数

getMapNaviCapabilities() 返回固定能力，getMapNaviState() 返回插件全局占用缓存；均无需初始化，也不会为查询而创建 SDK。普通页面使用 lizhao-map-navi。App 自定义适配器可用 new MapNaviController(element, traffic, transport, voiceEnabled)；其接口与组件实例相同。直接适配器须监听 native-view 的 navistate 并在卸载调用 destroy()；建议使用标准组件处理 ref/ready 与 UI 解绑。

货车参数仅在 transport="truck" 使用。固定SDK对尺寸字段明确注明type1生效，本插件当前只开放燃油货车1；其他燃料货车暂不开放，避免参数被静默忽略。货车路线服务的开通、费用及配额请向高德确认；不保证结果完全避开现实通行限制。高德车辆说明

MapNaviCapabilities：

MapNaviState 与全局 MapNaviGlobalState：

MapNaviRouteResult 与 MapNaviRoute：

MapNaviEvent（组件事件名为navi-event）：

MapNaviInfo 与 MapNaviLocation：

高德原厂说明中国大陆及港澳台输出高德坐标，海外输出WGS84，因此导航结果使用amap标签；国内高德坐标为GCJ-02，示例输入采用国内高德坐标。坐标范围说明，高德坐标说明。

每条路线最多128标签，全部结果合计最多20路线/200000坐标，单文本4096 UTF16、最终UTF-8 16MiB，超界报24而非截断。核心高频进度/位置在同一次交付批次合并为最新值；结束/错误等保留顺序。界面展示本次实际字段，日志建议仅保留类型、实例/请求ID和错误码，并限制容量。

导航引擎是进程单例，宿主不得再并行直接管理同一导航SDK。getMapNaviState只读取本插件的导航缓存；空闲不代表其他代码未持有SDK或定位资源，创建时仍会检查实际占用。退出只清理本插件自己的视图、监听、路径和导航定位；Android先销毁自己的NaviView再销毁引擎，鸿蒙先解绑Builder再回收Factory，iOS移除自身representatives与强引用后检查destroy结果。SDK层released不等于已经实测OS全部采样/线程停止；撤权、服务关闭或异常不能确认时保留uncertain/busy。无回执时可能持续回收，需匹配环境核查或重启进程，不按定时器假解锁。重新同意隐私不复活旧路线/车辆/位置。

巡航结果与系统语音

speakMapText 同步返回请求ID，同步门禁失败抛统一错误；受理后OS失败走事件。stopMapSpeech 返回void并立即抑制该请求用户交付；停止后用 getMapSpeechState 读取清理。getMapSpeechState 与 getMapSpeechCapabilities 只读缓存，不创建系统引擎，不申请麦克风或定位。

Android仅选已安装、中文中国且无需联网的Voice；鸿蒙使用系统离线模式，资源缺失真实失败，不下载或改在线。iOS只调用系统AVSpeechSynthesizer，不接云服务，但没有公开接口保证设备离线资产和系统网络行为。无需地图Key或SDK初始化；隐私三项和前台仍须满足。系统引擎关闭及本地解绑只证明自身对象回收，不等于已在设备上验证物理声音或所有OS线程停止；初始化Promise未结束或清理无法确认时保持占用。

离线会话参数与输出

getMapOfflineState() 和 getMapOfflineCapabilities() 无参数，不构造 SDK、不弹权限。四项城市操作返回唯一 operationId。getMapOfflineCatalog() 未就绪报 9101010、失效会话报 9101008；停止会话立即清除本会话排队的用户回调，后台释放仍须读取真实状态。

宿主不得并行直接创建或操作其他离线 manager：SDK 内部是共享单例，插件只能约束自己的 owner。默认使用 SDK 应用专属存储，不新增广泛存储权限，不改全局网络或缓存目录。下载/删除必须由用户主动触发；只管理所选城市，不全盘清理，不删除文件系统目录。停止会话保留已安装数据。

Android/鸿蒙删除需匹配删除回执并读取 SDK 缓存确认；iOS 无删除回调，只确认该项 SDK 可见缓存缺失，不能据此声称物理文件擦除或线程已退出。目录构造、排队启动、解压或删除未决时，退出/超时后可能继续占用，需等待原 SDK 管线结算，不能用倒计时假释。三端均无城市中心字段，示例地图用明确的独立手动坐标。默认优先本地缓存不等于强制断网，断网底图须在已授权真机验收。

高级地图参数与输出

以下均为 lizhao-map 组件 ref 方法。层/项 ID 保留原值，1–64 字符、合法 UTF-16、无控制字符/首尾空白，同层项 ID 唯一，字符串 '0' 有效。坐标为 GCJ-02，尺寸和容量属于插件共同合同。

clearAdvancedLayers() 清三种高级层、取消自有移动/截图并回收已注册临时图；clearOverlays() 仍只清普通覆盖物。隐藏取消移动与截图交付，静态层保留，返回前台不会自动续播。releaseState=uncertain 必须保留占用，不能按计时假释；SDK真终态与清理失败以实际状态为准。协议失败后重建地图再使用高级方法；invalid-result-last-known 是最后可信快照，不能当作当前释放确认。

前台围栏参数与输出

三端只启用进入/离开激活，SDK可能返回unknown或stayed；没有自定义停留时长承诺。Android/iOS注册后由专用SDK内部定位，鸿蒙由独立真实定位回调驱动SDK判断；两者均不在插件中计算距离伪造关系。围栏不依赖地图创建，示例按需画出的圆只是输入/确认几何，不能证明监控已经运行。Web只预览界面，不生成成功或定位事件。

围栏API调用顺序

能力与管理状态纯读；startMapGeofenceSession → 等本地ready → addMapCircleGeofence → 等真实registered/status → getMapGeofences。removeMapGeofence按sessionId+业务ID精确移除，stopMapGeofenceSession结束自己的会话。页面隐藏/退出和撤隐私均关闭交付；SDK无删除terminal，正常名单缺失可释放逻辑记录，未决注册/部分启动不明则保留真实busy。

错误码说明

示例与平台接入

示例首页为宿主 pages/index/index.uvue，宿主 pages.json 注册17条真实路由。完整演示位于插件 example/uniappx/，覆盖接入、地图、定位、覆盖物、查询、工具、路线、导航、巡航语音、离线、地图进阶、围栏与业务串联。结果按实际字段、空值和失败展示；Web提供界面预览与本地校验。

iOS 使用 HBuilderX 5.34 及以上版本，通过插件根入口导入。请完整保留 utssdk/app-ios/interceptor.js、bridge-core.uts 与 facade/：同步校验和统一错误在 JS 层处理，SDK 调用通过原生桥接完成。插件根 index.d.ts 提供公开类型声明，导入时应保留整个插件目录。

路线页包含五种方式、完整参数、公交备选与真实分段；导航配置/展示两页包含四种方式、Navi独立算路、选路、GPS/模拟、实时信息和释放状态。串联页把明确选择的端点与模拟设置一次性交接给Navi重新算路，Search方案ID不能作为导航凭据。地图进阶提供三种数据层、点移动和临时截图；前台围栏提供真实注册、关系和自有清理。Android Key绑定宿主包名与签名，iOS Key绑定Bundle ID，鸿蒙Key绑定高德要求的应用身份。

后台定位需要宿主原生集成配置，导入源码后应重新制作匹配基座或运行包：

• Android插件Manifest含FOREGROUND_SERVICE、FOREGROUND_SERVICE_LOCATION、POST_NOTIFICATIONS及location类型的私有服务。采用从前台启动定位前台服务路径，不自动申请ACCESS_BACKGROUND_LOCATION。Android13+主动申请通知，旧系统仍读取真实通知开关。通知支持点击回App及停止本会话。
• iOS插件Info.plist含UIBackgroundModes.location及WhenInUse用途说明；确认最终Bundle保留能力并签名后使用。只请求使用期间授权，从前台开始的连续后台定位不请求Always，也不提供进程重启恢复。使用原生后台位置指示。
• 鸿蒙前台持续最低API20，后台最低API21。插件声明LOCATION_IN_BACKGROUND、KEEP_BACKGROUND_RUNNING及定位用途；后台位置授权需用户进入设置，通知单独申请。宿主EntryAbility的backgroundModes须含location：将自己的生成entry/src/main/module.json5复制到项目harmony-configs/entry/src/main/module.json5，在原Ability上添加该字段并保留宿主配置。本项目已提供该真实覆盖文件。详见DCloud鸿蒙配置覆盖说明；最终检查生成HAP的合并结果。

Android 固定导航地图定位搜索合包 11.3.100_3dmap11.3.100_loc11.3.000_sea9.8.1。iOS 固定 NO-IDFA Navi 11.2.100、Location 2.12.2、Search 9.8.1、Foundation 1.9.1。鸿蒙固定 navi/common/location/search 11.2.1，地图使用导航包内实现，无需再添加另一地图 SDK。

注意事项

• 三项隐私必须全部为 true 才允许初始化，宿主负责政策内容与用户选择。
• 仅将 Key 保存在当前进程中，示例不会持久化 Key，运行日志不包含 Key。
• 同 Key 可以重复初始化，进程开始配置后更换 Key 需要重启。
• 错误演示会改变当前隐私状态，测试后需重新同意并初始化。
• 隐私撤回会关闭所有地图；恢复同意并初始化后，须创建新组件。页面隐藏传 active=false，退出移除组件以释放 SDK 监听和地图资源。
• 地图浏览、覆盖物及按手动条件搜索不主动申请定位权限，不显示当前位置蓝点。定位由用户主动触发；示例地图中心联动真实结果。路线规划使用独立Search结果；驾车导航使用Navi自身真实路径组，两者ID不能互换。
• 搜索数据通过各端原生高德SDK发送，宿主需向用户说明关键词、城市、输入中心/范围及POI ID的用途。搜索页不自动逐字请求，隐私撤回会结束搜索等待并清除页面地点与地图缓存；已发送的数据不能由插件追溯撤回。
• 搜索取消与定位取消分别使用各自API。页面隐藏/退出仅取消自己保存的搜索ID，迟到回调不能覆盖新条件的列表。新提示成功后清除旧提示的地图关联，需重新选择本次提示；分页使用成功query快照，不将输入修改与旧页码混用。
• 地理信息/矩阵使用cancelMapGeoRequest，原生四槽与地点搜索分别管理。Android/鸿蒙取消后仍等SDK回执释放retired记录；iOS只取消各请求自己的API实例。超时不修改SDK全局网络设置，也不承诺已经撤销远端请求。
• 地址、起终点、行政区和转换来源均是用户输入条件。坐标转换可原样返回，changed/dataAvailable不是鉴权或转换正确性证明；矩阵整体成功时仍要逐项判断success，失败项不能用0代替null。工具和投影不申请定位，SDK行为仍须隐私披露。
• 行政区边界保留原厂多段及顶点；省市大边界可能超过单地图图形5000点限制。示例通过分段或选择边界展示，并明确说明未绘制部分；不要为显示方便静默改写查询结果。矩形/多边形面积为SDK估算，输入限制、极区与日期线边界见参数表。
• 覆盖物按地图实例/类型/ID隔离，upsert完整替换；移除/隐藏标记关闭气泡，退出释放监听。实际拖动后重新读取位置，避免用旧表单坐标覆盖拖动结果。
• 高级图层和点移动使用宿主主动提供的点与路径；移动路径不是实际定位轨迹。地图截图只含当前地图区域，写入应用临时PNG，由本实例管理回收；插件不主动上传截图，宿主导出或分享应另行说明用途。
• 前台围栏由SDK处理用户输入的圆形区域和定位关系，不提供后台或进程恢复；隐藏/退出清理自己的会话。首条inside/outside可能是初态，SDK名单缺席不能证明系统定位线程已经停止。
• 定位用途文案请按宿主实际业务检查。Android/iOS持续后台沿用前台/使用期间授权与各端后台机制；鸿蒙后台位置权限由用户在系统设置开启。系统授权、通知、服务和SDK初始化为独立条件。
• 会话与单次定位互斥，停止/异步清理期间保留互斥。后台模式由用户主动开始；返回前台读取原生轨迹，页面真正退出时停止自己的ID，不在App退后台时误停后台会话。系统杀进程、撤权、省电或厂商限制可结束运行，插件不绕过系统限制。
• 鸿蒙定位会暂时关闭高德 SDK 的自动长任务策略，由插件管理自己的系统任务，全部清理后恢复原值。同一进程在本插件定位运行期间应避免通过其他入口改写该 SDK 全局开关。
• 固定鸿蒙 SDK 11.2.1 的停止方法会检查定位授权。插件先关闭该管理器的后台选项，再确认自身监听已停止；前台授权全部撤回或系统注销失败时仍保留 stopping，恢复前台授权/服务后自动重试。若 SDK 部分启动且从未确认 isStarted，无法证明已回收时需结束应用进程后重新进入；仅返回页面不能解除这类占用，期间新定位仍返回9101016。此时自有系统后台任务仍会独立回收，不全量停止宿主任务。
• Android 关闭公开定位缓存开关并排除明确的缓存结果；iOS/鸿蒙使用新管理器和真实单次 API，SDK 没有相同缓存开关时不伪造该能力，返回原始位置时间。鸿蒙 SDK 的在途系统单次请求无法强行中止时，取消后清理 SDK/回调并丢弃迟到结果。
• 地图、定位、查询及Search路线按各自返回的coordinateType使用GCJ-02，角度单位为度、缩放为级别。导航结果标记为amap，保留SDK原厂坐标：国内GCJ-02、海外WGS84，不二次纠偏；不要把原始WGS-84输入直接当作GCJ-02。
• 原生指南针可见性受旋转状态影响。统一缩放按钮与四类地图手势分别配置，保留原厂 Logo。
• 示例图标随插件位于 static/icons/，统一为 24 × 24、2px 线宽的线性 SVG；请保留资源路径。
• 原生 SDK 运行需要匹配依赖的集成环境，iOS 需要可用的原生构建环境和签名。
• 高德SDK的数据处理、固定依赖和使用条件见第三方说明及原厂政策；宿主须按实际启用的能力披露并取得授权。

作者系列 UTS 插件

以下为作者已上架的 UTS 插件，详情见各市场页面或作者主页。作者主页