快速接入最后更新时间: 2026年07月01日

搭建鸿蒙开发环境

开发鸿蒙应用需要使用鸿蒙的IDE进行开发，具体内容请参考鸿蒙官网开发文档

开始前请参考下载与安装软件、配置开发环境，完成DevEco Studio的安装和开发环境配置。
开发环境配置完成后，请参考创建和运行Hello World 创建工程。
工程创建完成后，使用预览器或Phone模拟器运行该工程。

配置应用的签名信息

应用工程创建完成后，需要配置签名信息，才可以使用真机调试和发布应用。具体的签名配置请参考华为官网的配置应用签名信息指南

获取应用的AppId

配置完签名信息之后，就可以获取当前应用的appId了，这个appId主要用于申请高德的apiKey，请确定最终发布应用的appId, 防止最终高德SDK鉴权失败。

目前只能通过代码获取应用的appId，具体代码请参考如下代码

let flag = bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_SIGNATURE_INFO;
let bundleInfo = bundleManager.getBundleInfoForSelfSync(flag)
let appId = bundleInfo.signatureInfo.appId;

最终获取的appId格式类似于：com.amap.demo_BGtGgVB3ASqU7ar1nHkwX4s0nIexDbEwqNrVoatUDs17GrClWC7V2/zhoYh6tFQHAd5DASWVTEAgvZfzrEGljjs=

为了确保鉴权通过，请确保真机调试时使用的key是基于真机获取的appid申请的，而云真机调试时则应使用云真机appid对应的key

申请高德API Key

如何申请 Key

1、创建新应用

进入控制台，创建一个新应用。如果您之前已经创建过应用，可直接跳过这个步骤。

2、添加新Key

在创建的应用上点击"添加新Key"按钮，在弹出的对话框中，依次输入应用名名称，选择绑定的服务为“HarmonyOS NEXT 平台”，输入AppID ，如下图所示：

在阅读完高德地图API服务条款后，勾选此选项，点击“提交”，完成 Key 的申请，此时您可以在所创建的应用下面看到刚申请的 Key 了。

开通权限

您在高德开放平台创建的应用默认不会启用司乘同显服务。在使用高德提供的司乘同显服务前，需要联系与您对接的商务进行开通。

请保证在调用任何高德地图SDK的接口之前将apikey设置给高德司乘SDK，建议放到页面的初始化之中

请使用api的方式将申请的高德api key设置给高德司乘SDK。

设置地图key

//申请地址：https://console.amap.com/dev/key/app
const appkey = '你申请的 Key'
MapsInitializer.setApiKey(appkey);

sdk启动首页需要同意隐私协议

function privacyCompliance(context: common.Context): Promise<boolean> {
  return new Promise((resolve, reject) => {
    AlertDialog.show({
      message: "亲，感谢您对XXX一直以来的信任！我们依据最新的监管要求更新了XXX" +
        "《隐私权政策》，特向您说明如下\n" +
        "1.为向您提供交易相关基本功能，我们会收集、使用必要的信息；\n" +
        "2.基于您的明示授权，我们可能会获取您的位置（为您提供附近的商品、店铺及优惠资讯等）等信息，您有权拒绝或取消授权；\n" +
        "3.我们会采取业界先进的安全措施保护您的信息安全；\n" +
        "4.未经您同意，我们不会从第三方处获取、共享或向提供您的信息；\n" + "" +
        "5.如果您不同意以上隐私政策，我们将无法提供XXX服务;\n",
      alignment: DialogAlignment.Bottom,
      buttons: [
        {
          value: "不同意",
          action: () => {
            SCTXConfig.updatePrivacyAgree(context, false);
            reject();
          }
        },
        {
          value: "同意",
          action: () => {
            SCTXConfig.updatePrivacyAgree(context, true);
            resolve(true);
          }
        },
      ],
      cancel: () => {
        SCTXConfig.updatePrivacyAgree(context, false);
        reject();
      }
    });
    SCTXConfig.updatePrivacyShow(context, true, true);
  });
}

