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