使用JSVM-API接口进行primitive类相关开发
============================

#### 简介

在使用JSVM-API接口时，开发人员可以实现在JSVM模块中与JavaScript对象的交互，并进行数据转换和获取特定对象的操作，它们在不同的场景中发挥着重要的作用，使开发人员能够更灵活地处理JavaScript值和对象。

#### 基本概念

在使用JSVM操作JavaScript对象时，需要了解一些基本概念：

*   **JavaScript值到C/C++类型的转换：** 在JSVM模块中，可以使用JSVM函数将JavaScript值转换为C/C++的数据类型，如将JavaScript数值转换为C/C++的整数、将JavaScript字符串转换为C/C++的字符数组等。同样，也可以将C/C++的数据类型转换为JavaScript值，以便将结果返回给JavaScript代码。

#### 接口说明

| 接口 | 功能说明 |
| :-- | :-- |
| OH\_JSVM\_CoerceToBool | 将目标值转换为Boolean类型对象。 |
| OH\_JSVM\_CoerceToNumber | 将目标值转换为Number类型对象。 |
| OH\_JSVM\_CoerceToObject | 将目标值转换为Object类型对象。 |
| OH\_JSVM\_CoerceToString | 将目标值转换为String类型对象。 |
| OH\_JSVM\_GetBoolean | 获取JavaScript单例对象。 |
| OH\_JSVM\_GetValueBool | 获取给定JavaScript Boolean的C布尔基础类型值。 |
| OH\_JSVM\_GetGlobal | 获取当前环境中的全局global对象。 |
| OH\_JSVM\_GetNull | 获取JavaScript null。 |
| OH\_JSVM\_GetUndefined | 获取JavaScript undefined。 |

#### 使用示例

JSVM-API接口开发流程参考[使用JSVM-API实现JS与C/C++语言交互开发流程](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/use-jsvm-process)。本文仅展示接口对应的C++相关代码。

#### \[h2\]OH\_JSVM\_CoerceToBool

用于将一个给定的JavaScript值强制转为JavaScript boolean值。

cpp 部分代码：

// hello.cpp
#include "napi/native\_api.h"
#include "ark\_runtime/jsvm.h"
#include <hilog/log.h>
// OH\_JSVM\_CoerceToBool的样例方法
static JSVM\_Value CoerceToBool(JSVM\_Env env, JSVM\_CallbackInfo info)
{
    size\_t argc = 1;
    JSVM\_Value args\[1\] = {nullptr};
    OH\_JSVM\_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
    JSVM\_Value boolean = nullptr;
    JSVM\_Status status = OH\_JSVM\_CoerceToBool(env, args\[0\], &boolean);
    if (status != JSVM\_OK) {
        OH\_LOG\_ERROR(LOG\_APP, "JSVM OH\_JSVM\_CoerceToBool failed");
    } else {
        bool result = false;
        OH\_JSVM\_GetValueBool(env, boolean, &result);
        OH\_LOG\_INFO(LOG\_APP, "JSVM OH\_JSVM\_CoerceToBool success:%{public}d", result);
    }
    return boolean;
}
// CoerceToBool注册回调
static JSVM\_CallbackStruct param\[\] = {
    {.data = nullptr, .callback = CoerceToBool},
};
static JSVM\_CallbackStruct \*method = param;
// CoerceToBool方法别名，ArkTS侧调用
static JSVM\_PropertyDescriptor descriptor\[\] = {
    {"coerceToBool", nullptr, method++, nullptr, nullptr, nullptr, JSVM\_DEFAULT},
};
// 样例测试js
const char \*srcCallNative = R"JS(coerceToBool("123"))JS";

预期结果：

JSVM OH\_JSVM\_CoerceToBool success:1

#### \[h2\]OH\_JSVM\_CoerceToNumber

用于将给定的JavaScript value强转为JavaScript number。

cpp 部分代码：

