1# 使用JSVM-API接口操作bigint类型值 2 3## 简介 4 5BigInt是JavaScript中用于表示任意精度整数的数据类型，它能够处理比Number类型更大范围的整数值。通过JSVM-API提供的接口，可以在JSVM模块中创建、获取和操作BigInt类型值，从而实现与BigInt相关的功能扩展。 6 7## 基本概念 8 9在使用JSVM-API接口操作BigInt类型值时，需要理解以下基本概念： 10 11- **BigInt类型：** BigInt是JavaScript中的一种数据类型，用于表示任意精度的整数。与Number类型不同，BigInt类型可以精确表示非常大的整数，而不会丢失精度或溢出。 12- **BigInt创建：** 使用JSVM-API提供的接口，可以通过传递C的int64或uint64数据来创建对应的JavaScript BigInt。这使得在JSVM模块中可以方便地创建BigInt类型值。 13- **BigInt操作：** JSVM-API提供了多个接口用于操作BigInt类型值。通过这些接口，可以获取BigInt的数值，进行数值转换，以及执行常见的算术和位运算操作。 14 15## 接口说明 16 17| 接口 | 功能说明 | 18| ---------------------------- | ---------------------------------------- | 19| OH_JSVM_CreateBigintInt64 | 将C int64_t类型的值转换为JavaScript BigInt类型。| 20| OH_JSVM_CreateBigintUint64 | 将C uint64_t类型的值转换为JavaScript BigInt类型。| 21| OH_JSVM_CreateBigintWords | 将一组无符号64位字转换为单个BigInt值。| 22| OH_JSVM_GetValueBigintInt64 | 返回给定JavaScript BigInt的C int64_t基础类型等价值。 如果需要，它将截断该值，将lossless设置为false。 | 23| OH_JSVM_GetValueBigintUint64 | 返回给定JavaScript BigInt的C uint64_t基础类型等价值。 如果需要，它将截断该值，将lossless设置为false。 | 24| OH_JSVM_GetValueBigintWords | 将单个BigInt值转换为符号位、64位小端数组和数组中的元素数。 signBit和words参数可以都设置为NULL。这种情况下，只获取wordCount。| 25 26## 使用示例 27 28JSVM-API接口开发流程参考[使用JSVM-API实现JS与C/C++语言交互开发流程](use-jsvm-process.md)，本文仅对接口对应C++及ArkTS相关代码进行展示。 29 30### OH_JSVM_GetValueBigintWords 31 32获取给定JavaScript BigInt对象的底层数据，即BigInt数据的字词表示。 33 34cpp部分代码 35 36```cpp 37// hello.cpp 38#include "napi/native_api.h" 39#include "ark_runtime/jsvm.h" 40#include <hilog/log.h> 41// GetValueBigintWords注册回调 42static JSVM_CallbackStruct param[] = { 43 {.data = nullptr, .callback = GetValueBigintWords}, 44}; 45static JSVM_CallbackStruct *method = param; 46// GetValueBigintWords方法别名，供JS调用 47static JSVM_PropertyDescriptor descriptor[] = { 48 {"getValueBigintWords", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT}, 49}; 50// OH_JSVM_GetValueBigintWords的样例方法 51static JSVM_Value GetValueBigintWords(JSVM_Env env, JSVM_CallbackInfo info) 52{ 53 size_t argc = 1; 54 JSVM_Value args[1] = {nullptr}; 55 OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr); 56 int signBit = 0; 57 size_t wordCount = 0; 58 uint64_t words; 59 // 调用OH_JSVM_GetValueBigintWords接口获取wordCount 60 JSVM_Status status = OH_JSVM_GetValueBigintWords(env, args[0], nullptr, &wordCount, nullptr); 61 OH_LOG_INFO(LOG_APP, "OH_JSVM_GetValueBigintWords wordCount:%{public}d.", wordCount); 62 // 调用OH_JSVM_GetValueBigintWords接口获取传入bigInt相关信息，如：signBit传入bigInt正负信息 63 status = OH_JSVM_GetValueBigintWords(env, args[0], &signBit, &wordCount, &words); 64 if (status != JSVM_OK) { 65 OH_LOG_ERROR(LOG_APP, "OH_JSVM_GetValueBigintWords fail, status:%{public}d.", status); 66 } else { 67 OH_LOG_INFO(LOG_APP, "OH_JSVM_GetValueBigintWords signBit: %{public}d.", signBit); 68 } 69 // 将符号位转化为int类型传出去 70 JSVM_Value returnValue = nullptr; 71 OH_JSVM_CreateInt32(env, signBit, &returnValue); 72 return returnValue; 73} 74``` 75 76ArkTS侧示例代码 77 78```ts 79import hilog from "@ohos.hilog" 80// 通过import的方式，引入Native能力。 81import napitest from "libentry.so" 82try { 83 let script: string = `getValueBigintWords(BigInt(5555555555555555))`; 84 let result = napitest.runJsVm(script); 85 hilog.info(0x0000, 'testJSVM', 'Test JSVM getValueBigintWords: %{public}s', result); 86} catch (error) { 87 hilog.error(0x0000, 'testJSVM', 'Test JSVM getValueBigintWords error: %{public}s', error.message); 88} 89try { 90 let script: string = `getValueBigintWords(BigInt(-5555555555555555))`; 91 let result = napitest.runJsVm(script); 92 hilog.info(0x0000, 'testJSVM', 'Test JSVM getValueBigintWords: %{public}s', result); 93} catch (error) { 94 hilog.error(0x0000, 'testJSVM', 'Test JSVM getValueBigintWords error: %{public}s', error.message); 95} 96``` 97 98### OH_JSVM_CreateBigintWords 99 100根据给定的Uint64_t数组创建一个JavaScript BigInt对象。 101 102cpp部分代码 103 104```cpp 105// hello.cpp 106#include "napi/native_api.h" 107#include "ark_runtime/jsvm.h" 108#include <hilog/log.h> 109// CreateBigintWords注册回调 110static JSVM_CallbackStruct param[] = { 111 {.data = nullptr, .callback = CreateBigintWords}, 112}; 113static JSVM_CallbackStruct *method = param; 114// CreateBigintWords方法别名，供JS调用 115static JSVM_PropertyDescriptor descriptor[] = { 116 {"createBigintWords", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT}, 117}; 118// OH_JSVM_CreateBigintWords的样例方法 119static int DIFF_VALUE_THREE = 3; 120static JSVM_Value CreateBigintWords(JSVM_Env env, JSVM_CallbackInfo info) 121{ 122 // 使用OH_JSVM_CreateBigintWords接口创建一个BigInt对象 123 int signBit = 0; 124 size_t wordCount = DIFF_VALUE_THREE; 125 uint64_t words[] = {12ULL, 34ULL, 56ULL}; 126 JSVM_Value returnValue = nullptr; 127 JSVM_Status status = OH_JSVM_CreateBigintWords(env, signBit, wordCount, words, &returnValue); 128 if (status != JSVM_OK) { 129 OH_LOG_ERROR(LOG_APP, "JSVM OH_JSVM_CreateBigintWords fail"); 130 } else { 131 OH_LOG_INFO(LOG_APP, "JSVM OH_JSVM_CreateBigintWords success"); 132 } 133 return returnValue; 134} 135``` 136 137ArkTS侧示例代码 138 139```ts 140import hilog from "@ohos.hilog" 141// 通过import的方式，引入Native能力。 142import napitest from "libentry.so" 143try { 144 let script: string = `createBigintWords()`; 145 let result = napitest.runJsVm(script); 146 hilog.info(0x0000, 'testJSVM', 'Test JSVM createBigintWords: %{public}s', result); 147} catch (error) { 148 hilog.error(0x0000, 'testJSVM', 'Test JSVM createBigintWords error: %{public}s', error.message); 149} 150``` 151 152### OH_JSVM_CreateBigintUint64 153 154根据Uint64类型对象创建 JavaScript Bigint对象。 155 156cpp部分代码 157 158```cpp 159// hello.cpp 160#include "napi/native_api.h" 161#include "ark_runtime/jsvm.h" 162#include <hilog/log.h> 163// 声明uint64_t的变量value 164static uint64_t TEST_VALUE = 5555555555555555555; 165// CreateBigintUint64注册回调 166static JSVM_CallbackStruct param[] = { 167 {.data = nullptr, .callback = CreateBigintUint64}, 168}; 169static JSVM_CallbackStruct *method = param; 170// CreateBigintUint64方法别名，供JS调用 171static JSVM_PropertyDescriptor descriptor[] = { 172 {"createBigintUint64", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT}, 173}; 174// OH_JSVM_CreateBigintUint64的样例方法 175static JSVM_Value CreateBigintUint64(JSVM_Env env, JSVM_CallbackInfo info) 176{ 177 // 将value转化为JSVM_Value类型返回 178 JSVM_Value returnValue = nullptr; 179 JSVM_Status status = OH_JSVM_CreateBigintUint64(env, TEST_VALUE, &returnValue); 180 if (status != JSVM_OK) { 181 OH_LOG_ERROR(LOG_APP, "JSVM OH_JSVM_CreateBigintUint64 fail"); 182 } else { 183 OH_LOG_INFO(LOG_APP, "JSVM OH_JSVM_CreateBigintUint64 success"); 184 } 185 return returnValue; 186} 187``` 188 189ArkTS侧示例代码 190 191```ts 192import hilog from "@ohos.hilog" 193// 通过import的方式，引入Native能力。 194import napitest from "libentry.so" 195try { 196 let script: string = `createBigintUint64()`; 197 let result = napitest.runJsVm(script); 198 hilog.info(0x0000, 'testJSVM', 'Test JSVM createBigintUint64: %{public}s', result); 199} catch (error) { 200 hilog.error(0x0000, 'testJSVM', 'Test JSVM createBigintUint64 error: %{public}s', error.message); 201} 202``` 203 204### OH_JSVM_GetValueBigintUint64 205 206获取给定JavaScript BigInt的Uint64_t基础类型值。 207 208cpp部分代码 209 210```cpp 211// hello.cpp 212#include "napi/native_api.h" 213#include "ark_runtime/jsvm.h" 214#include <hilog/log.h> 215// GetValueBigintUint64注册回调 216static JSVM_CallbackStruct param[] = { 217 {.data = nullptr, .callback = GetValueBigintUint64}, 218}; 219static JSVM_CallbackStruct *method = param; 220// GetValueBigintUint64方法别名，供JS调用 221static JSVM_PropertyDescriptor descriptor[] = { 222 {"getValueBigintUint64", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT}, 223}; 224// OH_JSVM_GetValueBigintUint64的样例方法 225static JSVM_Value GetValueBigintUint64(JSVM_Env env, JSVM_CallbackInfo info) 226{ 227 size_t argc = 1; 228 JSVM_Value args[1] = {nullptr}; 229 OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr); 230 // 从参数值中获取BigInt的数值 231 uint64_t value = 0; 232 bool lossLess = false; 233 OH_JSVM_GetValueBigintUint64(env, args[0], &value, &lossLess); 234 // 判断从JS侧获取bigint是否为无损转换，如果不是抛出异常 235 if (!lossLess) { 236 OH_JSVM_ThrowError(env, nullptr, "BigInt values have no lossless converted"); 237 return nullptr; 238 } else { 239 OH_LOG_INFO(LOG_APP, "JSVM GetValueBigintUint64 success:%{public}d", lossLess); 240 } 241 JSVM_Value returnValue = nullptr; 242 OH_JSVM_CreateBigintUint64(env, value, &returnValue); 243 return returnValue; 244} 245``` 246 247接口声明 248 249ArkTS侧示例代码 250 251```ts 252import hilog from "@ohos.hilog" 253// 通过import的方式，引入Native能力。 254import napitest from "libentry.so" 255try { 256 let script: string = `getValueBigintUint64(BigInt(5555555555555555))`; 257 let result = napitest.runJsVm(script); 258 hilog.info(0x0000, 'testJSVM', 'Test JSVM getValueBigintUint64: %{public}s', result); 259} catch (error) { 260 hilog.error(0x0000, 'testJSVM', 'Test JSVM getValueBigintUint64 error: %{public}s', error.message); 261} 262``` 263 264### OH_JSVM_CreateBigintInt64 265 266根据Uint64类型对象创建JavaScript Bigint对象。 267 268cpp部分代码 269 270```cpp 271// hello.cpp 272#include "napi/native_api.h" 273#include "ark_runtime/jsvm.h" 274#include <hilog/log.h> 275// 声明int64_t的变量value 276static int64_t TEST_VALUE_DEMO = -5555555555555555555; 277// CreateBigintInt64注册回调 278static JSVM_CallbackStruct param[] = { 279 {.data = nullptr, .callback = CreateBigintInt64}, 280}; 281static JSVM_CallbackStruct *method = param; 282// CreateBigintInt64方法别名，供JS调用 283static JSVM_PropertyDescriptor descriptor[] = { 284 {"createBigintInt64", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT}, 285}; 286// OH_JSVM_CreateBigintInt64的样例方法 287static JSVM_Value CreateBigintInt64(JSVM_Env env, JSVM_CallbackInfo info) 288{ 289 JSVM_Value returnValue = nullptr; 290 JSVM_Status status = OH_JSVM_CreateBigintInt64(env, TEST_VALUE_DEMO, &returnValue); 291 if (status != JSVM_OK) { 292 OH_LOG_ERROR(LOG_APP, "JSVM OH_JSVM_CreateBigintInt64 fail"); 293 } else { 294 OH_LOG_INFO(LOG_APP, "JSVM OH_JSVM_CreateBigintInt64 success"); 295 } 296 return returnValue; 297} 298``` 299 300ArkTS侧示例代码 301 302```ts 303import hilog from "@ohos.hilog" 304// 通过import的方式，引入Native能力。 305import napitest from "libentry.so" 306try { 307 let script: string = `createBigintInt64()`; 308 let result = napitest.runJsVm(script); 309 hilog.info(0x0000, 'testJSVM', 'Test JSVM createBigintInt64: %{public}s', result); 310} catch (error) { 311 hilog.error(0x0000, 'testJSVM', 'Test JSVM createBigintInt64 error: %{public}s', error.message); 312} 313``` 314 315### OH_JSVM_GetValueBigintInt64 316 317用于从传入的参数中提取64位整数的BigInt数据，以供后续处理。 318 319cpp部分代码 320 321```cpp 322// hello.cpp 323#include "napi/native_api.h" 324#include "ark_runtime/jsvm.h" 325#include <hilog/log.h> 326// GetBigintInt64注册回调 327static JSVM_CallbackStruct param[] = { 328 {.data = nullptr, .callback = GetBigintInt64}, 329}; 330static JSVM_CallbackStruct *method = param; 331// GetBigintInt64方法别名，供JS调用 332static JSVM_PropertyDescriptor descriptor[] = { 333 {"getBigintInt64", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT}, 334}; 335// OH_JSVM_GetValueBigintInt64的样例方法 336static JSVM_Value GetBigintInt64(JSVM_Env env, JSVM_CallbackInfo info) 337{ 338 size_t argc = 1; 339 JSVM_Value args[1] = {nullptr}; 340 OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr); 341 // 从传入的参数中提取64位整数的BigInt数据 342 int64_t value; 343 bool lossLess; 344 OH_JSVM_GetValueBigintInt64(env, args[0], &value, &lossLess); 345 // 判断从JS侧获取bigint是否为无损转换，如果不是抛出异常 346 if (!lossLess) { 347 OH_JSVM_ThrowError(env, nullptr, "BigInt values have no lossless converted"); 348 return nullptr; 349 } else { 350 OH_LOG_INFO(LOG_APP, "JSVM GetBigintInt64 success:%{public}d", lossLess); 351 } 352 JSVM_Value returnValue = nullptr; 353 OH_JSVM_CreateBigintInt64(env, value, &returnValue); 354 return returnValue; 355} 356``` 357 358ArkTS侧示例代码 359 360```ts 361import hilog from "@ohos.hilog" 362// 通过import的方式，引入Native能力。 363import napitest from "libentry.so" 364try { 365 let script: string = `getBigintInt64(BigInt(-5555555555555555))`; 366 let result = napitest.runJsVm(script); 367 hilog.info(0x0000, 'testJSVM', 'Test JSVM getBigintInt64: %{public}d', result); 368} catch (error) { 369 hilog.error(0x0000, 'testJSVM', 'Test JSVM getBigintInt64 error: %{public}s', error.message); 370} 371``` 372