子地图实例功能（原"多实例底图"，已重命名为 SubMap）提供为单个导航会话创建多个独立地图显示实例的能力。每个实例可独立进行地图模式切换、视图调整、自定义元素配置等操作，适用于分屏导航、路线对比、多窗口展示等复杂场景。
> 接口重命名说明：为更准确地表达语义，将 "MultiMap"（多实例地图）重命名为 "SubMap"（子地图），避免与数据结构 MultiMap 混淆。SDK 访问方式从 multiMap 更新为 subMap。
核心特性：

• 基于 tag 标识符支持多个地图实例同时存在

• 每个地图实例完全独立，互不影响

• 支持 2D/3D 模式无缝切换

• 灵活的车标偏移配置（2D 和 3D 分别设置）

• 自定义 DIY 图标和动态标签控制

• 完整的生命周期管理（创建、销毁、就绪事件）

通过 SDK 服务的 subMap 属性访问：

// 获取子地图管理接口
const subMapInterface = BNSDKService.subMap;

接口定义：

export interface BNISubMapInterface {
  /**
   * 创建子地图实例的控制器
   * @param tag - 子地图唯一标识，每个地图实例需要使用不同的 tag
   * @returns 地图控制器实例，创建失败返回 null
   */
  createNaviMapController(tag: string): BNISubMapControllerInterface | null;

  /**
   * 根据 tag 获取对应的地图控制器实例
   * @param tag - 子地图唯一标识
   * @returns 地图控制器实例，不存在返回 null
   */
  getMapController(tag: string): BNISubMapControllerInterface | null;

  /**
   * 销毁对应的地图控制器实例
   * @param tag - 子地图唯一标识
   */
  destroyMapController(tag: string): void;
}

export interface BNISubMapControllerInterface {
  /**
   * 地图是否初始化完成
   */
  readonly isReady: boolean;

  /**
   * 当地图初始化完成后会回调该方法
   */
  onReady(callback: () => void): void;

  // ... 其他方法（见下文详解）
}

export interface BNISubMapCarOffsetDelegate {
  /**
   * 配置地图 2D 模式车标的偏移量
   * 坐标原点为 0,0
   * x 表示横坐标的偏移量，负数往左边移动，正数往右边移动
   * y 表示纵坐标的偏移量，负数往下边移动，正数往上边移动
   *
   * @returns 含 x,y 的偏移量
   */
  carOffsetFor2DMode: () => BNPoint;

  /**
   * 配置地图 3D 模式车标的偏移量
   * 同上，分别为 3D 模式配置
   *
   * @returns 含 x,y 的偏移量
   */
  carOffsetFor3DMode: () => BNPoint;
}

地图初始化完成回调，确保地图已准备好进行操作。
使用场景：需要等待地图准备好后才能执行配置操作

mapController.onReady(() => {
  console.log('地图已就绪，可以开始操作');
  mapController.set2DMode();
});

销毁当前地图控制器，释放所有相关资源。
重要提示：不再使用的地图实例必须调用此方法释放资源，否则可能导致内存泄漏。

切换到 2D 平面地图模式。
特点：

• 使用 2D 模式车标偏移

• 地图北向朝上（朝向 0 度）

• 适合导航过程中的标准驾驶视图

mapController.set2DMode();
// 支持后续调用 setCarOffsetDelegate 来微调车标位置

切换到 3D 三维倾斜地图模式。
特点：

• 使用 3D 模式车标偏移

• 视角向下倾斜 45 度，地图根据车辆方向旋转

• 适合提供沉浸式导航体验

mapController.set3DMode();
// 3D 模式下会自动跟随车辆朝向旋转

设置车标的偏移量委托，用于在 2D/3D 模式下分别微调车标位置。
参数说明：

• delegate - 实现 BNISubMapCarOffsetDelegate 接口的对象

• x 偏移：负数往左，正数往右

• y 偏移：负数往下，正数往上

class MyOffsetDelegate implements BNISubMapCarOffsetDelegate {
  carOffsetFor2DMode() {
    // 2D 模式下，车标向上偏移 50 像素
    return { x: 0, y: -50 };
  }

  carOffsetFor3DMode() {
    // 3D 模式下，车标向下偏移 30 像素
    return { x: 0, y: 30 };
  }
}

mapController.setCarOffsetDelegate(new MyOffsetDelegate());

设置地图显示区域的内边距（绿框区域），用于控制路线全览时的展示范围。
参数说明：

• insets - 包含 top, bottom, left, right 四个边距值（单位：像素）

// 设置路线展示区域，上下各留 100px 边距，左右各留 50px 边距
mapController.setRouteShowRect({
  top: 100,
  bottom: 100,
  left: 50,
  right: 50
});

