目录

navigationInfoMgr (Navigation Information Management)

This module provides a set of map navigation functions, including sending navigation commands (such as starting or ending navigation), navigation updates (such as POI information), and navigation metadata (turn-by-turn information, TBT information for short) to maps, for navigation hop and dashboard/AR-HUD display.

Since: 4.1.0(11)

Modules to Import

import { navigationInfoMgr } from '@kit.CarKit';

MapStatus

Enumerated values of the map status.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.CarService.NavigationInfo

Since: 4.1.0(11)

Name Value Description
IDLE 0 The map is in idle state. This is the default value when the map app is not started.
NAVIGATION 1 The map is in navigation mode.
CRUISE 2 The map is in cruise mode.
POI 3 The map is in point of interest (POI) selection mode.
ROUTE 4 The map is in route selection mode.
UNAVAILABLE 5 The map service is not available. This value is used when the map app cannot provide services due to an internal error.

Location

Geographical location information.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.CarService.NavigationInfo

Since: 4.1.0(11)

Name Type Read-Only Optional Description
name string No No Address name, which can contain 0 to 1,024 bytes.
coordType LocationCoordType No No Geodetic coordinate system.
longitude number No No Longitude of the destination. This parameter is used together with coordType. The value ranges from –180 to 180.
latitude number No No Latitude of the destination. This parameter is used together with coordType. The value ranges from –90 to 90.
altitude number No No Altitude of the destination, in meters. The default value is 0.

LocationCoordType

Enumerated values of the geodetic coordinate system.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.CarService.NavigationInfo

Since: 4.1.0(11)

Name Value Description
GCJ02 0 China geodetic coordinate system.
WGS84 1 World geodetic coordinate system.

RoutePreference

Enumerated values of route preference.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.CarService.NavigationInfo

Since: 4.1.0(11)

Name Value Description
INTELLIGENT_RECOMMENDATION 0 Recommend routes smartly.
HIGHWAY_FIRST 1 Take highways in priority.
AVOID_HIGHWAY 2 Avoid highways.
AVOID_CONGESTION 3 Avoid traffic jams.
LESS_CHARGE 4 Minimize tolls.
MAIN_ROAD_FIRST 5 Take main roads in priority.
TIME_FIRST 6 Minimize travel time when selecting routes.

ThemeType

Enumerated values of the map theme color.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.CarService.NavigationInfo

Since: 4.1.0(11)

Name Value Description
LIGHT 0 The map uses the light theme.
DARK 1 The map uses the dark theme.

SystemNavigationListener

System navigation listener callback.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.CarService.NavigationInfo

Since: 4.1.0(11)

[h2]onQueryNavigationInfo

onQueryNavigationInfo(query: QueryType, args: Record<string, Object>): Promise<ResultData>

Returns the query result when an app receives a query request from the system.

This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.CarService.NavigationInfo

Device behavior differences: For 6.0.0(22) and earlier versions, this callback is triggered on phones and returns the query result, but does not respond on other device types. For 6.1.0(23) and later versions, this callback can be triggered on both phones and tablets and returns the query result, but does not respond on other device types.

Since: 4.1.0(11)

Parameters:

Parameter Type Mandatory Description
query QueryType Yes Query command.
args Record<string, Object> Yes Additional parameters for the query parameter.

Returns:

Type Description
Promise<ResultData> Promise used to return the navigation information query result.

Example:

Callback method. For details about the sample code, please refer to registerSystemNavigationListener.

[h2]onReceiveNavigationCmd

onReceiveNavigationCmd(command: CommandType, args: Record<string, Object>): Promise<ResultData>

Returns the command execution result when an app receives a command from the system.

This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.CarService.NavigationInfo

Device behavior differences: For 6.0.0(22) and earlier versions, this callback is triggered on phones and returns the command execution result, but does not respond on other device types. For 6.1.0(23) and later versions, this callback can be triggered on both phones and tablets and returns the command execution result, but does not respond on other device types.

Since: 4.1.0(11)

Parameters:

Parameter Type Mandatory Description
command CommandType Yes Command that the system service requires your app to execute.
args Record<string, Object> Yes

Command parameter. The value varies according to command.

When command is set to START_NAVIGATION,

the value is destLocation, indicating the navigation destination of the Location type.

When command is set to START_MAP_LAYER or STOP_MAP_LAYER,

the value is mapLayerDisplayId, indicating the display ID of the screen where the map layer is started. The parameter type is number.

When command is set to CHANGE_THEME,

the value is newTheme, indicating that the app is notified to change the theme, for example, switching between light and dark colors. The parameter type is ThemeType.

When command is set to SEARCH_POI,

the value is address, indicating that the app is notified to search for the corresponding address. The parameter type is string.

Returns:

Type Description
Promise<ResultData> Promise used to return the command sending result.

Example:

Callback method. For details about the sample code, please refer to registerSystemNavigationListener.

QueryType

Enumerated values of the navigation information query type.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.CarService.NavigationInfo

Since: 4.1.0(11)

Name Value Description
NAVIGATION_STATUS 'navigationStatus' Navigation status query. NavigationStatus is returned through a callback.
NAVIGATION_METADATA 'navigationMetadata' Navigation TBT information query. NavigationMetadata is returned through a callback.

CommandType

Enumerated values of the command type.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.CarService.NavigationInfo

Since: 4.1.0(11)

Name Value Description
START_NAVIGATION 'startNavigation' Starts navigation.
STOP_NAVIGATION 'stopNavigation' Stops navigation.
GO_HOME 'goHome' Navigates home.
GO_TO_COMPANY 'goToCompany' Navigates to the office.
START_MAP_LAYER 'startMapLayer' Starts a map layer on another screen.
STOP_MAP_LAYER 'stopMapLayer' Stops a map layer on another screen.
ZOOM_IN_MAP 'zoomInMap' Zooms in on the map.
ZOOM_OUT_MAP 'zoomOutMap' Zooms out on the map.
CHANGE_THEME 'changeTheme' Changes the theme.
START_UPDATE_NAVIGATION_STATUS 'startUpdateNavigationStatus'

Starts the navigation status update.

Since: 5.0.0(12)
STOP_UPDATE_NAVIGATION_STATUS 'stopUpdateNavigationStatus'

Stops the navigation status update.

Since: 5.0.0(12)
SEARCH_POI 'searchPOI'

Searches for POIs.

Since: 5.1.0(18)

ResultData

Navigation information query result or command sending result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.CarService.NavigationInfo

Since: 4.1.0(11)

Name Type Read-Only Optional Description
code number No No Result code. Result code 0 means the operation was successful. Any non-zero code indicates a failure, with the specific value passed from the third-party map app.
message string No No

Result message, depending on the result code.

For result code 0, the result message could be "execute success" or other similar content indicating an operation success.

For any non-zero code, the result message could be "execute fail" or other similar content indicating an operation failure.

The actual value depends on the value passed from the map app.
data { [key: string]: object; } No No Additional information. Your app can return the information to the system in the form of key-value pairs as required.

getNavigationController

getNavigationController(): NavigationController

Controller used to obtain the navigation information service.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.CarService.NavigationInfo

Device behavior differences: For 6.0.0(22) and earlier versions, this API is supported on phones. On other device types, it returns error code 801. For 6.1.0(23) and later versions, this API is supported on both phones and tablets, but does not respond on other device types.

Required permission: ohos.permission.ACCESS_SERVICE_NAVIGATION_INFO

Since: 4.1.0(11)

Returns:

Type Description
NavigationController Controller of the navigation information service.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

ID Error Message
201 Permission denied.
801 Capability not supported.

Example:

import { navigationInfoMgr } from '@kit.CarKit';

let navInfoController: navigationInfoMgr.NavigationController = navigationInfoMgr.getNavigationController();

[h2]updateNavigationStatus

updateNavigationStatus(navigationStatus: NavigationStatus): void

Sets the navigation status, including the map status, navigation type, destination, waypoints, route, map, and theme.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.CarService.NavigationInfo