在业务页面跳转之前初始化导航对象

  //是否同意隐私协议
  privacyCompliancePassed: boolean = false;
    if (this.privacyCompliancePassed) {
      // change last times before turn
      const appkey = '申请的apiKey'
      let naviInstance = AMapNaviFactory.getAMapNaviInstance(getContext().getApplicationContext(), appkey)
      naviInstance.setIsUseInnerVoice(false) // 是否开启内置语音，默认true
      router.pushUrl({ url: url, params: { "pageType": pageType, "orderId": this.orderId } },
        router.RouterMode.Standard, (err) => {
          if (err) {
            console.error(`Invoke pushUrl failed, code is ${err.code}, message is ${err.message}`);
            return;
          }
          console.info('Invoke pushUrl succeeded.');
        })
      return
    }

集成SDK

使用司乘SDK之前，需要在 module.json 文件中进行相关权限设置，确保功能可以正常使用。

乘客端

第一步，配置module.json5 声明权限

 "requestPermissions": [
      {
        "name": "ohos.permission.APPROXIMATELY_LOCATION",
        "reason": "$string:Harmony_location_permission_reason",
        "usedScene": {
          "abilities": [
            "Harmony_location_demoAbility"
          ],
          "when": "always"
        }
      },
      {
        "name": "ohos.permission.LOCATION",
        "reason": "$string:Harmony_location_permission_reason",
        "usedScene": {
          "abilities": [
            "Harmony_location_demoAbility"
          ],
          "when": "always"
        }
      },
      {
        "name": "ohos.permission.LOCATION_IN_BACKGROUND",
        "reason": "$string:Harmony_location_permission_reason",
        "usedScene": {
          "abilities": [
            "Harmony_location_demoAbility"
          ],
          "when": "always"
        }
      },
      {
        "name": "ohos.permission.INTERNET",
        "reason": "$string:Harmony_location_permission_reason",
        "usedScene": {
          "abilities": [
            "Harmony_location_demoAbility"
          ],
          "when": "always"
        }
      },
      {
        "name": "ohos.permission.KEEP_BACKGROUND_RUNNING",
        "reason": "$string:Harmony_location_permission_reason",
        "usedScene": {
          "abilities": [
            "Harmony_location_demoAbility"
          ],
          "when": "always"
        }
      }
    ]

第二步添加库文件

拷贝乘客端两个har到工程libs文件夹下：

第三步配置dependencies

向 oh-package.json5文件中添加依赖

 "dependencies": {
    "@amap/amap_lbs_common": "file:./lib/amap_lbs_common-signed.har",
    "@amap/amap_lbs_map3d": "2.1.2",
    "@amap/amap_lbs_location": "1.1.0",
    "@amap/amap_cloudmap_sctxc": "file:./lib/amap_cloudmap_sctx-signed.har"
  }

司机端

第一步，配置module.json5 声明权限

"requestPermissions": [
      {
        "name": "ohos.permission.APPROXIMATELY_LOCATION",
        "reason": "$string:Harmony_location_permission_reason",
        "usedScene": {
          "abilities": [
            "Harmony_location_demoAbility"
          ],
          "when": "always"
        }
      },
      {
        "name": "ohos.permission.LOCATION",
        "reason": "$string:Harmony_location_permission_reason",
        "usedScene": {
          "abilities": [
            "Harmony_location_demoAbility"
          ],
          "when": "always"
        }
      },
      {
        "name": "ohos.permission.LOCATION_IN_BACKGROUND",
        "reason": "$string:Harmony_location_permission_reason",
        "usedScene": {
          "abilities": [
            "Harmony_location_demoAbility"
          ],
          "when": "always"
        }
      },
      {
        "name": "ohos.permission.INTERNET",
        "reason": "$string:Harmony_location_permission_reason",
        "usedScene": {
          "abilities": [
            "Harmony_location_demoAbility"
          ],
          "when": "always"
        }
      },
      {
        "name": "ohos.permission.KEEP_BACKGROUND_RUNNING",
        "reason": "$string:Harmony_location_permission_reason",
        "usedScene": {
          "abilities": [
            "Harmony_location_demoAbility"
          ],
          "when": "always"
        }
      },
      {
        "name": "ohos.permission.GET_NETWORK_INFO",
        "reason": "$string:Harmony_location_permission_reason",
        "usedScene": {
          "abilities": [
            "Harmony_location_demoAbility"
          ],
          "when": "always"
        }
      }
    ]