添加自定义 UI 碰撞区域，路线全览时会避开这些区域。
使用场景：应用界面中有浮动窗口、按钮等需要避开的 UI 元素

// 为浮动按钮添加碰撞区域
mapController.addUIViewBound([
  {
    top: 20,
    bottom: 0,
    left: 300,
    right: 20
  }
]);

切换全览模式和跟随模式。
参数说明：

• isViewAll = true - 全览模式，显示完整路线

• isViewAll = false - 跟随模式，地图跟随车辆移动

// 进入全览模式
mapController.setViewAllMode(true);

// 切换回跟随模式
mapController.setViewAllMode(false);

设置是否处于浏览态，浏览态下用户可自由操作地图（缩放、平移等）。
参数说明：

• isBrowse = true - 进入浏览态

• isBrowse = false - 退出浏览态，恢复导航态

// 用户想要自由探索地图
mapController.setBrowse(true);

// 返回导航显示
mapController.setBrowse(false);

设置是否支持车道级导航（HD Lane）。
参数说明：

• supportLane = true - 开启车道级导航（默认开启）

• supportLane = false - 禁用车道级导航

// 禁用车道级导航
mapController.setSupportLane(false);

// 重新启用
mapController.setSupportLane(true);

切换地图的白天/黑夜显示模式。
参数说明：

• isNight = true - 夜间模式

• isNight = false - 白天模式

// 系统进入夜间，切换地图到夜间模式
mapController.setNightMode(true);

// 天亮了，切换回白天模式
mapController.setNightMode(false);

设置地图的导航模式。
枚举值（来自 BNAbilityInterfaceDefine.ets）：

export enum BNAbilityNaviMode {
  Invalid = 0, // 未定义
  Normal = 1,  // 普通导航
  Route = 5,   // 驾车路线页
}

参数说明：

• BNAbilityNaviMode.Normal - 导航中模式

• BNAbilityNaviMode.Route - 路线规划结果页模式

// 导航中使用导航模式
mapController.setNaviMode(BNAbilityNaviMode.Normal);

// 显示路线规划结果时使用结果页模式
mapController.setNaviMode(BNAbilityNaviMode.Route);

设置车标大小比例。
参数说明：

• scale - 缩放比例，1.0 为原始大小，范围 0.5-2.0 建议

// 车标放大 1.5 倍
mapController.setCarIconScale(1.5);

// 缩小到原来的 0.8 倍
mapController.setCarIconScale(0.8);

设置罗盘大小比例。

// 罗盘放大 1.2 倍
mapController.setCompassScale(1.2);

设置车道级模式下车的大小比例。

// 在车道级模式下放大车模型
mapController.setHDModelCarScale(1.3);

显示或隐藏实时路况信息。
参数说明：

• isShow = true - 显示路况

• isShow = false - 隐藏路况

// 用户不想看路况，隐藏
mapController.showRoadCondition(false);

// 重新显示
mapController.showRoadCondition(true);

DIY 图标类型枚举 BNDIYImageType（来自 BNAbilityInterfaceDefine.ets）：

export enum BNDIYImageType {
  CarLogo = 0,     // 车标
  StartPoint = 1,  // 起点
  EndPoint = 2,    // 终点
  DIY3DCar = 3,    // 3D车标
  WayPoint = 4,    // 途经点
}

设置指定类型的自定义 DIY 图标。
参数说明：

• icon - 图标资源，支持 PixelMap、Resource 或本地 rawfile 路径字符串

• type - 图标类型，来自 BNDIYImageType 枚举

• 返回：Promise 类型，成功返回 true，失败返回 false

// 使用资源设置自定义车标
const result = await mapController.setDIYImage(
  $r('app.media.my_car_logo'),
  BNDIYImageType.CarLogo
);

if (result) {
  console.log('车标设置成功');
} else {
  console.log('车标设置失败');
}

// 使用本地 rawfile 路径
await mapController.setDIYImage(
  'common/start_point.png',
  BNDIYImageType.StartPoint
);

清除指定类型的自定义 DIY 图标，恢复为默认图标。

// 清除自定义终点图标
mapController.clearDIYImage(BNDIYImageType.EndPoint);

// 清除所有自定义图标
mapController.clearDIYImage(BNDIYImageType.CarLogo);
mapController.clearDIYImage(BNDIYImageType.StartPoint);
mapController.clearDIYImage(BNDIYImageType.EndPoint);
mapController.clearDIYImage(BNDIYImageType.WayPoint);

显示或隐藏指定类型的自定义 DIY 图标。

// 隐藏自定义车标
mapController.setDIYImageShow(false, BNDIYImageType.CarLogo);

// 显示自定义车标
mapController.setDIYImageShow(true, BNDIYImageType.CarLogo);