Device behavior differences: For 6.0.0(22) and earlier versions, this API is supported on phones. On other device types, it returns error code 801. For 6.1.0(23) and later versions, this API is supported on both phones and tablets, but does not respond on other device types.

Required permission: ohos.permission.ACCESS_SERVICE_NAVIGATION_INFO

Since: 4.1.0(11)

Parameters:

Parameter Type Mandatory Description
navigationStatus NavigationStatus Yes Navigation status, including the map status, navigation type, destination, waypoints, route, map, and theme.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

ID Error Message
201 Permission denied.
801 Capability not supported.
1003810001 Invalid parameter value.
1003810002 The total size of all parameters exceeds the limit.

Example:

import { navigationInfoMgr } from '@kit.CarKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

// Set the destination.
let location: navigationInfoMgr.Location = {
  name: 'location',
  coordType: navigationInfoMgr.LocationCoordType.GCJ02,
  longitude: 0.000000000000001,
  latitude: 1.000000000000001,
  altitude: 2.000000000000001
};
// (Optional) Set waypoints.
let passPoint0: navigationInfoMgr.Location = {
  name: 'passPoint0',
  coordType: navigationInfoMgr.LocationCoordType.GCJ02,
  longitude: 29.53851890563965,
  latitude: 16.50643920898438,
  altitude: 3.00015949516846
};
let passPoint1: navigationInfoMgr.Location = {
  name: 'passPoint1',
  coordType: navigationInfoMgr.LocationCoordType.WGS84,
  longitude: 4.4445874651238,
  latitude: 5.55565329843751,
  altitude: 6.66641578943265
};
// Set the navigation status attributes.
let navigationStatus: navigationInfoMgr.NavigationStatus = {
  status: navigationInfoMgr.MapStatus.NAVIGATION,
  naviType: navigationInfoMgr.NaviType.DRIVING,
  destLocation: location,
  passPoint: [passPoint0, passPoint1],
  routeIndex: 101,
  customData: 'customData',
  routePreference: [
    navigationInfoMgr.RoutePreference.TIME_FIRST,
    navigationInfoMgr.RoutePreference.MAIN_ROAD_FIRST
  ],
  theme: navigationInfoMgr.ThemeType.LIGHT
};

try {
  // Obtain NavigationController.
  let navInfoController: navigationInfoMgr.NavigationController = navigationInfoMgr.getNavigationController();
  navInfoController.updateNavigationStatus(navigationStatus);
} catch (e) {
  // Obtain the error code for an API call exception and handle the exception.
  hilog.error(0x0000, 'testTag', `update navigation status error, error code: ${e?.code}`);
}

[h2]updateNavigationMetadata

updateNavigationMetadata(navigationMetadata: NavigationMetadata): void

Sets the navigation data, including the navigation turn mode, distance to the next turn, current road name, and next road name.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.CarService.NavigationInfo

Device behavior differences: For 6.0.0(22) and earlier versions, this API is supported on phones. On other device types, it returns error code 801. For 6.1.0(23) and later versions, this API is supported on both phones and tablets, but does not respond on other device types.

Required permission: ohos.permission.ACCESS_SERVICE_NAVIGATION_INFO

Since: 4.1.0(11)

Parameters:

Parameter Type Mandatory Description
navigationMetadata NavigationMetadata Yes Navigation data, including the navigation turn mode, distance to the next turn, current road name, and next road name.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

ID Error Message
201 Permission denied.
801 Capability not supported.
1003810001 Invalid parameter value.
1003810002 The total size of all parameters exceeds the limit.

Example:

import { navigationInfoMgr } from '@kit.CarKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

// Set the data attributes.
let data: navigationInfoMgr.NavigationMetadata = {
  naviTurnMode: 0x0001,
  segmentLeftDis: 100,
  currentRoadName: 'currentRoad',
  nextRoadName: 'nextRoad',
  intersectionView: 'intersectionView',
  viewWidth: 960,
  viewHeight: 450,
  trafficLane: '0001',
  cameraSpeedLimitValid: false,
  cameraSpeedLimit: 120,
  naviSpeedLimitValid: true,
  naviSpeedLimit: 80,
  currentSpeed: 75,
  naviBearing: 90.00000000000000,
  totalLeftDis: 1546,
  remainingTime: 5,
  customData: { 'sample': 'sampleData' }
};

