• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Loading a Module in the Main Thread Using Node-API
2
3## **Scenario**
4
5You can use **napi_load_module** to load a module in the main thread. After the module is loaded, you can use **napi_get_property** to obtain the variables of the module or use **napi_get_named_property** to obtain the functions of the module.
6
7## Function Description
8
9```cpp
10napi_status napi_load_module(napi_env env, const char* path, napi_value* result);
11```
12
13| Parameter           | Description         |
14| :------------- | :----------------------------- |
15| env            | Current JSVM environment.      |
16| path          | Pointer to the path of the file or name of the module to load.         |
17| result         | Pointer to the module loaded.         |
18
19## Constraints
20
21- Do not use this API in non-main threads.
22- Do not use this API in the **Init()** function.
23- Do not load a file in the callback function of a thread-safe function.
24
25You are advised to use [napi_load_module_with_info](use-napi-load-module-with-info.md) to load modules. This API supports more scenarios.
26
27## Scenarios Supported by napi_load_module
28| Scenario           | Scenario Description          | Remarks                        |
29| :------------- | :----------------------------- | :--------------------------- |
30| System module       |    Load **@ohos.** or **@system.**. | -                            |
31| Local project module  | Load a module defined in a file under the **ets** directory.     | The file path must start with **ets**.            |
32| Local project module  | Load a file path in a module.      | The file path must start with **moduleName**.            |
33| Local project module  | Load the name of a HAR module.          | -                            |
34| Local project module  | Load the name of an HSP module.          | -                            |
35| Remote package        | Load the name of a remote HAR module.       | -                            |
36| Remote package        | Load the ohpm package name.           | -                            |
37| Native library of a module  | Load **libNativeLibrary.so**.| -                            |
38
39- **Loading a System Module**
40
41    ```cpp
42    static napi_value loadModule(napi_env env, napi_callback_info info) {
43        // 1. Call napi_load_module to load the @ohos.hilog module.
44        napi_value result;
45        napi_status status = napi_load_module(env, "@ohos.hilog", &result);
46        if (status != napi_ok) {
47            return nullptr;
48        }
49
50        // 2. Call napi_get_named_property to obtain the info function.
51        napi_value infoFn;
52        napi_get_named_property(env, result, "info", &infoFn);
53
54        napi_value tag;
55        std::string formatStr = "test";
56        napi_create_string_utf8(env, formatStr.c_str(), formatStr.size(), &tag);
57
58        napi_value outputString;
59        std::string str = "Hello OpenHarmony";
60        napi_create_string_utf8(env, str.c_str(), str.size(), &outputString);
61
62        napi_value flag;
63        napi_create_int32(env, 0, &flag);
64
65        napi_value args[3] = {flag, tag, outputString};
66        // 3. Call napi_call_function to invoke the info function.
67        napi_call_function(env, result, infoFn, 3, args, nullptr);
68        return result;
69    }
70    ```
71
72- **Loading a Module Defined in a File Under the ets Directory**
73
74    For example, load a module from a file as shown in the following ArkTS code:
75
76    ```javascript
77    //./src/main/ets/Test.ets
78    let value = 123;
79    function test() {
80      console.log("Hello OpenHarmony");
81    }
82    export {value, test};
83    ```
84
851. Configure the **build-profile.json5** file of the project.
86
87    ```json
88    {
89      "buildOption" : {
90        "arkOptions" : {
91          "runtimeOnly" : {
92            "sources": [
93              "./src/main/ets/Test.ets"
94            ]
95          }
96        }
97      }
98    }
99    ```
100
1012. Call **napi_load_module** to load the module from the **Test.ets** file, call the **test()** function, and obtain the **value** variable.
102
103    ```cpp
104    static napi_value loadModule(napi_env env, napi_callback_info info) {
105        napi_value result;
106        // 1. Call napi_load_module to load the module from the Test.ets file.
107        napi_status status = napi_load_module(env, "ets/Test", &result);
108        if (status != napi_ok) {
109            return nullptr;
110        }
111
112        napi_value testFn;
113        // 2. Call napi_get_named_property to obtain the test function.
114        napi_get_named_property(env, result, "test", &testFn);
115        // 3. Call napi_call_function to invoke the test function.
116        napi_call_function(env, result, testFn, 0, nullptr, nullptr);
117
118        napi_value value;
119        napi_value key;
120        std::string keyStr = "value";
121        napi_create_string_utf8(env, keyStr.c_str(), keyStr.size(), &key);
122        // 4. Call napi_get_property to obtain the value variable.
123        napi_get_property(env, result, key, &value);
124        return result;
125    }
126    ```
127- **Loading a File Path in a Module**
128
129    For example, load a module from a file as shown in the following ArkTS code:
130
131    ```javascript
132    //./src/main/ets/Test.ets
133    let value = 123;
134    function test() {
135      console.log("Hello OpenHarmony");
136    }
137    export {value, test};
138    ```
139
1401. Configure the **build-profile.json5** file of the current module as follows:
141
142    ```json
143    {
144      "buildOption" : {
145        "arkOptions" : {
146          "runtimeOnly" : {
147            "sources": [
148              "./src/main/ets/Test.ets"
149            ]
150          }
151        }
152      }
153    }
154    ```
155
1562. Call **napi_load_module** to load the module from the **Test.ets** file, call the **test()** function, and obtain the **value** variable.
157
158    ```cpp
159    static napi_value loadModule(napi_env env, napi_callback_info info) {
160        napi_value result;
161        // 1. Call napi_load_module to load the module from the Test.ets file.
162        napi_status status = napi_load_module(env, "entry/src/main/ets/Test", &result);
163        if (status != napi_ok) {
164            return nullptr;
165        }
166
167        napi_value testFn;
168        // 2. Call napi_get_named_property to obtain the test function.
169        napi_get_named_property(env, result, "test", &testFn);
170        // 3. Call napi_call_function to invoke the test function.
171        napi_call_function(env, result, testFn, 0, nullptr, nullptr);
172
173        napi_value value;
174        napi_value key;
175        std::string keyStr = "value";
176        napi_create_string_utf8(env, keyStr.c_str(), keyStr.size(), &key);
177        // 4. Call napi_get_property to obtain a variable value.
178        napi_get_property(env, result, key, &value);
179        return result;
180    }
181    ```
182
183- **Loading a HAR Module**
184
185    For example, the **Index.ets** file in a HAR is as follows:
186
187    ```javascript
188    // Library Index.ets
189    let value = 123;
190    function test() {
191      console.log("Hello OpenHarmony");
192    }
193    export {value, test};
194    ```
195
1961. Configure **dependencies** in the **oh-package.json5** file of the module.
197
198    ```json
199    {
200      "dependencies": {
201        "library": "file:../library"
202      }
203    }
204    ```
205
2062. Configure **build-profile.json5** for the module that uses the library.
207
208    ```json
209    {
210      "buildOption" : {
211        "arkOptions" : {
212          "runtimeOnly" : {
213            "packages": [
214              "library"
215            ]
216          }
217        }
218      }
219    }
220    ```
221
2223. Call **napi_load_module** to load the library, call the **test** function, and obtain the **value** variable.
223
224    ```cpp
225    static napi_value loadModule(napi_env env, napi_callback_info info) {
226        napi_value result;
227        // 1. Call napi_load_module to load the library.
228        napi_status status = napi_load_module(env, "library", &result);
229        if (status != napi_ok) {
230            return nullptr;
231        }
232
233        napi_value testFn;
234        // 2. Call napi_get_named_property to obtain the test function.
235        napi_get_named_property(env, result, "test", &testFn);
236        // 3. Call napi_call_function to invoke the test function.
237        napi_call_function(env, result, testFn, 0, nullptr, nullptr);
238
239        napi_value value;
240        napi_value key;
241        std::string keyStr = "value";
242        napi_create_string_utf8(env, keyStr.c_str(), keyStr.size(), &key);
243        // 4. Call napi_get_property to obtain the value variable.
244        napi_get_property(env, result, key, &value);
245        return result;
246    }
247    ```
248
249- **Loading an HSP module**
250
251    For example, the **Index.ets** file in an HSP is as follows:
252
253    ```javascript
254    // Shared library Index.ets
255    let value = 123;
256    function test() {
257      console.log("Hello OpenHarmony");
258    }
259    export {value, test};
260    ```
261
2621. Configure **dependencies** in the **oh-package.json5** file of the module.
263
264    ```json
265    {
266      "dependencies": {
267        "sharedlibrary": "file:../sharedlibrary"
268      }
269    }
270    ```
271
2722. Configure **build-profile.json5** for the module that uses the library.
273
274    ```json
275    {
276      "buildOption" : {
277        "arkOptions" : {
278          "runtimeOnly" : {
279            "packages": [
280              "sharedlibrary"
281            ]
282          }
283        }
284      }
285    }
286    ```
287
2883. Call **napi_load_module** to load the shared library, call the **test** function, and obtain the **value** variable.
289
290    ```cpp
291    static napi_value loadModule(napi_env env, napi_callback_info info) {
292        napi_value result;
293        // 1. Call napi_load_module to load the shared library.
294        napi_status status = napi_load_module(env, "sharedlibrary", &result);
295        if (status != napi_ok) {
296            return nullptr;
297        }
298
299        napi_value testFn;
300        // 2. Call napi_get_named_property to obtain the test function.
301        napi_get_named_property(env, result, "test", &testFn);
302        // 3. Call napi_call_function to invoke the test function.
303        napi_call_function(env, result, testFn, 0, nullptr, nullptr);
304
305        napi_value value;
306        napi_value key;
307        std::string keyStr = "value";
308        napi_create_string_utf8(env, keyStr.c_str(), keyStr.size(), &key);
309        // 4. Call napi_get_property to obtain the value variable.
310        napi_get_property(env, result, key, &value);
311        return result;
312    }
313    ```
314
315- **Loading a Remote HAR Module**
316
3171. Configure **dependencies** in the **oh-package.json5** file of the module.
318
319    ```json
320    {
321      "dependencies": {
322        "@ohos/hypium": "1.0.16"
323      }
324    }
325    ```
326
3272. Configure **build-profile.json5** for the module that uses **@ohos/hypium**.
328
329    ```json
330    {
331      "buildOption" : {
332        "arkOptions" : {
333          "runtimeOnly" : {
334            "packages": [
335              "@ohos/hypium"
336            ]
337          }
338        }
339      }
340    }
341    ```
342
3433. Call **napi_load_module** to load **@ohos/hypium** and obtain the **DEFAULT** variable.
344
345    ```cpp
346    static napi_value loadModule(napi_env env, napi_callback_info info) {
347        napi_value result;
348        // 1. Call napi_load_module to load @ohos/hypium.
349        napi_status status = napi_load_module(env, "@ohos/hypium", &result);
350        if (status != napi_ok) {
351            return nullptr;
352        }
353
354        napi_value key;
355        std::string keyStr = "DEFAULT";
356        napi_create_string_utf8(env, keyStr.c_str(), keyStr.size(), &key);
357        // 2. Call napi_get_property to obtain the DEFAULT variable.
358        napi_value defaultValue;
359        napi_get_property(env, result, key, &defaultValue);
360        return result;
361    }
362    ```
363
364- **Loading an ohpm Package**
365
3661. Configure **dependencies** in the **oh-package.json5** file of the module.
367
368    ```json
369    {
370      "dependencies": {
371        "@ohos/axios": "2.2.4",
372      }
373    }
374    ```
375
3762. Configure **build-profile.json5** for the module that uses **@ohos/axios**.
377
378    ```json
379    {
380      "buildOption" : {
381        "arkOptions" : {
382          "runtimeOnly" : {
383            "packages": [
384              "@ohos/axios"
385            ]
386          }
387        }
388      }
389    }
390    ```
391
3923. Call **napi_load_module** to load **@ohos/axios** and obtain the **VERSION** variable.
393
394    ```cpp
395    static napi_value loadModule(napi_env env, napi_callback_info info) {
396        napi_value result;
397        // 1. Call napi_load_module to load @ohos/axios.
398        napi_status status = napi_load_module(env, "@ohos/axios", &result);
399        if (status != napi_ok) {
400            return nullptr;
401        }
402
403        napi_value key;
404        std::string keyStr = "VERSION";
405        napi_create_string_utf8(env, keyStr.c_str(), keyStr.size(), &key);
406        // 2. Call napi_get_property to obtain the version.
407        napi_value defaultValue;
408        napi_get_property(env, result, key, &defaultValue);
409        return result;
410    }
411    ```
412
413- **Loading a Native Library**
414
415    For example, the **index.d.ts** file of **libentry.so** is as follows:
416
417    ```javascript
418    //index.d.ts
419    export const add: (a: number, b: number) => number;
420    ```
421
4221. Configure **dependencies** in the **oh-package.json5** file of the module.
423
424    ```json
425    {
426      "dependencies": {
427        "libentry.so": "file:../src/main/cpp/types/libentry"
428      }
429    }
430    ```
431
4322. Configure **build-profile.json5** for the module that uses **libentry.so**.
433
434    ```json
435    {
436      "buildOption" : {
437        "arkOptions" : {
438          "runtimeOnly" : {
439            "packages": [
440              "libentry.so"
441            ]
442          }
443        }
444      }
445    }
446    ```
447
4483. Call **napi_load_module** to load **libentry.so** and call the **add** function.
449
450    ```cpp
451    static napi_value loadModule(napi_env env, napi_callback_info info) {
452        napi_value result;
453        // 1. Call napi_load_module to load libentry.so.
454        napi_status status = napi_load_module(env, "libentry.so", &result);
455        if (status != napi_ok) {
456            return nullptr;
457        }
458
459        napi_value addFn;
460        // 2. Call napi_get_named_property to obtain the add() function.
461        napi_get_named_property(env, result, "add", &addFn);
462
463        napi_value a;
464        napi_value b;
465        napi_create_int32(env, 2, &a);
466        napi_create_int32(env, 3, &b);
467        napi_value args[2] = {a, b};
468        // 3. Call napi_call_function to invoke the add() function.
469        napi_value returnValue;
470        napi_call_function(env, result, addFn, 2, args, &returnValue);
471        return result;
472    }
473    ```
474
475- **Loading Another HAR Module to a HAR**
476
477    For example, load **har2** to **har1**. The **Index.ets** file of **har2** is as follows:
478
479    ```javascript
480    //har2 Index.ets
481    let value = 123;
482    function test() {
483      console.log("Hello OpenHarmony");
484    }
485    export {value, test};
486    ```
487
4881. Configure **dependencies** in the **oh-package.json5** file of **har1**.
489
490    ```json
491    {
492      "dependencies": {
493        "har2": "file:../har2"
494      }
495    }
496    ```
497
4982. Configure the **build-profile.json5** file for **har1**.
499
500    ```json
501    {
502      "buildOption" : {
503        "arkOptions" : {
504          "runtimeOnly" : {
505            "packages": [
506              "har2"
507            ]
508          }
509        }
510      }
511    }
512    ```
5133. Call **napi_load_module** to load **har2** to **har1**, call the **test** function, and obtain the **value** variable.
514
515    ```cpp
516    static napi_value loadModule(napi_env env, napi_callback_info info) {
517        napi_value result;
518        // 1. Call napi_load_module to load har2.
519        napi_status status = napi_load_module(env, "har2", &result);
520        if (status != napi_ok) {
521            return nullptr;
522        }
523
524        napi_value testFn;
525        // 2. Call napi_get_named_property to obtain the test function.
526        napi_get_named_property(env, result, "test", &testFn);
527        // 3. Call napi_call_function to invoke the test function.
528        napi_call_function(env, result, testFn, 0, nullptr, nullptr);
529
530        napi_value value;
531        napi_value key;
532        std::string keyStr = "value";
533        napi_create_string_utf8(env, keyStr.c_str(), keyStr.size(), &key);
534        // 4. Call napi_get_property to obtain the value variable.
535        napi_get_property(env, result, key, &value);
536        return result;
537    }
538    ```
539