// hello.cpp
#include "napi/native\_api.h"
#include "ark\_runtime/jsvm.h"
#include <hilog/log.h>
// OH\_JSVM\_CoerceToNumber的样例方法
static JSVM\_Value CoerceToNumber(JSVM\_Env env, JSVM\_CallbackInfo info)
{
    size\_t argc = 1;
    JSVM\_Value args\[1\] = {nullptr};
    OH\_JSVM\_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
    JSVM\_Value number = nullptr;
    JSVM\_Status status = OH\_JSVM\_CoerceToNumber(env, args\[0\], &number);
    if (status != JSVM\_OK) {
        OH\_LOG\_ERROR(LOG\_APP, "JSVM OH\_JSVM\_CoerceToNumber failed");
    } else {
        int32\_t result = 0;
        OH\_JSVM\_GetValueInt32(env, number, &result);
        OH\_LOG\_INFO(LOG\_APP, "JSVM OH\_JSVM\_CoerceToNumber success:%{public}d", result);
    }
    return number;
}
// CoerceToNumber注册回调
static JSVM\_CallbackStruct param\[\] = {
    {.data = nullptr, .callback = CoerceToNumber},
};
static JSVM\_CallbackStruct \*method = param;
// CoerceToNumber方法别名，ArkTS侧调用
static JSVM\_PropertyDescriptor descriptor\[\] = {
    {"coerceToNumber", nullptr, method++, nullptr, nullptr, nullptr, JSVM\_DEFAULT},
};
// 样例测试js
const char \*srcCallNative = R"JS(coerceToNumber(true))JS";

预期结果：

JSVM OH\_JSVM\_CoerceToNumber success:1

#### \[h2\]OH\_JSVM\_CoerceToObject

用于将给定的JavaScript value强转为JavaScript Object类型。

cpp 部分代码：

// hello.cpp
#include "napi/native\_api.h"
#include "ark\_runtime/jsvm.h"
#include <hilog/log.h>
// OH\_JSVM\_CoerceToObject的样例方法
static JSVM\_Value CoerceToObject(JSVM\_Env env, JSVM\_CallbackInfo info)
{
    size\_t argc = 1;
    JSVM\_Value args\[1\] = {nullptr};
    OH\_JSVM\_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
    JSVM\_Value obj = nullptr;
    JSVM\_Status status = OH\_JSVM\_CoerceToObject(env, args\[0\], &obj);
    if (status != JSVM\_OK) {
        OH\_JSVM\_ThrowError(env, nullptr, "JSVM OH\_JSVM\_CoerceToObject failed");
        return nullptr;
    } else {
        OH\_LOG\_INFO(LOG\_APP, "JSVM OH\_JSVM\_CoerceToObject success");
    }
    return obj;
}
// CoerceToObject注册回调
static JSVM\_CallbackStruct param\[\] = {
    {.data = nullptr, .callback = CoerceToObject},
};
static JSVM\_CallbackStruct \*method = param;
// CoerceToObject方法别名，ArkTS侧调用
static JSVM\_PropertyDescriptor descriptor\[\] = {
    {"coerceToObject", nullptr, method++, nullptr, nullptr, nullptr, JSVM\_DEFAULT},
};
// 样例测试js
const char \*srcCallNative = R"JS(coerceToObject(123))JS";

预期结果：

JSVM OH\_JSVM\_CoerceToObject success

#### \[h2\]OH\_JSVM\_CoerceToString

用于将给定的JavaScript value强转为JavaScript string类型。

cpp 部分代码：

// hello.cpp
#include "napi/native\_api.h"
#include "ark\_runtime/jsvm.h"
#include <hilog/log.h>
// OH\_JSVM\_CoerceToString的样例方法
static JSVM\_Value CoerceToString(JSVM\_Env env, JSVM\_CallbackInfo info)
{
    size\_t argc = 1;
    JSVM\_Value args\[1\] = {nullptr};
    OH\_JSVM\_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
    JSVM\_Value str = nullptr;
    JSVM\_Status status = OH\_JSVM\_CoerceToString(env, args\[0\], &str);
    if (status != JSVM\_OK) {
        OH\_JSVM\_ThrowError(env, nullptr, "JSVM OH\_JSVM\_CoerceToString failed");
        return nullptr;
    } else {
        OH\_LOG\_INFO(LOG\_APP, "JSVM OH\_JSVM\_CoerceToString success");
    }
    return str;
}
// CoerceToString注册回调
static JSVM\_CallbackStruct param\[\] = {
    {.data = nullptr, .callback = CoerceToString},
};
static JSVM\_CallbackStruct \*method = param;
// CoerceToString方法别名，ArkTS侧调用
static JSVM\_PropertyDescriptor descriptor\[\] = {
    {"coerceToString", nullptr, method++, nullptr, nullptr, nullptr, JSVM\_DEFAULT},
};
// 样例测试js
const char \*srcCallNative = R"JS(coerceToString(22222))JS";

预期结果：

JSVM OH\_JSVM\_CoerceToString success

#### \[h2\]OH\_JSVM\_GetBoolean

获取给定布尔值的JavaScript单例对象。

cpp 部分代码：

