• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 使用JSVM-API接口创建基本数据类型
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在JavaScript中，整数类型是一种基本数据类型，用于表示没有小数部分的数值。Double类型用于表示有小数的数值。JavaScript的数值存储方式会导致在某些情况下无法准确表示非常大或非常小的数值，在这种情况下，需要使用BigInt对应的JSVM-API接口来处理更大范围的整数。
12
13## 基本概念
14
15当使用JSVM-API接口进行数值类型的创建和获取时，需要了解以下基本概念：
16
17- **数值类型** 在使用JSVM-API接口时，可能需要从JSVM模块数值类型转换为JavaScript数值类型，或者从JavaScript数值类型转换为JSVM模块数值类型。在进行数据类型转换时，需要注意数据范围是否匹配，以及有无符号整数和双精度数值等区别。
18- **错误处理** 在使用这些接口时，需要对可能发生的错误进行适当处理。例如，在创建整数值时可能发生内存分配错误或其他运行时错误，需要使用JSVM-API提供的错误处理机制来捕获并处理这些错误。
19- **JavaScript交互** 在开发过程中，需要考虑如何将创建的数值类型值与JavaScript环境进行交互，包括传递参数、返回值等。
20
21## 接口说明
22
23| 接口                  | 功能说明                                        |
24| --------------------- | -----------------------------------------------|
25| OH_JSVM_GetValueUint32 | 获取给定JavaScript number的Uint32基础类型值。   |
26| OH_JSVM_GetValueInt32  | 获取给定JavaScript number的Int32基础类型值。    |
27| OH_JSVM_GetValueInt64  | 获取给定JavaScript number的Int64基础类型值。    |
28| OH_JSVM_GetValueDouble | 获取给定JavaScript number的Double基础类型值。   |
29| OH_JSVM_CreateInt32     | 根据Int32_t类型对象创建JavaScript number对象。 |
30| OH_JSVM_CreateUint32    | 根据Uint32_t类型对象创建JavaScript number对象。|
31| OH_JSVM_CreateInt64     | 根据Int64_t类型对象创建JavaScript number对象。 |
32| OH_JSVM_CreateDouble    | 根据Double类型对象创建JavaScript number对象。  |
33
34## 使用示例
35
36JSVM-API接口开发流程参考[使用JSVM-API实现JS与C/C++语言交互开发流程](use-jsvm-process.md)，本文仅对接口对应C++相关代码进行展示。
37
38### OH_JSVM_GetValueUint32
39
40将JavaScript value转为JSVM模块中的uint32类型数据。
41
42cpp部分代码：
43
44```cpp
45// hello.cpp
46#include "napi/native_api.h"
47#include "ark_runtime/jsvm.h"
48#include <hilog/log.h>
49
50// OH_JSVM_GetValueUint32的样例方法
51static JSVM_Value GetValueUint32(JSVM_Env env, JSVM_CallbackInfo info)
52{
53    // 获取传入的数字类型参数
54    size_t argc = 1;
55    JSVM_Value argv[1] = {nullptr};
56    // 解析传入的参数
57    OH_JSVM_GetCbInfo(env, info, &argc, argv, nullptr, nullptr);
58    uint32_t number = 0;
59    // 获取传入参数的值中的无符号32位整数
60    JSVM_Status status = OH_JSVM_GetValueUint32(env, argv[0], &number);
61    if (status != JSVM_OK) {
62        OH_LOG_ERROR(LOG_APP, "JSVM GetValueUint32 fail");
63    } else {
64        OH_LOG_INFO(LOG_APP, "JSVM GetValueUint32 success: %{public}u", number);
65    }
66    return argv[0];
67}
68
69// GetValueUint32注册回调
70static JSVM_CallbackStruct param[] = {
71    {.data = nullptr, .callback = GetValueUint32},
72};
73static JSVM_CallbackStruct *method = param;
74
75// GetValueUint32方法别名，供JS调用
76static JSVM_PropertyDescriptor descriptor[] = {
77    {"getValueUint32", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
78};
79
80// 样例测试js
81const char* srcCallNative = R"JS(getValueUint32(123))JS";
82```
83<!-- @[oh_jsvm_get_value_uint32](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmBasicDataTypes/getvalueuint32/src/main/cpp/hello.cpp) -->
84
85预期的输出结果：
86
87```
88JSVM GetValueUint32 success: 123
89```
90
91### OH_JSVM_GetValueInt32
92
93将JavaScript value转为JSVM模块中的Int32类型数据。
94
95cpp部分代码：
96
97```cpp
98// hello.cpp
99#include "napi/native_api.h"
100#include "ark_runtime/jsvm.h"
101#include <hilog/log.h>
102
103// OH_JSVM_GetValueInt32的样例方法
104static JSVM_Value GetValueInt32(JSVM_Env env, JSVM_CallbackInfo info)
105{
106    size_t argc = 1;
107    JSVM_Value args[1] = {nullptr};
108    int32_t result32 = 0;
109    // 解析传递的参数
110    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
111    // 将前端传过来的参数转为JSVM模块的int32类型
112    JSVM_Status status = OH_JSVM_GetValueInt32(env, args[0], &result32);
113    if (status != JSVM_OK) {
114        return nullptr;
115    }
116    if (status != JSVM_OK) {
117        OH_LOG_ERROR(LOG_APP, "JSVM GetValueInt32 fail");
118    } else {
119        OH_LOG_INFO(LOG_APP, "JSVM GetValueInt32 success: %{public}d", result32);
120    }
121    return args[0];
122}
123
124// GetValueInt32注册回调
125static JSVM_CallbackStruct param[] = {
126    {.data = nullptr, .callback = GetValueInt32},
127};
128static JSVM_CallbackStruct *method = param;
129// GetValueInt32方法别名，供JS调用
130static JSVM_PropertyDescriptor descriptor[] = {
131    {"getValueInt32", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
132};
133
134// 样例测试js
135const char* srcCallNative = R"JS(getValueInt32(-123))JS";
136```
137<!-- @[oh_jsvm_get_value_int32](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmBasicDataTypes/getvalueint32/src/main/cpp/hello.cpp) -->
138
139预期的输出结果：
140
141```
142JSVM GetValueInt32 success: -123
143```
144
145### OH_JSVM_GetValueInt64
146
147将JavaScript value转为JSVM模块中的Int64类型数据。
148
149cpp部分代码：
150
151```cpp
152// hello.cpp
153#include "napi/native_api.h"
154#include "ark_runtime/jsvm.h"
155#include <hilog/log.h>
156
157// OH_JSVM_GetValueInt64的样例方法
158static JSVM_Value GetValueInt64(JSVM_Env env, JSVM_CallbackInfo info)
159{
160    size_t argc = 1;
161    JSVM_Value args[1] = {nullptr};
162    int64_t result64 = 0;
163    // 解析传递的值
164    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
165    // 将前端传过来的参数分别转为JSVM模块的int64类型
166    JSVM_Status status = OH_JSVM_GetValueInt64(env, args[0], &result64);
167    if (status != JSVM_OK) {
168        OH_LOG_ERROR(LOG_APP, "JSVM GetValueInt64 fail");
169    } else {
170        OH_LOG_INFO(LOG_APP, "JSVM GetValueInt64 success: %{public}ld", result64);
171    }
172    return args[0];
173}
174
175// GetValueInt64注册回调
176static JSVM_CallbackStruct param[] = {
177    {.data = nullptr, .callback = GetValueInt64},
178};
179static JSVM_CallbackStruct *method = param;
180// GetValueInt64方法别名，供JS调用
181static JSVM_PropertyDescriptor descriptor[] = {
182    {"getValueInt64", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
183};
184
185// 样例测试js
186const char* srcCallNative = R"JS(getValueInt64(-123))JS";
187```
188<!-- @[oh_jsvm_get_value_int64](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmBasicDataTypes/getvalueint64/src/main/cpp/hello.cpp) -->
189
190预期的输出结果：
191
192```
193JSVM GetValueInt64 success: -123
194```
195
196### OH_JSVM_GetValueDouble
197
198将JavaScript value转为JSVM模块中的double类型数据。
199
200cpp部分代码：
201
202```cpp
203// hello.cpp
204#include "napi/native_api.h"
205#include "ark_runtime/jsvm.h"
206#include <hilog/log.h>
207
208// OH_JSVM_GetValueDouble的样例方法
209static JSVM_Value GetDouble(JSVM_Env env, JSVM_CallbackInfo info)
210{
211    size_t argc = 1;
212    JSVM_Value args[1] = {nullptr};
213    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
214    double value = 0;
215    JSVM_Status status = OH_JSVM_GetValueDouble(env, args[0], &value);
216    if (status != JSVM_OK) {
217        OH_LOG_ERROR(LOG_APP, "JSVM GetDouble fail");
218    } else {
219        OH_LOG_INFO(LOG_APP, "JSVM GetDouble success: %{public}f", value);
220    }
221    return args[0];
222}
223
224// GetDouble注册回调
225static JSVM_CallbackStruct param[] = {
226    {.data = nullptr, .callback = GetDouble},
227};
228static JSVM_CallbackStruct *method = param;
229// GetDouble方法别名，供JS调用
230static JSVM_PropertyDescriptor descriptor[] = {
231    {"getDouble", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
232};
233
234// 样例测试js
235const char* srcCallNative = R"JS(getDouble(-110.0456))JS";
236```
237<!-- @[oh_jsvm_get_value_double](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmBasicDataTypes/getvaluedouble/src/main/cpp/hello.cpp) -->
238
239预期的输出结果：
240
241```
242JSVM GetDouble success: -110.045600
243```
244
245### OH_JSVM_CreateInt32
246
247根据int32_t数据创建JavaScript number对象。
248
249cpp部分代码：
250
251```cpp
252// hello.cpp
253#include "napi/native_api.h"
254#include "ark_runtime/jsvm.h"
255#include <hilog/log.h>
256
257// OH_JSVM_CreateInt32的样例方法
258static JSVM_Value CreateInt32(JSVM_Env env, JSVM_CallbackInfo info)
259{
260    int32_t value = -20;
261    // 创建JavaScript中的int32数字
262    JSVM_Value result = nullptr;
263    JSVM_Status status = OH_JSVM_CreateInt32(env, value, &result);
264    if (status != JSVM_OK) {
265        OH_LOG_ERROR(LOG_APP, "JSVM CreateInt32 fail");
266    } else {
267        int32_t number = 0;
268        OH_JSVM_GetValueInt32(env, result, &number);
269        OH_LOG_INFO(LOG_APP, "JSVM CreateInt32 success: %{public}d", number);
270    }
271    return result;
272}
273
274// CreateInt32注册回调
275static JSVM_CallbackStruct param[] = {
276    {.data = nullptr, .callback = CreateInt32},
277};
278static JSVM_CallbackStruct *method = param;
279// CreateInt32方法别名，供JS调用
280static JSVM_PropertyDescriptor descriptor[] = {
281    {"createInt32", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
282};
283
284// 样例测试js
285const char* srcCallNative = R"JS(createInt32())JS";
286```
287<!-- @[oh_jsvm_create_int32](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmBasicDataTypes/createint32/src/main/cpp/hello.cpp) -->
288
289预期的输出结果：
290
291```
292JSVM CreateInt32 success: -20
293```
294
295### OH_JSVM_CreateUint32
296
297根据uint32_t数据创建JavaScript number对象。
298
299cpp部分代码：
300
301```cpp
302// hello.cpp
303#include "napi/native_api.h"
304#include "ark_runtime/jsvm.h"
305#include <hilog/log.h>
306
307// OH_JSVM_CreateUint32的样例方法
308static JSVM_Value CreateUInt32(JSVM_Env env, JSVM_CallbackInfo info)
309{
310    // 如果使用
311    // uint32_t类型来定义-26，会发生溢出，溢出时会对结果进行模运算，将负数的二进制补码转换为相应的正数。-26输出4294967270
312    // uint32_t是无符号的32位整数类型，只能表示非负整数。它的范围是从0到2 ^32 - 1，即0到4294967295
313    // 要表示的整数值
314    uint32_t value = 26;
315    // 创建JavaScript中的uint32数字
316    JSVM_Value result = nullptr;
317    JSVM_Status status = OH_JSVM_CreateUint32(env, value, &result);
318    if (status != JSVM_OK) {
319        OH_LOG_ERROR(LOG_APP, "JSVM CreateUInt32 fail");
320    } else {
321        uint32_t number = 0;
322        OH_JSVM_GetValueUint32(env, result, &number);
323        OH_LOG_INFO(LOG_APP, "JSVM CreateUInt32 success: %{public}u", number);
324    }
325    return result;
326}
327
328// CreateUInt32注册回调
329static JSVM_CallbackStruct param[] = {
330    {.data = nullptr, .callback = CreateUInt32},
331};
332static JSVM_CallbackStruct *method = param;
333// CreateUInt32方法别名，供JS调用
334static JSVM_PropertyDescriptor descriptor[] = {
335    {"createUInt32", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
336};
337
338// 样例测试js
339const char* srcCallNative = R"JS(createUInt32())JS";
340```
341<!-- @[oh_jsvm_create_uint32](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmBasicDataTypes/createuint32/src/main/cpp/hello.cpp) -->
342
343预期的输出结果：
344
345```
346JSVM CreateUInt32 success: 26
347```
348
349### OH_JSVM_CreateInt64
350
351根据int64_t数据创建JavaScript number对象。如果需要表示JS超大数，建议使用BigInt接口。
352
353cpp部分代码：
354
355```cpp
356// hello.cpp
357#include "napi/native_api.h"
358#include "ark_runtime/jsvm.h"
359#include <hilog/log.h>
360
361// OH_JSVM_CreateInt64的样例方法
362static JSVM_Value CreateInt64(JSVM_Env env, JSVM_CallbackInfo info)
363{
364    int64_t value = 2147483648;
365    // 创建JavaScript中的int64数字
366    JSVM_Value result = nullptr;
367    JSVM_Status status = OH_JSVM_CreateInt64(env, value, &result);
368    if (status != JSVM_OK) {
369        OH_LOG_ERROR(LOG_APP, "JSVM CreateInt64 fail");
370    } else {
371        int64_t number = 0;
372        OH_JSVM_GetValueInt64(env, result, &number);
373        OH_LOG_INFO(LOG_APP, "JSVM CreateInt64 success: %{public}ld", number);
374    }
375    return result;
376}
377
378// CreateInt64注册回调
379static JSVM_CallbackStruct param[] = {
380    {.data = nullptr, .callback = CreateInt64},
381};
382static JSVM_CallbackStruct *method = param;
383// CreateInt64方法别名，供JS调用
384static JSVM_PropertyDescriptor descriptor[] = {
385    {"createInt64", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
386};
387
388// 样例测试js
389const char* srcCallNative = R"JS(createInt64())JS";
390```
391<!-- @[oh_jsvm_create_int64](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmBasicDataTypes/createint64/src/main/cpp/hello.cpp) -->
392
393预期的输出结果：
394
395```
396JSVM CreateInt64 success: 2147483648
397```
398
399### OH_JSVM_CreateDouble
400
401根据double数据创建JavaScript number对象。
402
403cpp部分代码：
404
405```cpp
406// hello.cpp
407#include "napi/native_api.h"
408#include "ark_runtime/jsvm.h"
409#include <hilog/log.h>
410// CreateDouble注册回调
411
412// OH_JSVM_CreateDouble的样例方法
413static JSVM_Value CreateDouble(JSVM_Env env, JSVM_CallbackInfo info)
414{
415    double value = 1.234;
416    // 创建JavaScript中的double数字
417    JSVM_Value result = nullptr;
418    JSVM_Status status = OH_JSVM_CreateDouble(env, value, &result);
419    if (status != JSVM_OK) {
420        OH_LOG_ERROR(LOG_APP, "JSVM CreateDouble fail");
421    } else {
422        double number = 0;
423        OH_JSVM_GetValueDouble(env, result, &number);
424        OH_LOG_INFO(LOG_APP, "JSVM CreateDouble success: %{public}f", number);
425    }
426    return result;
427}
428
429static JSVM_CallbackStruct param[] = {
430    {.data = nullptr, .callback = CreateDouble},
431};
432static JSVM_CallbackStruct *method = param;
433// CreateDouble方法别名，供JS调用
434static JSVM_PropertyDescriptor descriptor[] = {
435    {"createDouble", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
436};
437
438// 样例测试js
439const char* srcCallNative = R"JS(createDouble())JS";
440```
441<!-- @[oh_jsvm_create_double](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmBasicDataTypes/createdouble/src/main/cpp/hello.cpp) -->
442
443预期的输出结果：
444
445```
446JSVM CreateDouble success: 1.234000
447```
448