• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 使用JSVM-API接口进行primitive类相关开发
2<!--Kit: NDK Development-->
3<!--Subsystem: arkcompiler-->
4<!--Owner: @yuanxiaogou; @string_sz-->
5<!--Designer: @knightaoko-->
6<!--Tester: @test_lzz-->
7<!--Adviser: @fang-jinxu-->
8
9## 简介
10
11在使用JSVM-API接口时，开发人员可以实现在JSVM模块中与JavaScript对象的交互，并进行数据转换和获取特定对象的操作，它们在不同的场景中发挥着重要的作用，使开发人员能够更灵活地处理JavaScript值和对象。
12
13## 基本概念
14
15在使用JSVM操作JavaScript对象时，需要了解一些基本概念：
16
17- **JavaScript值到C/C++类型的转换：** 在JSVM模块中，可以使用JSVM函数将JavaScript值转换为C/C++的数据类型，如将JavaScript数值转换为C/C++的整数、将JavaScript字符串转换为C/C++的字符数组等。同样，也可以将C/C++的数据类型转换为JavaScript值，以便将结果返回给JavaScript代码。
18
19## 接口说明
20
21| 接口                   | 功能说明                                                |
22| ---------------------- | ------------------------------------------------------- |
23| OH_JSVM_CoerceToBool   | 将目标值转换为Boolean类型对象。   |
24| OH_JSVM_CoerceToNumber | 将目标值转换为Number类型对象。    |
25| OH_JSVM_CoerceToObject | 将目标值转换为Object类型对象。    |
26| OH_JSVM_CoerceToString | 将目标值转换为String类型对象。    |
27| OH_JSVM_GetBoolean       | 获取JavaScript单例对象。 |
28| OH_JSVM_GetValueBool    | 获取给定JavaScript Boolean的C布尔基础类型值。 |
29| OH_JSVM_GetGlobal      | 获取当前环境中的全局global对象。                                      |
30| OH_JSVM_GetNull          | 获取JavaScript null。                                        |
31| OH_JSVM_GetUndefined     | 获取JavaScript undefined。                                   |
32
33## 使用示例
34
35JSVM-API接口开发流程参考[使用JSVM-API实现JS与C/C++语言交互开发流程](use-jsvm-process.md)。本文仅展示接口对应的C++相关代码。
36
37### OH_JSVM_CoerceToBool
38
39用于将一个给定的JavaScript值强制转为JavaScript boolean值。
40
41cpp 部分代码：
42
43```cpp
44// hello.cpp
45#include "napi/native_api.h"
46#include "ark_runtime/jsvm.h"
47#include <hilog/log.h>
48// OH_JSVM_CoerceToBool的样例方法
49static JSVM_Value CoerceToBool(JSVM_Env env, JSVM_CallbackInfo info)
50{
51    size_t argc = 1;
52    JSVM_Value args[1] = {nullptr};
53    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
54    JSVM_Value boolean = nullptr;
55    JSVM_Status status = OH_JSVM_CoerceToBool(env, args[0], &boolean);
56    if (status != JSVM_OK) {
57        OH_LOG_ERROR(LOG_APP, "JSVM OH_JSVM_CoerceToBool failed");
58    } else {
59        bool result = false;
60        OH_JSVM_GetValueBool(env, boolean, &result);
61        OH_LOG_INFO(LOG_APP, "JSVM OH_JSVM_CoerceToBool success:%{public}d", result);
62    }
63    return boolean;
64}
65// CoerceToBool注册回调
66static JSVM_CallbackStruct param[] = {
67    {.data = nullptr, .callback = CoerceToBool},
68};
69static JSVM_CallbackStruct *method = param;
70// CoerceToBool方法别名，ArkTS侧调用
71static JSVM_PropertyDescriptor descriptor[] = {
72    {"coerceToBool", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
73};
74// 样例测试js
75const char *srcCallNative = R"JS(coerceToBool("123"))JS";
76```
77<!-- @[oh_jsvm_coerce_to_bool](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutPrimitive/coercetobool/src/main/cpp/hello.cpp) -->
78
79预期结果：
80```
81JSVM OH_JSVM_CoerceToBool success:1
82```
83
84### OH_JSVM_CoerceToNumber
85
86用于将给定的JavaScript value强转为JavaScript number。
87
88cpp 部分代码：
89
90```cpp
91// hello.cpp
92#include "napi/native_api.h"
93#include "ark_runtime/jsvm.h"
94#include <hilog/log.h>
95// OH_JSVM_CoerceToNumber的样例方法
96static JSVM_Value CoerceToNumber(JSVM_Env env, JSVM_CallbackInfo info)
97{
98    size_t argc = 1;
99    JSVM_Value args[1] = {nullptr};
100    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
101    JSVM_Value number = nullptr;
102    JSVM_Status status = OH_JSVM_CoerceToNumber(env, args[0], &number);
103    if (status != JSVM_OK) {
104        OH_LOG_ERROR(LOG_APP, "JSVM OH_JSVM_CoerceToNumber failed");
105    } else {
106        int32_t result = 0;
107        OH_JSVM_GetValueInt32(env, number, &result);
108        OH_LOG_INFO(LOG_APP, "JSVM OH_JSVM_CoerceToNumber success:%{public}d", result);
109    }
110    return number;
111}
112// CoerceToNumber注册回调
113static JSVM_CallbackStruct param[] = {
114    {.data = nullptr, .callback = CoerceToNumber},
115};
116static JSVM_CallbackStruct *method = param;
117// CoerceToNumber方法别名，ArkTS侧调用
118static JSVM_PropertyDescriptor descriptor[] = {
119    {"coerceToNumber", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
120};
121// 样例测试js
122const char *srcCallNative = R"JS(coerceToNumber(true))JS";
123```
124<!-- @[oh_jsvm_coerce_to_number](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutPrimitive/coercetonumber/src/main/cpp/hello.cpp) -->
125
126预期结果：
127```
128JSVM OH_JSVM_CoerceToNumber success:1
129```
130
131### OH_JSVM_CoerceToObject
132
133用于将给定的JavaScript value强转为JavaScript Object类型。
134
135cpp 部分代码：
136
137```cpp
138// hello.cpp
139#include "napi/native_api.h"
140#include "ark_runtime/jsvm.h"
141#include <hilog/log.h>
142// OH_JSVM_CoerceToObject的样例方法
143static JSVM_Value CoerceToObject(JSVM_Env env, JSVM_CallbackInfo info)
144{
145    size_t argc = 1;
146    JSVM_Value args[1] = {nullptr};
147    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
148    JSVM_Value obj = nullptr;
149    JSVM_Status status = OH_JSVM_CoerceToObject(env, args[0], &obj);
150    if (status != JSVM_OK) {
151        OH_JSVM_ThrowError(env, nullptr, "JSVM OH_JSVM_CoerceToObject failed");
152        return nullptr;
153    } else {
154        OH_LOG_INFO(LOG_APP, "JSVM OH_JSVM_CoerceToObject success");
155    }
156    return obj;
157}
158// CoerceToObject注册回调
159static JSVM_CallbackStruct param[] = {
160    {.data = nullptr, .callback = CoerceToObject},
161};
162static JSVM_CallbackStruct *method = param;
163// CoerceToObject方法别名，ArkTS侧调用
164static JSVM_PropertyDescriptor descriptor[] = {
165    {"coerceToObject", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
166};
167// 样例测试js
168const char *srcCallNative = R"JS(coerceToObject(123))JS";
169```
170<!-- @[oh_jsvm_coerce_to_object](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutPrimitive/coercetoobject/src/main/cpp/hello.cpp) -->
171
172预期结果：
173```
174JSVM OH_JSVM_CoerceToObject success
175```
176
177### OH_JSVM_CoerceToString
178
179用于将给定的JavaScript value强转为JavaScript string类型。
180
181cpp 部分代码：
182
183```cpp
184// hello.cpp
185#include "napi/native_api.h"
186#include "ark_runtime/jsvm.h"
187#include <hilog/log.h>
188// OH_JSVM_CoerceToString的样例方法
189static JSVM_Value CoerceToString(JSVM_Env env, JSVM_CallbackInfo info)
190{
191    size_t argc = 1;
192    JSVM_Value args[1] = {nullptr};
193    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
194    JSVM_Value str = nullptr;
195    JSVM_Status status = OH_JSVM_CoerceToString(env, args[0], &str);
196    if (status != JSVM_OK) {
197        OH_JSVM_ThrowError(env, nullptr, "JSVM OH_JSVM_CoerceToString fail");
198        return nullptr;
199    } else {
200        OH_LOG_INFO(LOG_APP, "JSVM OH_JSVM_CoerceToString success");
201    }
202    return str;
203}
204// CoerceToString注册回调
205static JSVM_CallbackStruct param[] = {
206    {.data = nullptr, .callback = CoerceToString},
207};
208static JSVM_CallbackStruct *method = param;
209// CoerceToString方法别名，ArkTS侧调用
210static JSVM_PropertyDescriptor descriptor[] = {
211    {"coerceToString", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
212};
213// 样例测试js
214const char *srcCallNative = R"JS(coerceToString(22222))JS";
215```
216<!-- @[oh_jsvm_coerce_to_string](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutPrimitive/coercetostring/src/main/cpp/hello.cpp) -->
217
218预期结果：
219```
220JSVM OH_JSVM_CoerceToString success
221```
222
223### OH_JSVM_GetBoolean
224
225获取给定布尔值的JavaScript单例对象。
226
227cpp 部分代码：
228
229```cpp
230// hello.cpp
231#include "napi/native_api.h"
232#include "ark_runtime/jsvm.h"
233#include <hilog/log.h>
234// OH_JSVM_GetBoolean的样例方法
235static JSVM_Value GetBoolean(JSVM_Env env, JSVM_CallbackInfo info)
236{
237    // 传入两个参数并解析
238    size_t argc = 2;
239    JSVM_Value argv[2] = {nullptr};
240    OH_JSVM_GetCbInfo(env, info, &argc, argv, nullptr, nullptr);
241    int32_t paramData = 0;
242    OH_JSVM_GetValueInt32(env, argv[0], &paramData);
243    int32_t paramValue = 0;
244    OH_JSVM_GetValueInt32(env, argv[1], &paramValue);
245    JSVM_Value returnValue = nullptr;
246    bool type = false;
247    if (paramData == paramValue) {
248        OH_LOG_INFO(LOG_APP, "JSVM resultType equal");
249        type = true;
250    }
251    JSVM_Status status = OH_JSVM_GetBoolean(env, type, &returnValue);
252    if (status != JSVM_OK) {
253        OH_JSVM_ThrowError(env, nullptr, "JSVM OH_JSVM_GetBoolean fail");
254    } else {
255        bool result = false;
256        OH_JSVM_GetValueBool(env, returnValue, &result);
257        OH_LOG_INFO(LOG_APP, "JSVM OH_JSVM_GetBoolean success:%{public}d", result);
258    }
259    // 返回结果
260    return returnValue;
261}
262// GetBoolean注册回调
263static JSVM_CallbackStruct param[] = {
264    {.data = nullptr, .callback = GetBoolean},
265};
266static JSVM_CallbackStruct *method = param;
267// GetBoolean方法别名，供JS调用
268static JSVM_PropertyDescriptor descriptor[] = {
269    {"getBoolean", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
270};
271// 样例测试js
272const char *srcCallNative = R"JS(getBoolean(1, 2);
273                                 getBoolean(1, 1))JS";
274```
275<!-- @[oh_jsvm_get_boolean](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutPrimitive/getboolean/src/main/cpp/hello.cpp) -->
276
277预期结果：
278```
279JSVM OH_JSVM_GetBoolean success:0
280JSVM resultType equal
281JSVM OH_JSVM_GetBoolean success:1
282```
283
284### OH_JSVM_GetValueBool
285
286使用这个函数将JavaScript中的布尔值转为等价的C布尔值。
287
288cpp 部分代码：
289
290```cpp
291// hello.cpp
292#include "napi/native_api.h"
293#include "ark_runtime/jsvm.h"
294#include <hilog/log.h>
295// OH_JSVM_GetValueBool的样例方法
296static JSVM_Value GetValueBool(JSVM_Env env, JSVM_CallbackInfo info)
297{
298    size_t argc = 1;
299    JSVM_Value args[1] = {nullptr};
300    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
301    bool result = false;
302    JSVM_Status status = OH_JSVM_GetValueBool(env, args[0], &result);
303    if (status != JSVM_OK) {
304        // 如果OH_JSVM_GetValueBool成功会返回JSVM_OK，如果传入一个非布尔值则会返回JSVM_BOOLEAN_EXPECTED
305        OH_LOG_ERROR(LOG_APP, "JSVM OH_JSVM_GetValueBool fail:%{public}d", status);
306        return nullptr;
307    } else {
308        OH_LOG_INFO(LOG_APP, "JSVM OH_JSVM_GetValueBool success:%{public}d", result);
309    }
310    JSVM_Value boolJv = nullptr;
311    OH_JSVM_GetBoolean(env, result, &boolJv);
312    return boolJv;
313}
314// GetValueBool注册回调
315static JSVM_CallbackStruct param[] = {
316    {.data = nullptr, .callback = GetValueBool},
317};
318static JSVM_CallbackStruct *method = param;
319// GetValueBool方法别名，供JS调用
320static JSVM_PropertyDescriptor descriptor[] = {
321    {"getValueBool", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
322};
323// 样例测试js
324const char *srcCallNative = R"JS(getValueBool("abc");
325                                getValueBool(true);
326                                getValueBool(false);)JS";
327```
328<!-- @[oh_jsvm_get_value_bool](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutPrimitive/getvaluebool/src/main/cpp/hello.cpp) -->
329
330预期结果：
331```
332JSVM OH_JSVM_GetValueBool fail:7
333JSVM OH_JSVM_GetValueBool success:1
334JSVM OH_JSVM_GetValueBool success:0
335```
336
337### OH_JSVM_GetGlobal
338
339用于获取全局JavaScript对象。该函数的主要作用是获取表示JavaScript全局对象的JSVM_Value，使JSVM模块能够与JavaScript运行时的全局对象进行交互。
340
341cpp 部分代码：
342
343```cpp
344// hello.cpp
345#include "napi/native_api.h"
346#include "ark_runtime/jsvm.h"
347#include <hilog/log.h>
348// OH_JSVM_GetGlobal的样例方法
349static JSVM_Value GetGlobal(JSVM_Env env, JSVM_CallbackInfo info)
350{
351    // 获取全局对象
352    JSVM_Value value = nullptr;
353    JSVM_Value global = nullptr;
354    OH_JSVM_CreateInt32(env, 1, &value);
355    JSVM_Status status = OH_JSVM_GetGlobal(env, &global);
356    OH_JSVM_SetNamedProperty(env, global, "Row", value);
357    if (status != JSVM_OK) {
358        OH_LOG_ERROR(LOG_APP, "JSVM OH_JSVM_GetGlobal fail");
359    } else {
360        OH_LOG_INFO(LOG_APP, "JSVM OH_JSVM_GetGlobal success");
361    }
362    return global;
363}
364// GetGlobal注册回调
365static JSVM_CallbackStruct param[] = {
366    {.data = nullptr, .callback = GetGlobal},
367};
368static JSVM_CallbackStruct *method = param;
369// GetGlobal方法别名，供JS调用
370static JSVM_PropertyDescriptor descriptor[] = {
371    {"getGlobal", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
372};
373// 样例测试js
374const char *srcCallNative = R"JS(getGlobal())JS";
375```
376<!-- @[oh_jsvm_get_global](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutPrimitive/getglobal/src/main/cpp/hello.cpp) -->
377
378预期结果：
379```
380JSVM OH_JSVM_GetGlobal success
381```
382
383### OH_JSVM_GetNull
384
385用于获取 JavaScript null 对象。
386
387cpp 部分代码：
388
389```cpp
390// hello.cpp
391#include "napi/native_api.h"
392#include "ark_runtime/jsvm.h"
393#include <hilog/log.h>
394// OH_JSVM_GetNull的样例方法
395static JSVM_Value GetNull(JSVM_Env env, JSVM_CallbackInfo info) {
396    JSVM_Value nullValue = nullptr;
397    JSVM_Status status = OH_JSVM_GetNull(env, &nullValue);
398    if (status != JSVM_OK) {
399        OH_LOG_ERROR(LOG_APP, "JSVM OH_JSVM_GetNull fail");
400    } else {
401        OH_LOG_INFO(LOG_APP, "JSVM OH_JSVM_GetNull success");
402    }
403    return nullValue;
404}
405// GetNull注册回调
406static JSVM_CallbackStruct param[] = {
407    {.data = nullptr, .callback = GetNull},
408};
409static JSVM_CallbackStruct *method = param;
410// GetNull方法别名，供JS调用
411static JSVM_PropertyDescriptor descriptor[] = {
412    {"getNull", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
413};
414// 样例测试js
415const char *srcCallNative = R"JS(getNull())JS";
416```
417<!-- @[oh_jsvm_get_null](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutPrimitive/getnull/src/main/cpp/hello.cpp) -->
418
419预期结果:
420```
421JSVM OH_JSVM_GetNull success
422```
423
424### OH_JSVM_GetUndefined
425
426用于获取 JavaScript undefined 对象。
427
428cpp 部分代码：
429
430```cpp
431// hello.cpp
432#include "napi/native_api.h"
433#include "ark_runtime/jsvm.h"
434#include <hilog/log.h>
435// OH_JSVM_GetUndefined的样例方法
436static JSVM_Value GetUndefined(JSVM_Env env, JSVM_CallbackInfo info)
437{
438    // 获取并解析传进的参数
439    size_t argc = 1;
440    JSVM_Value args[1] = {nullptr};
441    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
442    // 创建一个undefined值
443    JSVM_Value value = nullptr;
444    JSVM_Status status = OH_JSVM_GetUndefined(env, &value);
445    if (status != JSVM_OK) {
446        OH_LOG_ERROR(LOG_APP, "JSVM OH_JSVM_GetUndefined failed");
447    } else {
448        OH_LOG_INFO(LOG_APP, "JSVM OH_JSVM_GetUndefined success");
449    }
450    return value;
451}
452// GetUndefined注册回调
453static JSVM_CallbackStruct param[] = {
454    {.data = nullptr, .callback = GetUndefined},
455};
456static JSVM_CallbackStruct *method = param;
457// GetUndefined方法别名，供JS调用
458static JSVM_PropertyDescriptor descriptor[] = {
459    {"getUndefined", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
460};
461// 样例测试js
462const char *srcCallNative = R"JS(getUndefined())JS";
463```
464<!-- @[oh_jsvm_get_undefined](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutPrimitive/getundefined/src/main/cpp/hello.cpp) -->
465
466预期结果:
467```
468JSVM OH_JSVM_GetUndefined success
469```
470