miaoda-expo-maps-55
v0.1.3
Published
Miaoda customized Expo Maps for Expo SDK 55, rendering the official Baidu Maps Android SDK on devices with or without Google Mobile Services (Apple Maps on iOS).
Maintainers
Readme
miaoda-expo-maps-55
Expo 地图模块定制分支。Android 与 iOS 两端均以百度官方地图 SDK 渲染(Android 有无 Google 移动服务(GMS)均可),同一份 JS 代码(BaiduMaps.View + BaiduSearch)双端行为一致;上游的 AppleMaps.View 作为 iOS 专属组件原样保留。JS 侧坐标一律采用 WGS-84,原生层自动完成 BD-09 双向转换,与 miaoda-expo-location-55 遵循同一约定。
内部 fork 说明:本包 fork 自上游 expo-maps(SDK 57 分支),工程与依赖体系全面回退至 Expo 55 兼容(Kotlin 2.1.20、Compose 1.7.6、expo-module-scripts ^55.0.2)。57 → 55 回退清单、渲染层设计、坐标管线与 props 映射的完整说明见 BAIDU-MAP.md。
平台支持
| 平台 | 渲染引擎 | 入口组件 |
| --- | --- | --- |
| Android | 百度地图 SDK(BaiduMapSDK_Map:8.2.0,无 GMS 依赖) | BaiduMaps.View(别名 GoogleMaps.View) |
| iOS | 百度地图 SDK(BaiduMapKit 7.2.0 + BMKLocationKit 2.1.4,CocoaPods) | BaiduMaps.View(别名 GoogleMaps.View);另保留上游 AppleMaps.View |
| Web | 不支持 | — |
跨平台代码统一使用 BaiduMaps.View 与 BaiduSearch,无需按 Platform.OS 分支。iOS 实现与 Android 的 props、事件、命令式方法、错误码、默认值逐项对齐,差异与实现说明见 BAIDU-MAP.md 第 12 节。
iOS 模拟器:百度 iOS SDK 的 pod 向 App target 注入
EXCLUDED_ARCHS[sdk=iphonesimulator*]=arm64(SDK 不含 arm64 模拟器切片),Apple Silicon Mac 上只能使用 Rosetta(x86_64)模拟器或真机。
AppleMaps.View 的系统版本分层
AppleMaps.View 为上游实现语义保留——10 个 Swift 文件与 npm [email protected] 除空白格式(switch 表达式缩进、协议方法间空行)外完全一致,podspec 同为 15.1(验证记录见 BAIDU-MAP.md 第 11 节)。其系统版本分层沿用上游:
| 系统版本 | 行为 |
| --- | --- |
| iOS 18+ | 完整功能,全部事件可用 |
| iOS 17 | 基础渲染与相机控制;仅 onMapClick / onCameraMove 可用,onMarkerClick / onAnnotationClick / onPolylineClick / onPolygonClick / onCircleClick 不触发(类型定义已标注 @platform ios 18.0+) |
| iOS 16 及以下 | 渲染空白视图(上游 expo-maps 55 与 57 版本相同的既有行为,本 fork 未改动) |
若产品需覆盖 iOS 16 及以下设备,应在上游层面推动解决;本 fork 以与 expo-maps@55 drop-in 一致为契约,不单方面改动 iOS 行为。
与上游的差异(JS 视角)
新增:
onMarkerDragStart/onMarkerDrag/onMarkerDragEnd回调。上游的draggable属性存在但从不回传拖拽结果,实际不可用;本分支接通百度原生拖拽事件,事件坐标为 WGS-84。fitToCoordinates(coordinates, padding?)命令式方法:将视野动画适配到给定的一组坐标(可带 dp 边距);单点时直接移动相机,空数组时不执行任何操作。setPrivacyAgreed(agreed):必须在用户同意隐私政策后调用,之前地图不渲染、检索拒绝(国内应用市场合规要求)。- 内置「我的位置」:
properties.isMyLocationEnabled即显示蓝点(百度定位 SDK + 罗盘,含精度圈与朝向),onUserLocationChange回传 fix;userLocation新增accuracy/heading,传coordinates时覆盖内置源。 - 信息窗渲染
title+snippet(calloutStyle配色,onMarkerCalloutClick);点聚合markerClustering(onClusterClick);自定义热力图heatmap、百度城市热力isBaiduHeatMapEnabled;个性化地图customMapStyle;地图截图takeSnapshot()。 BaiduSearch.*LBS 服务:天气、POI(城市 / 周边 / 区域 / 详情)、输入提示、路线规划(驾车 / 步行 / 骑行 / 公交 / 跨城)、行政区边界、公交线路、AOI、建筑物、推荐上车点、短链分享。Android 专属,详见 BAIDU-MAP.md 第 7c 节。
移除:
GoogleMaps.StreetView。StreetView 为 GMS 专属功能,无 GMS 设备不可用,故未提供替代实现。
回落与忽略(详见 BAIDU-MAP.md 第 5.2 节):
properties.mapType = TERRAIN回落为NORMAL,HYBRID渲染为SATELLITE(百度卫星图无路网标注叠加层);properties.mapStyleOptions(Google JSON 样式)无百度对应物,被忽略并输出一次性警告;mapOptions.mapId、colorScheme静默忽略(样式改用customMapStyle);uiSettings中indoorLevelPickerEnabled、mapToolbarEnabled、myLocationButtonEnabled、scrollGesturesEnabledDuringRotateOrZoom无百度对应物,静默忽略;- 未指定自定义
icon的标记渲染为内置的红色水滴图钉。百度MarkerOptions要求必须设置图标(与 Google SDK 不同,后者内置默认图钉),本分支以 Canvas 绘制默认图标兜底。
其余 props、事件与命令式方法与上游一致。BaiduMaps 为本分支的正名命名空间,GoogleMaps 为其别名(View 指向同一组件,保留 MapType、MapColorScheme 枚举与各类型导出),以便沿用上游文档与既有代码;类型名保留 Google 前缀,确保 drop-in 兼容。
安装
本包以 pnpm workspace 协议消费,无需发布至 registry:
// package.json
"expo-maps": "workspace:miaoda-expo-maps-55@*"// app.json
"plugins": [
["expo-maps", { "androidBaiduApiKey": "<AK>" }]
]配置
插件参数
| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| androidBaiduApiKey | string | — | 三态:未设置时不动 manifest(保留其他插件写入的值);非空字符串写入;''/null 显式移除。目标条目为 AndroidManifest.xml 的 com.baidu.lbsapi.API_KEY meta-data |
| iosBaiduApiKey | string | — | iOS 百度 AK,同样三态,目标为 Info.plist 的 BaiduLbsApiKey(与 miaoda-expo-location-55 共用)。iOS AK 与 Android AK 分开申请:控制台类型选「iOS SDK」,安全码填 Bundle ID |
| requestLocationPermission | boolean | false | 是否向 manifest / Info.plist 追加定位权限声明 |
| locationPermission | string | Allow $(PRODUCT_NAME) to access your location | iOS NSLocationWhenInUseUsageDescription 文案 |
androidBaiduApiKey 与 miaoda-expo-location-55 共用同一条 com.baidu.lbsapi.API_KEY meta-data:两个插件写入的内容完全一致,重复执行幂等合并,不引入任何新增配置项。建议从环境变量读取,避免将 Key 提交至仓库:
EXPO_PUBLIC_BAIDU_ANDROID_API_KEY=<ak> npx expo prebuild --platform androidiOS 权限前置条件:在 iOS 上调用
useLocationPermissions/getPermissionsAsync/requestPermissionsAsync之前,必须开启requestLocationPermission(或自行在 Info.plist 添加NSLocationWhenInUseUsageDescription)。缺少该键时,原生层以 fatal error 终止应用(MapPermissionRequester的 fail-fast 设计,与上游expo-maps@55一致),而不是返回 denied。地图组件本身不依赖定位权限——常规做法是用expo-location获取权限(其插件默认写入该键)。Android 侧无此限制:权限查询走标准 Permissions 流程,未声明时仅返回 denied。
百度 AK 前置条件
- 在百度地图开放平台创建应用,类型选择「Android SDK」,绑定信息为
SHA1;PackageName指纹(发布版与调试版证书各一条); - 为该 AK 启用**「地图服务」**。仅开通定位服务的 AK 渲染空白瓦片,且通常没有其他报错——鉴权失败会输出到 logcat(tag
ExpoBaiduMaps),其中包含指纹与服务的核对指引; - 注意
expo prebuild(尤其是--clean)可能重新生成android/app/debug.keystore,导致签名指纹与控制台绑定值不一致,需在控制台更新 SHA1 字段。
使用
隐私合规
import { setPrivacyAgreed } from 'expo-maps';
// 用户在隐私政策弹窗中点击「同意」后(每次启动都需调用):
await setPrivacyAgreed(true);与 expo-location(miaoda-expo-location-55)共享同意状态,调用任一包的 setPrivacyAgreed 即可。用户撤回同意(设置页的「撤回隐私政策同意」)时调用 setPrivacyAgreed(false):地图卸载、内置定位与定位 watch 停止、检索实例释放。
基础示例
import { useRef } from 'react';
import { BaiduMaps } from 'expo-maps';
const BEIJING = { latitude: 39.9075, longitude: 116.3913 };
export function MapScreen() {
const mapRef = useRef<BaiduMaps.MapView>(null);
return (
<BaiduMaps.View
ref={mapRef}
style={{ flex: 1 }}
cameraPosition={{ coordinates: BEIJING, zoom: 13 }}
markers={[
{ id: 'tiananmen', title: '天安门', coordinates: BEIJING },
{
id: 'draggable',
title: '可拖拽标记',
draggable: true,
coordinates: { latitude: 39.915, longitude: 116.39 },
},
]}
polylines={[{ id: 'route', coordinates: [/* ... */], color: '#1E90FF', width: 6 }]}
circles={[{ id: 'zone', center: BEIJING, radius: 600, color: '#220000FF', lineColor: '#0000FF', lineWidth: 2 }]}
onMapClick={({ coordinates }) => console.log(coordinates)}
onMarkerDragEnd={(marker) => console.log(marker.coordinates)} // WGS-84
onCameraMove={({ coordinates, zoom }) => console.log(coordinates, zoom)}
/>
);
}颜色接受 #RRGGBB 或 #AARRGGBB 十六进制字符串。完整的 props、事件与类型定义见 src/google/GoogleMaps.types.ts 与 src/shared.types.ts(类型随包导出,含 JSDoc)。
命令式方法
// 动画移动相机(duration 单位毫秒,缺省用 SDK 默认时长)
mapRef.current?.setCameraPosition({ coordinates: { latitude: 31.2304, longitude: 121.4737 }, zoom: 12, duration: 2000 });
// 视野适配一组坐标,可带 dp 边距(fork 新增)
await mapRef.current?.fitToCoordinates(coordinates, { top: 40, bottom: 40, left: 40, right: 40 });
// 截图,返回缓存目录中的 file:// URI(fork 新增)
const uri = await mapRef.current?.takeSnapshot({ format: 'png' });
// 选中标记:弹出信息窗并可选动画;id 传 undefined 取消全部选中
await mapRef.current?.selectMarker('draggable', { zoom: 15, moveCamera: true });事件
| 事件 | 载荷 | 说明 |
| --- | --- | --- |
| onMapLoaded | — | 地图加载完成 |
| onMapClick / onMapLongClick | { coordinates } | 点击 / 长按地图(命中 POI 或标记时不触发) |
| onPOIClick | { name, coordinates } | 点击底图兴趣点 |
| onMarkerClick | 标记对象 | id / title 等字段 |
| onMarkerDragStart / onMarkerDrag / onMarkerDragEnd | 标记对象 | 本分支新增,坐标为拖拽实时位置 |
| onPolylineClick / onPolygonClick / onCircleClick | 对应覆盖物对象 | 圆另含 clickCoordinates |
| onCameraMove | CameraMoveEvent | 相机变化;挂载后以初始视野触发一次 |
坐标系约定
JS 与本包的所有边界上一律使用 WGS-84:传入的坐标(含 expo-location 的输出)可直接使用,原生层在落图前转换为 BD-09;所有事件回传坐标先转回 WGS-84。中国境外的坐标不参与转换(百度境外底图本身即 WGS-84,回传方向由百度转换器的透传行为判定,不受固定边界框影响)。转换实现与 miaoda-expo-location-55 同源,GCJ-02 → WGS-84 采用两轮定点迭代,两包对中国境内坐标产出一致。
已知限制
- StreetView 已移除,未提供替代实现(见上文);
- 信息窗为 fork 自绘位图(
title+snippet,配色经calloutStyle调整),不支持传入自定义 callout 视图; - 少于 2 坐标的 polyline 与去重后少于 3 坐标的 polygon 会被跳过并打一次 logcat 警告(百度 SDK 对此类输入抛异常,跳过是为避免原生崩溃);
- 缩放范围受百度 SDK 限制,实际可用的上下限为 4 – 22。
开发与验证
pnpm --filter miaoda-expo-maps-55 build # 包 TS 编译(expo-module-scripts 55 工具链;日常无需手动执行,pnpm install 会经 prepare 自动构建)
pnpm --filter maps-demo exec tsc --noEmit # 演示应用类型检查
cd examples/maps-demo/android && ./gradlew :expo-maps:compileDebugKotlin
cd examples/maps-demo/android && ./gradlew :app:assembleDebugbuild/ 与 plugin/build/ 为生成产物,不入库(.gitignore 已忽略);克隆后执行
pnpm install 即完成构建。
lint 脚本在当前 workspace 无法运行:根目录提升的 ESLint 10 只识别 flat config,不读取 55 工具链的 .eslintrc.js(miaoda-expo-location-55 受同样限制)。静态检查以 tsc 为准。
运行时冒烟已在无 GMS 的模拟器(AVD no-gms-test)上完成并通过,覆盖瓦片渲染、覆盖物、事件回传、坐标往返(误差 < 1e-5°)、selectMarker 与 fitToCoordinates,结果记录于 BAIDU-MAP.md 第 10 节。iOS 侧与 npm [email protected] 的一致性验证见第 11 节(语义一致,含为通过编码规范检查所做的空白格式调整记录)。
文档索引
- BAIDU-MAP.md —— 57 → 55 回退清单、渲染层架构、坐标管线、props / 事件映射表、已知限制与验证记录;
examples/maps-demo/—— 功能演示应用(地图、覆盖物、拖拽、相机控制、fitToCoordinates、与定位 fork 联动);vendor/expo-sdk-55/expo-location/NO-GMS.md—— 定位 fork 的国产引擎接入说明(与本包共用 AK 与坐标转换)。
