百度地图开放平台

所有文档

个性化地图编辑器

更新时间: 2026/11/12 10:21

在个性化地图编辑器中发布样式后,Android、iOS 和鸿蒙(HarmonyOS NEXT)地图 SDK 都可以通过样式 ID 在线加载这个样式,让 App 中的地图与产品风格保持一致。

准备工作
准备项说明

已发布的样式

在编辑器中完成编辑并点击「发布」。只保存草稿、没有发布的样式无法加载

样式 ID

在样式列表中点击样式 ID 即可复制,或在编辑器「⋮ > 复制样式 ID」

移动端 AK

在开放平台控制台为 App 申请 AK(Android 需要配置 SHA1 和包名,iOS 需要配置 Bundle ID),并完成 SDK 的集成与初始化。AK 必须和样式属于同一个开放平台账号

加载原理

设置样式 ID 后,SDK 会在线下载样式并缓存到本地:

  • 首次加载需要联网;之后打开地图会先显示本地缓存的样式,同时检查是否有新版本。

  • 在编辑器中重新发布后,App 下次加载样式时会自动更新,不需要发版。

  • 网络不通或加载失败时,可以配置一个本地样式文件作为兜底。

Android
第一步:设置样式 ID

创建 MapCustomStyleOptions,填入样式 ID,然后调用 MapView 的 setMapCustomStyle:

MapCustomStyleOptions options = new MapCustomStyleOptions();
// 在线样式 ID,替换为你自己的
options.customStyleId("5aff805d-d3c2-415b-91a9-97514672a2e1");
// 可选:本地兜底样式文件路径,在线样式加载失败时使用
// options.localCustomStylePath(localPath);
mMapView.setMapCustomStyle(options, new CustomMapStyleCallBack() {
@Override
public boolean onPreLoadLastCustomMapStyle(String customStylePath) {
// 先加载本地缓存的上一次样式,返回 false 表示使用 SDK 默认处理
return false;
}
@Override
public boolean onCustomMapStyleLoadSuccess(boolean hasUpdate, String customStylePath) {
// 在线样式加载成功,hasUpdate 表示是否有新版本
return false;
}
@Override
public boolean onCustomMapStyleLoadFailed(int status, String message, String customStylePath) {
// 在线样式加载失败,可在这里记录日志
return false;
}
});
第二步:开启或关闭个性化样式
// 开启个性化样式
mMapView.setMapCustomStyleEnable(true);
// 关闭后恢复为默认地图样式
mMapView.setMapCustomStyleEnable(false);
提示:建议在地图创建完成后(如 onCreate 中初始化 MapView 之后)设置样式。
iOS
第一步:设置样式 ID

创建 BMKCustomMapStyleOption,填入样式 ID,然后调用 BMKMapView 的 setCustomMapStyleWithOption:

BMKCustomMapStyleOption *option = [[BMKCustomMapStyleOption alloc] init];
// 在线样式 ID,替换为你自己的
option.customMapStyleID = @"5aff805d-d3c2-415b-91a9-97514672a2e1";
// 可选:本地兜底样式文件路径,在线样式加载失败时使用
// option.customMapStyleFilePath = localPath;
[self.mapView setCustomMapStyleWithOption:option
preLoad:^(NSString *path) {
// 先加载本地缓存的上一次样式
} success:^(NSString *path) {
// 在线样式加载成功
} failure:^(NSError *error, NSString *path) {
// 在线样式加载失败,可在这里记录日志
}];
第二步:开启或关闭个性化样式
// 开启个性化样式
[self.mapView setCustomMapStyleEnable:YES];
// 关闭后恢复为默认地图样式
[self.mapView setCustomMapStyleEnable:NO];
鸿蒙(HarmonyOS NEXT)
第一步:设置样式 ID

实现 CustomMapStyleCallBack 回调,然后调用 MapController 的 setCustomStyleById:

class CustomMapStyleCallBackImpl implements CustomMapStyleCallBack {
// 返回 false 表示使用 SDK 默认处理;返回 true 表示由开发者自行处理
onPreLoadLastCustomMapStyle(path: string | null) {
// 先加载本地缓存的上一次样式
return false;
}
onCustomMapStyleLoadSuccess(hasUpdate: boolean, path: string | null) {
// 在线样式加载成功,hasUpdate 表示是否有新版本
return false;
}
onCustomMapStyleLoadFailed(status: number, message: string, path: string | null) {
// 在线样式加载失败,可在这里记录日志
return false;
}
}
const styleCallBack: CustomMapStyleCallBack = new CustomMapStyleCallBackImpl();
// 在线样式 ID,替换为你自己的
this.mapController?.setCustomStyleById('5aff805d-d3c2-415b-91a9-97514672a2e1', styleCallBack);
第二步:开启或关闭个性化样式
// 开启个性化样式
this.mapController?.setCustomStyleEnable(true);
// 关闭后恢复为默认地图样式
this.mapController?.setCustomStyleEnable(false);
提示:在地图控制器 mapController 创建完成后再设置样式。
样式更新与版本
  • 在编辑器中重新发布后,App 下次加载样式时自动更新,不需要重新发版。

  • 编辑器中只保存、没有发布的修改不会出现在 App 中。

  • 如果样式已经在线上 App 中使用,建议先新建一个测试样式验证效果,再修改正式样式,避免影响线上用户。

新版与旧版样式 ID

SDK 根据样式 ID 的格式自动识别它来自新版还是旧版个性化编辑器,两种样式 ID 都可以直接设置:

来源样式 ID 格式示例

新版个性化地图编辑器

36 位,带连字符

5aff805d-d3c2-415b-91a9-97514672a2e1

旧版个性化编辑器

32 位,不带连字符

a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

常见问题

设置样式 ID 后地图没有变化?
请依次检查:样式是否已经发布;样式 ID 是否复制完整;AK 和样式是否属于同一个开放平台账号;Android 的 SHA1、包名或 iOS 的 Bundle ID 是否与 AK 配置一致;是否调用了开启个性化样式的方法。
重新发布后,App 里还是旧样式?
SDK 会先显示本地缓存的上一次样式,再在后台检查新版本,重新进入地图页后即可看到新样式。
断网时能显示个性化样式吗?
加载成功过一次后,SDK 会使用本地缓存的样式;从未加载成功时,会使用配置的本地兜底样式文件,没有配置则显示默认地图样式。

上一篇

在 JSAPI 中使用

下一篇

升级指南
本篇文章对您是否有帮助?