第二步添加库文件

拷贝司机端har到工程libs文件夹下：

第三步配置dependencies

向 oh-package.json5文件中添加依赖

"dependencies": {

    "@amap/amap_cloudmap_sctxs": "./libs/amap_cloudmap_sctx.har",
    "@amap/amap_lbs_navi": ">=2.2.7",
    "@amap/amap_lbs_location": ">=1.2.4",

    "@amap/amap_lbs_search": ">=1.0.2",
    "@amap/amap_lbs_common": ">=1.2.6"
  }

接入示例

司机端

1、创建DriverRouteManager

1) 初始化资源，更多设置可以参考RouteOverlayOptions的接口说明：

//初始化起终点图标
const options: RouteOverlayOptions = new RouteOverlayOptions(context);
//车辆图标
options.carIcon(BitmapDescriptorFactory.fromRawfilePathSync(context, 'amap_sctx_car.png'));
//起点图标
options.startPointIcon(BitmapDescriptorFactory.fromRawfilePathSync(context, 'amap_start.png'));
//终点图标
options.endPointIcon(BitmapDescriptorFactory.fromRawfilePathSync(context, 'amap_end.png'));

2）创建DriverRouteManager

this.managerDriver = new DriverRouteManager(this.context, map, overlayoptions, this.uiContext, new DemoPrivacyStatusListener(),
undefined, undefined, undefined);

2、设置订单信息

1）创建OrderProperty

//设置订单类型（普通、拼车）及订单ID
let orderProperty = new OrderProperty(SCTXConfig.SCTX_ORDER_TYPE_NORMAL, OrderId);

2）设置OrderProperty

//设置orderProperty、上车点坐标、目的地坐标
      this.managerDriver?.setOrderPropertyWithPoi(
        orderProperty,
        this.pickUpPosition,
        this.endPosition,
        this.wayPoints
      );

3、切换订单状态

1）订单状态类型，参考（com.amap.sctx.utils.SCTXConfig）

SCTX_ORDER_STATUS_UNSPECIFIED = 0;//未知状态
SCTX_ORDER_STATUS_PICKUPPASSENGER = 1;//去接乘客
SCTX_ORDER_STATUS_WAITPASSENGER = 2;//等待乘客上车
SCTX_ORDER_STATUS_PASSENGERONBOARD = 3;//乘客以上车
SCTX_ORDER_STATUS_ORDERCOMPLETE = 4;//订单结束

2）订单状态切换

this.managerDriver?.setOrderState(SCTXConfig.SCTX_ORDER_STATUS_PICKUPPASSENGER);

运行效果：

4、调起导航组件

在接乘客和送乘客阶段可以调起高德导航组件进行导航：