批量设置途径点的自定义图标。
参数说明：

• images - 图标资源数组，长度必须与 indexes 相同

• indexes - 途径点下标数组，指定要设置图标的途径点位置（从 0 开始）

• 返回：Promise 类型

// 为第 0 和第 2 个途径点设置自定义图标
const result = await mapController.setDIYWayPointImages(
  [
    $r('app.media.waypoint1'),
    $r('app.media.waypoint2')
  ],
  [0, 2]  // 设置第 0 和第 2 个途径点
);

if (result) {
  console.log('途径点图标设置成功');
}

路线动态标签类型枚举 BNMapCarElementType（来自 BNISubMapControllerInterface.ets）：

export enum BNMapCarElementType {
  Undefined,
  Camera,                    // 电子眼
  EnterRoad,                 // 进入路名
  Jam,                       // 拥堵
  Route,                     // 路线
  TrafficSign,               // 安全提示
  Ugc,                       // UGC外露
  Guide,                     // 机动点诱导
  RouteDesc,                 // 路线可理解性
  DestNode,                  // 终点
  TrafficLight,              // 红绿灯标签
  RouteConditionForecast,    // 路况预测标签
}

隐藏指定类型的路线动态标签。
重要提示：此方法不会记住之前传入的隐藏标签类型。每次调用时需要传入所有需要隐藏的类型。

// 隐藏电子眼和拥堵标签
mapController.hideMapCarElement([
  BNMapCarElementType.Camera,
  BNMapCarElementType.Jam
]);

// 如果要再隐藏安全提示，需要重新传入所有隐藏类型
mapController.hideMapCarElement([
  BNMapCarElementType.Camera,
  BNMapCarElementType.Jam,
  BNMapCarElementType.TrafficSign
]);

隐藏所有类型的路线动态标签。

// 隐藏所有动态标签
mapController.hideAllMapCarElement();

显示所有之前隐藏的路线动态标签。

// 显示所有被隐藏的动态标签
mapController.showAllMapCarElement();

import { BNSDKService, BNISubMapControllerInterface } from '@bnavi/sdk';

@Component
export struct SubMapExample {
  @State mapController?: BNISubMapControllerInterface;
  @Consume sdkService: BNSDKService;

  aboutToAppear(): void {
    // 创建子地图实例（v1.15.0+ 使用 subMap）
    this.mapController = this.sdkService.subMap?.createNaviMapController('assistMap');
  }

  aboutToDisappear(): void {
    // 销毁时释放资源
    this.mapController?.destroyController();
  }
}

import { NaviSubMapView } from '@bnavi/sdk';

build() {
  Column() {
    // 子地图实例 UI 组件（v1.15.0+ 使用 NaviSubMapView）
    if (this.mapController) {
      NaviSubMapView({
        mapController: this.mapController,
        onReady: () => {
          // 地图初始化完成后配置
          this.mapController?.setNaviMode(BNAbilityNaviMode.Route);
          this.mapController?.setRouteShowRect(new BNEngineEdgeInsets(0, 0, 1150, 800));
          this.mapController?.showRoadCondition(false);
        }
      })
      .width('100%')
      .layoutWeight(1)
    }

    // 模式控制按钮
    Row({ space: 8 }) {
      Button('2D').onClick(() => {
        this.mapController?.set2DMode();
      }).layoutWeight(1)

      Button('3D').onClick(() => {
        this.mapController?.set3DMode();
      }).layoutWeight(1)

      Button('白天').onClick(() => {
        this.mapController?.setNightMode(false);
      }).layoutWeight(1)

      Button('黑夜').onClick(() => {
        this.mapController?.setNightMode(true);
      }).layoutWeight(1)
    }
    .width('100%')
    .padding(16)
  }
}

// 设置自定义车标和隐藏元素
async function configureMapAdvanced(mapController?: BNISubMapControllerInterface) {
  // 设置自定义车标
  await mapController?.setDIYImage('my_car_logo.png', BNDIYImageType.CarLogo);
  
  // 调整缩放
  mapController?.setCarIconScale(1.5);
  mapController?.setCompassScale(1.2);
  
  // 隐藏特定动态标签
  mapController?.hideMapCarElement([
    BNMapCarElementType.Camera,
    BNMapCarElementType.TrafficLight
  ]);
}

// 设置车标偏移（2D/3D 分别配置）
const offsetDelegate: BNISubMapCarOffsetDelegate = {
  carOffsetFor2DMode: () => ({ x: 0, y: -50 }),    // 2D 模式向上偏移
  carOffsetFor3DMode: () => ({ x: 0, y: 30 }),     // 3D 模式向下偏移
};

mapController?.setCarOffsetDelegate(offsetDelegate);