// hello.cpp
#include "napi/native\_api.h"
#include "ark\_runtime/jsvm.h"
#include <hilog/log.h>
// OH\_JSVM\_GetBoolean的样例方法
static JSVM\_Value GetBoolean(JSVM\_Env env, JSVM\_CallbackInfo info)
{
    // 传入两个参数并解析
    size\_t argc = 2;
    JSVM\_Value argv\[2\] = {nullptr};
    OH\_JSVM\_GetCbInfo(env, info, &argc, argv, nullptr, nullptr);
    int32\_t paramData = 0;
    OH\_JSVM\_GetValueInt32(env, argv\[0\], &paramData);
    int32\_t paramValue = 0;
    OH\_JSVM\_GetValueInt32(env, argv\[1\], &paramValue);
    JSVM\_Value returnValue = nullptr;
    bool type = false;
    if (paramData == paramValue) {
        OH\_LOG\_INFO(LOG\_APP, "JSVM resultType equal");
        type = true;
    }
    JSVM\_Status status = OH\_JSVM\_GetBoolean(env, type, &returnValue);
    if (status != JSVM\_OK) {
        OH\_JSVM\_ThrowError(env, nullptr, "JSVM OH\_JSVM\_GetBoolean failed");
    } else {
        bool result = false;
        OH\_JSVM\_GetValueBool(env, returnValue, &result);
        OH\_LOG\_INFO(LOG\_APP, "JSVM OH\_JSVM\_GetBoolean success:%{public}d", result);
    }
    // 返回结果
    return returnValue;
}
// GetBoolean注册回调
static JSVM\_CallbackStruct param\[\] = {
    {.data = nullptr, .callback = GetBoolean},
};
static JSVM\_CallbackStruct \*method = param;
// GetBoolean方法别名，供JS调用
static JSVM\_PropertyDescriptor descriptor\[\] = {
    {"getBoolean", nullptr, method++, nullptr, nullptr, nullptr, JSVM\_DEFAULT},
};
// 样例测试js
const char \*srcCallNative = R"JS(getBoolean(1, 2);
                                 getBoolean(1, 1))JS";

预期结果：

JSVM OH\_JSVM\_GetBoolean success:0
JSVM resultType equal
JSVM OH\_JSVM\_GetBoolean success:1

#### \[h2\]OH\_JSVM\_GetValueBool

使用这个函数将JavaScript中的布尔值转为等价的C布尔值。

cpp 部分代码：

// hello.cpp
#include "napi/native\_api.h"
#include "ark\_runtime/jsvm.h"
#include <hilog/log.h>
// OH\_JSVM\_GetValueBool的样例方法
static JSVM\_Value GetValueBool(JSVM\_Env env, JSVM\_CallbackInfo info)
{
    size\_t argc = 1;
    JSVM\_Value args\[1\] = {nullptr};
    OH\_JSVM\_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
    bool result = false;
    JSVM\_Status status = OH\_JSVM\_GetValueBool(env, args\[0\], &result);
    if (status != JSVM\_OK) {
        // 如果OH\_JSVM\_GetValueBool成功会返回JSVM\_OK，如果传入一个非布尔值则会返回JSVM\_BOOLEAN\_EXPECTED
        OH\_LOG\_ERROR(LOG\_APP, "JSVM OH\_JSVM\_GetValueBool fail:%{public}d", status);
        return nullptr;
    } else {
        OH\_LOG\_INFO(LOG\_APP, "JSVM OH\_JSVM\_GetValueBool success:%{public}d", result);
    }
    JSVM\_Value boolJv = nullptr;
    OH\_JSVM\_GetBoolean(env, result, &boolJv);
    return boolJv;
}
// GetValueBool注册回调
static JSVM\_CallbackStruct param\[\] = {
    {.data = nullptr, .callback = GetValueBool},
};
static JSVM\_CallbackStruct \*method = param;
// GetValueBool方法别名，供JS调用
static JSVM\_PropertyDescriptor descriptor\[\] = {
    {"getValueBool", nullptr, method++, nullptr, nullptr, nullptr, JSVM\_DEFAULT},
};
// 样例测试js
const char \*srcCallNative = R"JS(getValueBool("abc");
                                getValueBool(true);
                                getValueBool(false);)JS";

预期结果：

JSVM OH\_JSVM\_GetValueBool fail:7
JSVM OH\_JSVM\_GetValueBool success:1
JSVM OH\_JSVM\_GetValueBool success:0

#### \[h2\]OH\_JSVM\_GetGlobal

用于获取全局JavaScript对象。该函数的主要作用是获取表示JavaScript全局对象的JSVM\_Value，使JSVM模块能够与JavaScript运行时的全局对象进行交互。

cpp 部分代码：