1)调用DriverRouteManager的startNavi方法开启导航：

    if (!this.naviParams) {
      this.naviParams = new NaviParams()
      this.naviParams.setUseInnerVoice(true)
      this.naviParams.setTrafficEnable(true)
      this.naviParams.setNeedCalculateRoute(false)
      this.naviParams.setShowExitNaviDialog(true)
      if (view) {
        this.naviParams.setCustomMiddleComponent(view)
      }
    }
    this.managerDriver?.startNavi(this.context, this.naviCallback, this.naviParams ?? new NaviParams())

 /**
   * 司乘同显 启动导航接口回调
   */
  private naviCallback: INaviInfoCallback = {
    onExitPage: (pageType: AMapPageType) => {
      AMapNaviFactory.getAMapNaviInstanceNoParams()?.setIsUseInnerVoice(false)
      console.log(`INaviInfoCallback-------onExitPage: ${pageType}`);
    },
    onInitNaviFailure: () => {
      console.log(`INaviInfoCallback-------onInitNaviFailure`);
    },
    onStartNavi: (type: NaviType) => {
      console.log(`INaviInfoCallback-------onStartNavi: ${type}`);
    },
    //算路成功回调
    onCalculateRouteSuccess: (ids: Int32Array) => {
      console.log(`INaviInfoCallback-------onCalculateRouteSuccess: ${ids}`);
    },
    //驾车路径规划失败后的回调函数。
    onCalculateRouteFailure: (errorInfo: number) => {
      console.log(`INaviInfoCallback-------onCalculateRouteFailure: ${errorInfo}`);
    },
    //重新规划的回调
    onReCalculateRoute: (type: number) => {
      console.log(`INaviInfoCallback-------onReCalculateRoute: ${type}`);
      this.queryPastAccidentOfCurrentRoute()
    },
    //切换算路偏好回调
    onStrategyChanged: (strategy: number) => {
      console.log(`INaviInfoCallback-------onStrategyChanged: ${strategy}`);
    },
    //驾车路径导航到达某个途经点的回调函数。
    onArrivedWayPoint: (wayID: number) => {
      console.log(`INaviInfoCallback-------onArrivedWayPoint: ${wayID}`);
    },
    //到达目的地后回调函数。
    onArriveDestination: (isEmulaterNavi: boolean) => {
      console.log(`INaviInfoCallback-------onArriveDestination: ${isEmulaterNavi}`);
    },
    //当GPS位置有更新时的回调函数
    onLocationChange: (location: AMapNaviLocation | null) => {
      console.log(`INaviInfoCallback-------onLocationChange: ${JSON.stringify(location)}`);
    },
    //导航播报信息回调
    onGetNavigationText: (text: string) => {
      console.log(`INaviInfoCallback-------onGetNavigationText: ${text}`);
    },
    //导航视角变化回调
    onNaviDirectionChanged: (naviMode: AMapNaviViewTrackingMode) => {
      console.log(`INaviInfoCallback-------onNaviDirectionChanged: ${naviMode}`);
    },
    //播报模式变化回调
    onBroadcastModeChanged: (mode: number) => {
      console.log(`INaviInfoCallback-------onBroadcastModeChanged: ${mode}`);
    },
    //组件地图白天黑夜模式切换回调
    onMapTypeChanged: (mapType: number) => {
      console.log(`INaviInfoCallback-------onMapTypeChanged: ${mapType}`);
    },
    //昼夜模式设置变化回调
    onDayAndNightModeChanged: (mode: number) => {
      console.log(`INaviInfoCallback-------onDayAndNightModeChanged: ${mode}`);
    },
    //比例尺智能缩放设置变化回调
    onScaleAutoChanged: (enable: boolean) => {
      console.log(`INaviInfoCallback-------onScaleAutoChanged: ${enable}`);
    },
    //停止播报回调
    onStopSpeaking: () => {
      console.log(`INaviInfoCallback-------onStopSpeaking:`);

    }
  };

5、销毁

 //释放资源
 this.managerDriver?.destroy()

乘客端

流程与司机端一一对应：

1、创建PassengerRouteManager

1) 初始化资源，更多设置可以参考RouteOverlayOptions的接口说明：

