原生地图 Map

Map 在仪表里显示真实的原生地图。CapDrive 负责定位、坐标显示转换、地图实例与相机更新。你可以配置跟随方式、样式、路线和偏移。

最简单的用法

jsx

function main() {
  return <CardContent title="当前位置" fulled={true} headerBlurColor="clear">
    <Map width="fill" height="fill"/>
  </CardContent>;
}

相机与外观

属性	值 / 默认	说明
`showUserLocation`	布尔值，默认 `true`	是否显示定位点，不决定是否跟随
`followMode`	`MapFollowMode.userLocation` / `.latestData`	默认跟随系统地图当前位置；另可跟随当前数据
`position`	`"current"` 或 `{latitude, longitude}`	固定坐标优先于跟随模式
`regionPixelOffset`	`[x, y]`，默认 `[0, 0]`	以屏幕逻辑点移动可视区域中心
`headingPolicy`	`MapHeadingPolicy.northUp` / `.vehicle` / `.path`	北朝上、车辆方向或路线方向
`appearance`	`MapAppearance.automatic` / `.light` / `.dark`	跟随 App 或固定主题
`mapStyle`	`MapStyle.standard` / `.satellite` / `.hybrid`	标准、卫星、混合
`pitch`	度，默认 0	地图俯仰

地图区域大小使用内部的固定地理尺度，没有公开的 distance 属性。不要把普通网页地图库的缩放参数复制进来。

跟随系统位置与跟随数据

jsx

<Map followMode={MapFollowMode.userLocation}/>
<Map followMode={MapFollowMode.latestData} showUserLocation={false}/>

隐藏定位点仍然可以跟随。latestData 在数据或显示坐标转换尚不可用时，会回退到当前系统地图位置。固定 position 则覆盖跟随：

jsx

<Map position={{latitude: 31.2304, longitude: 121.4737}}
  headingPolicy={MapHeadingPolicy.northUp}/>

固定经纬度和路线坐标按 WGS-84 提供，显示时由 CapDrive 处理所在地区要求的转换；不要在源码里重复转换。

区域偏移的方向

regionPixelOffset 移动的是可视区域中心，不是直接把定位点拖到某个屏幕位置。

正 X：可视区域中心向右，目标点看起来向左。
正 Y：可视区域中心向下，目标点看起来向上。
[0, -40]：让目标点在卡片里相对向下，方便为顶部标题留空间。

偏移使用与卡片尺寸相同的逻辑点单位，会换算到固定地图视口中。

绘制路线

属性	说明
`path`	WGS-84 坐标数组；用 `null` 分隔不连续段
`pathStyle`	`MapPathStyle.normal` 或 `.arrow`
`pathWidth`	主路线宽度，默认 4 点
`pathColor`	路线颜色
`pathOutlineWidth`	每侧轮廓宽度，默认 1；0 为关闭
`pathOutlineColor`	路线轮廓色

jsx

<Map path={[
  {latitude: 31.2304, longitude: 121.4737},
  {latitude: 31.2310, longitude: 121.4742},
  null,
  {latitude: 31.2320, longitude: 121.4750}
]} pathStyle={MapPathStyle.arrow} pathColor={$env.accent}/>

$data.history 只有最近 30 秒，不是完整行程轨迹。不要把短窗口路线标成“完整行程路线”。

支持与不支持的叠加

可以使用布局、二维 Transform、透明度、圆角和几何裁切。原生 Map 不能放在像素滤镜、alpha Mask 或 RepeatedLayout 的子树里。

需要渐变模糊时，把材质和遮罩作为地图之上的独立兄弟节点，参见地图与渐变材质。地图保持原生实例，不应通过不断更换随机 key 强制重建。

原生地图 Map ​

最简单的用法 ​

相机与外观 ​

跟随系统位置与跟随数据 ​

区域偏移的方向 ​

绘制路线 ​