1# Starting a Navigation Application
2
3
4This topic describes how to open the vertical domain panel of navigation applications.
5
6
7## Parameters on the Navigation Application Panel
8
9If the **type** field in **startAbilityByType** is set to **navigation**, **wantParam** contains the following properties.
10
11| Name            | Description                                                        | Data Type| Mandatory|
12| -------------------- | ------------------------------------------------------------ | -------- | -------- |
13| destinationLatitude  | Latitude of the destination.                                                   | number   | Mandatory when **sceneType** is set to **1** or **2**.|
14| destinationLongitude | Longitude of the destination.                                                    | number   | Mandatory when **sceneType** is set to **1** or **2**.|
15| sceneType            | Scene type. The options are as follows: 1: route planning; 2: navigation; 3: place search.                               | number   | No. When this parameter is left unspecified, the default value **1** is used.  |
16| destinationName      | Name of the destination.                                                    | string   | Mandatory when **sceneType** is set to **3**.  |
17| destinationPoiIds      | List of POI IDs of the destination. It is valid in route planning or navigation scenarios.                                                      | Record<number, string>   | No  |
18| originName           | Name of the source. It is valid in route planning scenarios.                                  | string   | No  |
19| originLatitude       | Latitude of the source. It is valid in route planning scenarios.                                  | number   | No  |
20| originLongitude      | Longitude of the source. It is valid in route planning scenarios.                                  | number   | No  |
21| originPoiIds      | List of POI IDs of the source. It is valid in route planning or navigation scenarios.                                                     | Record<number, string>   | No  |
22| vehicleType          | Transportation mode. The options are as follows: 0: driving; 1: walking; 2: cycling; 3: public transportation. It is valid in route planning scenarios.| number   | No. When this parameter is left unspecified, the processing is determined by the application.  |
23
24> **NOTE**
25> 
26> * The GCJ-02 coordinate system is used for the longitude and latitude in this document.
27> 
28> * You need to obtain the destination POI IDs and source POI IDs from each map system and transfer parameters based on the following mappings.
29
30```ts
31let wantParam: Record<string, Object> = {
32      // Other parameters
33      ...,
34      'destinationPoiIds': {
35          1:'1111', // Key 1 indicates Petal Maps, and the value must be a POI in Petal Maps.
36          2:'2222' // Key 2 indicates AutoNavi Map, and the value must be a POI in AutoNavi Map.
37      } as Record<number, string>,
38      'originPoiIds': {
39          1: '3333',  // Key 1 indicates Petal Maps, and the value must be a POI in Petal Maps.
40          2: '4444'   // Key 2 indicates AutoNavi Map, and the value must be a POI in AutoNavi Map.
41      } as Record<number, string>
42    };
43```
44
45## Developing a Caller Application
46
471. Import the **ohos.app.ability.common** module.
48    ```ts
49    import { common } from '@kit.AbilityKit';
50    ```
512. Construct parameters and call the **startAbilityByType** API.
52
53    ```ts
54    let context = getContext(this) as common.UIAbilityContext;
55    let wantParam: Record<string, Object> = {
56      'sceneType': 1,
57      'destinationLatitude': 32.060844,
58      'destinationLongitude': 118.78315,
59      'destinationName': 'No.xx, xx Road, xx City',
60      'destinationPoiIds': {
61          1: "111111111111",
62          2: "222222222222"
63      } as Record<number, string>,
64      'originName': 'xx Park in xx City',
65      'originLatitude': 31.060844,
66      'originLongitude': 120.78315,
67      'originPoiIds': {
68          1: "333333333333",  
69          2: "444444444444"
70      } as Record<number, string>,
71      'vehicleType': 0
72    };
73    let abilityStartCallback: common.AbilityStartCallback = {
74      onError: (code: number, name: string, message: string) => {
75        console.log(`onError code ${code} name: ${name} message: ${message}`);
76      },
77      onResult: (result)=>{
78        console.log(`onResult result: ${JSON.stringify(result)}`);
79      }
80    }
81    
82    context.startAbilityByType("navigation", wantParam, abilityStartCallback, 
83        (err) => {
84            if (err) {
85                console.error(`startAbilityByType fail, err: ${JSON.stringify(err)}`);
86            } else {
87                console.log(`success`);
88            }
89    });
90    ```
91    Effect
92
93    ![Effect example](./figures/start-navigation-panel.png)
94
95## Developing a Target Application
96
971. Configure [uris](../quick-start/module-configuration-file.md#skills) in the **module.json5** file.
98    1. Set the **linkFeature** field to declare the features supported by the application so that the system can match the application against all the installed applications on the device. The options are as follows:
99        | Value          | Description                        |
100        | -------------- | ---------------------------- |
101        | Navigation     | The application supports navigation.		|
102        | RoutePlan      | The application supports route planning.	|
103        | PlaceSearch    | The application supports place search.    |
104    2. Set **scheme**, **host**, **port**, and **path** or **pathStartWith** to match the URIs in Want to distinguish different features.
105    ```json
106    {
107      "abilities": [
108          {
109          "skills": [
110              {
111              "uris": [
112                  {
113                  "scheme": "maps", // It is for reference only. Ensure that the declared URI can be started by external systems.
114                  "host": "navigation",
115                  "path": "",
116                  "linkFeature": "Navigation" // Declare that the application supports navigation.
117                  },
118                  {
119                  "scheme": "maps", // It is for reference only. Ensure that the declared URI can be started by external systems.
120                  "host": "routePlan",
121                  "path": "",
122                  "linkFeature": "RoutePlan" // Declare that the application supports route planning.
123                  },
124                  {
125                  "scheme": "maps", // It is for reference only. Ensure that the declared URI can be started by external systems.
126                  "host": "search",
127                  "path": "",
128                  "linkFeature": "PlaceSearch" // Declare that the application supports place search.
129                  }
130              ]
131              }
132          ]
133          }
134      ]
135    }
136    ```
137
1382. Parse parameters and perform corresponding processing.
139
140    ```ts
141    UIAbility::onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void
142    ```
143
144    The **want.uri** parameter carries the URI corresponding to **linkFeature** configured by the target application.
145
146    The **want.parameters** parameter contains the following parameters, which may be slightly different from the ones passed in by the caller.
147
148    | Name            | Description                                                        | Data Type| Mandatory|
149    | -------------------- | ------------------------------------------------------------ | -------- | -------- |
150    | destinationLatitude  | Latitude of the destination.                                                    | number   | Mandatory in the route planning or navigation scenario.|
151    | destinationLongitude | Longitude of the destination.                                                    | number   | Mandatory in the route planning or navigation scenario.|
152    | destinationName      | Name of the destination.                                                    | string   | Mandatory in the place search scenario.  |
153    | destinationPoiId      | POI ID of the destination.                                                    | string   | No. When this parameter is specified, it can be used to display a route planning or navigation page.  |
154    | originName           | Name of the source.                                  | string   | No. When this parameter is specified, it can be used to display a route planning page.  |
155    | originLatitude       | Latitude of the source.                                | number   | No. When this parameter is specified, it can be used to display a route planning page.  |
156    | originLongitude      | Longitude of the source.                                 | number   | No. When this parameter is specified, it can be used to display a route planning page.  |
157    | originPoiId      | POI ID of the source.                                                    | string   | No. When this parameter is specified, it can be used to display a route planning page.  |
158    | vehicleType          | Transportation mode. The options are as follows: 0: driving; 1: walking; 2: cycling; 3: public transportation. It is valid in route planning scenarios.| number   | No. When this parameter is left unspecified, the processing is determined by the application.  |
159
160    The application can develop different style pages based on the features defined in [linkFeature](../quick-start/module-configuration-file.md#skills), such as route planning, navigation, and place search, as well as the received URI.
161
162**Sample Code**
163
164```ts
165import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
166import { hilog } from '@kit.PerformanceAnalysisKit';
167import { window } from '@kit.ArkUI';
168
169const TAG = 'EntryAbility'
170
171export default class EntryAbility extends UIAbility {
172    windowStage: window.WindowStage | null = null;
173
174    uri?: string;
175    destinationLatitude?: number;
176    destinationLongitude?: number;
177    destinationName?: string;
178    originName?: string;
179    originLatitude?: number;
180    originLongitude?: number;
181    vehicleType?: number;
182    destinationPoiId?: string;
183    originPoiId?: string;
184
185    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
186        hilog.info(0x0000, TAG, `onCreate, want=${JSON.stringify(want)}`);
187        super.onCreate(want, launchParam);
188        this.parseWant(want);
189    }
190
191    onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
192        hilog.info(0x0000, TAG, `onNewWant, want=${JSON.stringify(want)}`);
193        super.onNewWant(want, launchParam);
194        this.parseWant(want);
195        if (!this.windowStage) {
196            hilog.error(0x0000, TAG, 'windowStage is null');
197            this.context.terminateSelf();
198            return;
199        }
200        this.loadPage(this.windowStage);
201    }
202
203    private parseWant(want: Want): void {
204        this.uri = want.uri as string | undefined;
205        this.destinationLatitude = want.parameters?.destinationLatitude as number | undefined;
206        this.destinationLongitude = want.parameters?.destinationLongitude as number | undefined;
207        this.destinationName = want.parameters?.destinationName as string | undefined;
208        this.originName = want.parameters?.originName as string | undefined;
209        this.originLatitude = want.parameters?.originLatitude as number | undefined;
210        this.originLongitude = want.parameters?.originLongitude as number | undefined;
211        this.vehicleType = want.parameters?.vehicleType as number | undefined;
212        this.destinationPoiId = want.parameters?.destinationPoiId as string | undefined;
213        this.originPoiId = want.parameters?.originPoiId as string | undefined;
214    }
215
216    private loadPage(windowStage: window.WindowStage): void {
217        hilog.info(0x0000, TAG, `loadPage, uri=${this.uri}`);
218        if (this.uri === 'maps://navigation') {
219            // Construct parameters for the navigation scenario.
220            const storage: LocalStorage = new LocalStorage({
221                "destinationLatitude": this.destinationLatitude,
222                "destinationLongitude": this.destinationLongitude,
223                "destinationPoiId": this.destinationPoiId
224            } as Record<string, Object>);
225            // Open the navigation page.
226            windowStage.loadContent('pages/NavigationPage', storage)
227        } else if (this.uri === 'maps://routePlan') {
228            // Construct parameters for the path planning scenario.
229            const storage: LocalStorage = new LocalStorage({
230                "destinationLatitude": this.destinationLatitude,
231                "destinationLongitude": this.destinationLongitude,
232                "destinationName": this.destinationName,
233                "originName": this.originName,
234                "originLatitude": this.originLatitude,
235                "originLongitude": this.originLongitude,
236                "vehicleType": this.vehicleType,
237                "destinationPoiId": this.destinationPoiId,
238                "originPoiId": this.originPoiId
239            } as Record<string, Object>);
240            // Open the route planning page.
241            windowStage.loadContent('pages/RoutePlanPage', storage)
242        }  else if (this.uri === 'maps://search') {
243            // Construct parameters for the place search scenario.
244            const storage: LocalStorage = new LocalStorage({
245                "destinationName": this.destinationName
246            } as Record<string, Object>);
247            // Open the place search page.
248            windowStage.loadContent('pages/PlaceSearchPage', storage)
249        } else {
250            // Display the home page by default.
251            windowStage.loadContent('pages/Index', (err) => {
252                if (err.code) {
253                    hilog.error(0x0000, TAG, 'Failed to load the content. Cause: %{public}s',
254                        JSON.stringify(err) ?? '');
255                    return;
256                }
257                hilog.info(0x0000, TAG, 'Succeeded in loading the content.');
258            });
259        }
260    }
261
262    onDestroy(): void {
263        hilog.info(0x0000, TAG, `onDestroy`);
264    }
265
266    onWindowStageCreate(windowStage: window.WindowStage): void {
267        hilog.info(0x0000, TAG, `onWindowStageCreate`);
268        this.windowStage = windowStage;
269        this.loadPage(this.windowStage);
270    }
271
272    onWindowStageDestroy(): void {
273        hilog.info(0x0000, TAG, '%{public}s', 'Ability onWindowStageDestroy');
274    }
275
276    onForeground(): void {
277        hilog.info(0x0000, TAG, '%{public}s', 'Ability onForeground');
278    }
279
280    onBackground(): void {
281        hilog.info(0x0000, TAG, '%{public}s', 'Ability onBackground');
282    }
283}
284```
285