//初始化起终点图标
const options: RouteOverlayOptions = new RouteOverlayOptions(context);
//车辆图标
options.carIcon(BitmapDescriptorFactory.fromRawfilePathSync(context, 'amap_sctx_car.png'));
//起点图标
options.startPointIcon(BitmapDescriptorFactory.fromRawfilePathSync(context, 'amap_start.png'));
//终点图标
options.endPointIcon(BitmapDescriptorFactory.fromRawfilePathSync(context, 'amap_end.png'));

2）创建PassengerRouteManager

this.managerPassenger =new PassengerRouteManager(this.context, map, new DemoPrivacyStatusListener(), overlayoptions);

2、设置订单信息

1）创建OrderProperty

//设置订单类型（普通、拼车）及订单ID

let orderProperty: OrderProperty = new OrderProperty(SCTXConfig.SCTX_ORDER_TYPE_NORMAL, this.orderId);

2）设置OrderProperty

//设置orderProperty、上车点坐标、目的地坐标
this.pickUpPosition = new Poi("国际竹藤大厦", new LatLng(39.98964, 116.479907), "")
this.endPosition = new Poi("人民大学", new LatLng(39.971864, 116.318945), "")

this.managerPassenger?.setOrderPropertyWithPoi(
orderProperty,this.pickUpPosition,
this.endPosition,undefined);

3、切换订单状态

this.managerPassenger?.setOrderState(SCTXConfig.SCTX_ORDER_STATUS_PICKUPPASSENGER);

4、销毁

this.managerPassenger?.destroy();//释放资源

运行效果：

覆盖物样式自定义

司乘同显覆盖物（车、路线、起终点）样式均通过RouteOverlayOptions来控制，具体参数介绍：


 /**
     * 设置起点图标
     *
     * @param bitmapDescriptor
     * @return
     * @since 1.0.0
     */
    startPointIcon(s287: BitmapDescriptor | undefined): void;
    /**
     * 设置终点图标
     *
     * @param bitmapDescriptor
     * @return
     * @since 1.0.0
     */
    endPointIcon(r287: BitmapDescriptor | undefined): RouteOverlayOptions;
    /**
     * 设置小车图标
     */
    carIcon(q287: BitmapDescriptor | undefined): void;

    /**
     * 设置默认轨迹线填充纹理
     *
     * @param bitmapDescriptor
     * @return
     * @since 1.0.0
     */
    defaultRouteRes(o287: BitmapDescriptor | undefined): RouteOverlayOptions;
    /**
     * 设置步行轨迹线填充纹理
     *
     * @param bitmapDescriptor
     * @return
     * @since 1.0.0
     */
    walkRouteRes(n287: BitmapDescriptor | undefined): RouteOverlayOptions;
    /**
     * 设置路况轨迹线填充纹理--畅通
     *
     * @param bitmapDescriptor
     * @return
     * @since 1.0.0
     */
    smoothTrafficRes(m287: BitmapDescriptor | undefined): RouteOverlayOptions;
    /**
     * 设置路况轨迹线填充纹理--缓慢
     *
     * @param bitmapDescriptor
     * @return
     * @since 1.0.0
     */
    slowTrafficRes(l287: BitmapDescriptor | undefined): RouteOverlayOptions;
    /**
     * 设置路况轨迹线填充纹理--拥堵
     *
     * @param bitmapDescriptor
     * @return
     * @since 1.0.0
     */
    jamTrafficRes(k287: BitmapDescriptor | undefined): RouteOverlayOptions;
 /**
     * 设置路况轨迹线填充纹理--严重拥堵
     *
     * @param bitmapDescriptor
     * @return
     * @since 1.0.0
     */
    veryJamTrafficRes(j287: BitmapDescriptor | undefined): RouteOverlayOptions;
    /**
     * 设置路况轨迹线填充纹理--未知路况
     *
     * @param bitmapDescriptor
     * @return
     * @since 1.0.0
     */
    unknownTrafficRes(i287: BitmapDescriptor | undefined): RouteOverlayOptions;
    /**
     * 设置路况轨迹线填充纹理--畅通，未选中状态
     *
     * @param bitmapDescriptor
     * @return
     * @since 2.4.0
     */
    smoothTrafficUnSelectRes(h287: BitmapDescriptor | undefined): RouteOverlayOptions;
    /**
     * 设置路况轨迹线填充纹理--缓慢，未选中状态
     *
     * @param bitmapDescriptor
     * @return
     * @since 2.4.0
     */
    slowTrafficUnSelectRes(g287: BitmapDescriptor | undefined): RouteOverlayOptions;
    /**
     * 设置路况轨迹线填充纹理--拥堵，未选中状态
     *
     * @param bitmapDescriptor
     * @return
     * @since 2.4.0
     */
    jamTrafficUnSelectRes(f287: BitmapDescriptor | undefined): RouteOverlayOptions;
    /**
     * 设置路况轨迹线填充纹理--严重拥堵，未选中状态
     *
     * @param bitmapDescriptor
     * @return
     * @since 2.4.0
     */
    veryJamTrafficUnSelectRes(e287: BitmapDescriptor | undefined): RouteOverlayOptions;
    /**
     * 设置路况轨迹线填充纹理--未知路况，未选中状态
     *
     * @param bitmapDescriptor
     * @return
     * @since 2.4.0
     */
    unknownTrafficUnSelectRes(d287: BitmapDescriptor | undefined): RouteOverlayOptions;

    /**
     * 设置走过的路填充纹理
     *
     * @param bitmapDescriptor
     * @return
     * @since 2.0.0
     */
    passedTraceRes(c287: BitmapDescriptor | undefined): RouteOverlayOptions;
    /**
     * 设置普通途经点图片资源
     * @param normalWayPointDescriptor
     * @return
     * @since 2.3.0
     */
    setNormalWayPointDescriptor(w286: BitmapDescriptor | undefined): RouteOverlayOptions;
    /**
     * 设置上车途经点图片资源（拼车）
     *
     * @param startWayPointDescriptor
     * @since 2.0.0
     */
    setStartWayPointDescriptor(a287: BitmapDescriptor | undefined): RouteOverlayOptions;
    /**
     * 设置下车途经点图片资源（拼车）
     *
     * @param endWayPointDescriptor
     * @since 2.0.0
     */
    setEndWayPointDescriptor(z286: BitmapDescriptor | undefined): RouteOverlayOptions;