// hello.cpp
#include "napi/native\_api.h"
#include "ark\_runtime/jsvm.h"
#include <hilog/log.h>
// OH\_JSVM\_GetGlobal的样例方法
static JSVM\_Value GetGlobal(JSVM\_Env env, JSVM\_CallbackInfo info)
{
    // 获取全局对象
    JSVM\_Value value = nullptr;
    JSVM\_Value global = nullptr;
    OH\_JSVM\_CreateInt32(env, 1, &value);
    JSVM\_Status status = OH\_JSVM\_GetGlobal(env, &global);
    OH\_JSVM\_SetNamedProperty(env, global, "Row", value);
    if (status != JSVM\_OK) {
        OH\_LOG\_ERROR(LOG\_APP, "JSVM OH\_JSVM\_GetGlobal fail");
    } else {
        OH\_LOG\_INFO(LOG\_APP, "JSVM OH\_JSVM\_GetGlobal success");
    }
    return global;
}
// GetGlobal注册回调
static JSVM\_CallbackStruct param\[\] = {
    {.data = nullptr, .callback = GetGlobal},
};
static JSVM\_CallbackStruct \*method = param;
// GetGlobal方法别名，供JS调用
static JSVM\_PropertyDescriptor descriptor\[\] = {
    {"getGlobal", nullptr, method++, nullptr, nullptr, nullptr, JSVM\_DEFAULT},
};
// 样例测试js
const char \*srcCallNative = R"JS(getGlobal())JS";

预期结果：

JSVM OH\_JSVM\_GetGlobal success

#### \[h2\]OH\_JSVM\_GetNull

用于获取 JavaScript null 对象。

cpp 部分代码：

// hello.cpp
#include "napi/native\_api.h"
#include "ark\_runtime/jsvm.h"
#include <hilog/log.h>
// OH\_JSVM\_GetNull的样例方法
static JSVM\_Value GetNull(JSVM\_Env env, JSVM\_CallbackInfo info) {
    JSVM\_Value nullValue = nullptr;
    JSVM\_Status status = OH\_JSVM\_GetNull(env, &nullValue);
    if (status != JSVM\_OK) {
        OH\_LOG\_ERROR(LOG\_APP, "JSVM OH\_JSVM\_GetNull fail");
    } else {
        OH\_LOG\_INFO(LOG\_APP, "JSVM OH\_JSVM\_GetNull success");
    }
    return nullValue;
}
// GetNull注册回调
static JSVM\_CallbackStruct param\[\] = {
    {.data = nullptr, .callback = GetNull},
};
static JSVM\_CallbackStruct \*method = param;
// GetNull方法别名，供JS调用
static JSVM\_PropertyDescriptor descriptor\[\] = {
    {"getNull", nullptr, method++, nullptr, nullptr, nullptr, JSVM\_DEFAULT},
};
// 样例测试js
const char \*srcCallNative = R"JS(getNull())JS";

预期结果:

JSVM OH\_JSVM\_GetNull success

#### \[h2\]OH\_JSVM\_GetUndefined

用于获取 JavaScript undefined 对象。

cpp 部分代码：

// hello.cpp
#include "napi/native\_api.h"
#include "ark\_runtime/jsvm.h"
#include <hilog/log.h>
// OH\_JSVM\_GetUndefined的样例方法
static JSVM\_Value GetUndefined(JSVM\_Env env, JSVM\_CallbackInfo info)
{
    // 获取并解析传入的参数
    size\_t argc = 1;
    JSVM\_Value args\[1\] = {nullptr};
    OH\_JSVM\_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
    // 创建一个undefined值
    JSVM\_Value value = nullptr;
    JSVM\_Status status = OH\_JSVM\_GetUndefined(env, &value);
    if (status != JSVM\_OK) {
        OH\_LOG\_ERROR(LOG\_APP, "JSVM OH\_JSVM\_GetUndefined failed");
    } else {
        OH\_LOG\_INFO(LOG\_APP, "JSVM OH\_JSVM\_GetUndefined success");
    }
    return value;
}
// GetUndefined注册回调
static JSVM\_CallbackStruct param\[\] = {
    {.data = nullptr, .callback = GetUndefined},
};
static JSVM\_CallbackStruct \*method = param;
// GetUndefined方法别名，供JS调用
static JSVM\_PropertyDescriptor descriptor\[\] = {
    {"getUndefined", nullptr, method++, nullptr, nullptr, nullptr, JSVM\_DEFAULT},
};
// 样例测试js
const char \*srcCallNative = R"JS(getUndefined())JS";

预期结果:

JSVM OH\_JSVM\_GetUndefined success