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