try {
  // Obtain NavigationController.
  let navInfoController: navigationInfoMgr.NavigationController = navigationInfoMgr.getNavigationController();
  navInfoController.updateNavigationMetadata(data);
} catch (e) {
  // Obtain the error code for an API call exception and handle the exception.
  hilog.error(0x0000, 'testTag', `update navigation metadata error, error code: ${e?.code}`);
}

[h2]registerSystemNavigationListener

registerSystemNavigationListener(listener: SystemNavigationListener): void

Registers a listener for system navigation information and commands. This method needs to be called when your app is started.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.CarService.NavigationInfo

Device behavior differences: For 6.0.0(22) and earlier versions, this API is supported on phones. On other device types, it returns error code 801. For 6.1.0(23) and later versions, this API is supported on both phones and tablets, but does not respond on other device types.

Required permission: ohos.permission.ACCESS_SERVICE_NAVIGATION_INFO

Since: 4.1.0(11)

Parameters:

Parameter Type Mandatory Description
listener SystemNavigationListener Yes Listener for system navigation information and commands.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

ID Error Message
201 Permission denied.
801 Capability not supported.
1003810001 Invalid parameter value.

Example:

import { navigationInfoMgr } from '@kit.CarKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

// Implement the SystemNavigationListener API.
class Listener implements navigationInfoMgr.SystemNavigationListener {
  // Implement the onQueryNavigationInfo method.
  onQueryNavigationInfo(query: navigationInfoMgr.QueryType,
    args: Record<string, Object>): Promise<navigationInfoMgr.ResultData> {
    return new Promise(resolve => {
      let ret: navigationInfoMgr.ResultData = {
        code: 1001,
        message: 'message test1',
        data: args
      };
      resolve(ret);
    });
  }

  // Implement the onReceiveNavigationCmd method.
  onReceiveNavigationCmd(command: navigationInfoMgr.CommandType,
    args: Record<string, Object>): Promise<navigationInfoMgr.ResultData> {
    return new Promise(resolve => {
      let ret: navigationInfoMgr.ResultData = {
        code: 1002,
        message: 'message test2',
        data: args
      };
      resolve(ret);
    });
  }
}

try {
  // Obtain NavigationController.
  let navInfoController: navigationInfoMgr.NavigationController = navigationInfoMgr.getNavigationController();
  navInfoController.registerSystemNavigationListener(new Listener());
} catch (e) {
  // Obtain the error code for an API call exception and handle the exception.
  hilog.error(0x0000, 'testTag', `register system navigation listener error, error code: ${e?.code}`);
}

[h2]unregisterSystemNavigationListener

unregisterSystemNavigationListener(): void

Unregisters a listener for system navigation information and commands.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.CarService.NavigationInfo

Device behavior differences: For 6.0.0(22) and earlier versions, this API is supported on phones. On other device types, it returns error code 801. For 6.1.0(23) and later versions, this API is supported on both phones and tablets, but does not respond on other device types.

Required permission: ohos.permission.ACCESS_SERVICE_NAVIGATION_INFO

Since: 4.1.0(11)

Error codes:

For details about the error codes, please refer to Universal Error Codes.

ID Error Message
201 Permission denied.
801 Capability not supported.

Example:

import { navigationInfoMgr } from '@kit.CarKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

try {
  // Obtain NavigationController.
  let navInfoController: navigationInfoMgr.NavigationController = navigationInfoMgr.getNavigationController();
  navInfoController.unregisterSystemNavigationListener();
} catch (e) {
  // Obtain the error code for an API call exception and handle the exception.
  hilog.error(0x0000, 'testTag', `unregister system navigation listener error, error code: ${e?.code}`);
}