注意：如果有司乘同显地图界面退出重新进入的场景，建议在调用 DriverRouteManager.setMap前重新初始化一下RouteOverlayOptions里的图片资源，因为地图在退出销毁时同时会销毁这些图片；

使用注意事项

用司机端SDK时，避免外部同时使用导航SDK或者导航组件

导航SDK是单例的，司乘同显SDK内部功能也依赖于导航功能，当使用司乘同显SDK时，如果外部再调用导航组件或者导航路径规划功能会影响司机端的功能运行。如果在初始化司乘同显SDK之前已经有使用导航SDK的功能建议在初始化司乘同显SDK之前，先销毁导航SDK，再初始化司乘同显SDK。

避免重复设置订单信息

当订单信息没有变化时，只需要设置一次就可以了，重复设置会造成司乘同显内部信息重复上传、初始化，造成流量浪费和一些意外情况出现。

快速接入 最后更新时间: 2026年07月01日

搭建鸿蒙开发环境

配置应用的签名信息

获取应用的AppId

申请高德API Key

如何申请 Key

1、创建新应用

2、添加新Key

开通权限

集成SDK

乘客端

司机端

接入示例

司机端

1、创建DriverRouteManager

2、设置订单信息

3、切换订单状态

4、调起导航组件

5、销毁

乘客端

1、创建PassengerRouteManager

2、设置订单信息

3、切换订单状态

4、销毁

覆盖物样式自定义

使用注意事项

用司机端SDK时，避免外部同时使用导航SDK或者导航组件

避免重复设置订单信息

快速接入最后更新时间: 2026年07月01日