• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 使用JSVM-API接口创建和获取string值
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字符串的交互功能。
12
13## 基本概念
14
15string是编程中常用的数据类型。用于存储和操作文本数据，它可用于构建用户界面元素，如标签、按钮和文本框，处理用户输入，验证和格式化数据。不同的编码方案支持不同的字符集和语言，以下是一些主要的编码方案及其区别：
16
17- **ASCII**：ASCII是最早的字符编码方案之一，使用7位编码，只能表示英文字母、数字和一些基本符号。它是许多其他编码方案的基础。
18- **UTF-8**：UTF-8是一种变长编码方案，可以表示全球范围的字符集。它使用8位编码，根据字符的不同范围使用不同长度的字节序列。UTF-8是互联网上广泛使用的编码方案。
19- **UTF-16**：UTF-16是一种定长或变长编码方案，使用16位编码。它可以表示全球范围的字符集，并且适用于较大的字符集。
20- **ISO-8859-1（Latin-1）**：ISO-8859-1是一种单字节编码方案，使用8位编码。它主要用于表示拉丁字母字符集，包括欧洲大部分语言。
21
22## 接口说明
23
24| 接口                       | 功能说明                       |
25|----------------------------|--------------------------------|
26| OH_JSVM_GetValueStringUtf8       | 获取给定JavaScript string对象的Utf8编码字符串。|
27| OH_JSVM_CreateStringUtf8          | 根据Utf8编码的字符串创建一个JavaScript string对象。|
28| OH_JSVM_GetValueStringUtf16      | 获取给定JavaScript string对象的Utf16编码字符串。|
29| OH_JSVM_CreateStringUtf16         | 根据Utf16编码的字符串数据创建JavaScript string对象。|
30| OH_JSVM_GetValueStringLatin1     | 获取给定JavaScript string对象的Latin-1编码字符串。|
31| OH_JSVM_CreateStringLatin1        | 根据Latin-1编码的字符串创建一个JavaScript string对象。|
32
33## 使用示例
34
35JSVM-API接口开发流程参考[使用JSVM-API实现JS与C/C++语言交互开发流程](use-jsvm-process.md)。本文仅展示接口对应的C++相关代码。
36
37### OH_JSVM_GetValueStringUtf8
38
39OH_JSVM_GetValueStringUtf8接口可以将JavaScript的字符类型的数据转换为utf8编码的字符。
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#include <cstdlib>
49// OH_JSVM_GetValueStringUtf8的样例方法
50static JSVM_Value GetValueStringUtf8(JSVM_Env env, JSVM_CallbackInfo info)
51{
52    size_t argc = 1;
53    JSVM_Value args[1] = {nullptr};
54    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
55    size_t length = 0;
56    JSVM_Status status = OH_JSVM_GetValueStringUtf8(env, args[0], nullptr, 0, &length);
57    char *buf = (char *)malloc(length + 1);
58    if (buf == nullptr) {
59        OH_LOG_ERROR(LOG_APP, "malloc failed");
60        return nullptr;
61    }
62    memset(buf, 0, length + 1);
63    status = OH_JSVM_GetValueStringUtf8(env, args[0], buf, length + 1, &length);
64    if (status != JSVM_OK) {
65        OH_LOG_ERROR(LOG_APP, "JSVM GetValueStringUtf8 fail");
66        free(buf);
67        return nullptr;
68    } else {
69        OH_LOG_INFO(LOG_APP, "JSVM GetValueStringUtf8 success: %{public}s", buf);
70    }
71    JSVM_Value result = nullptr;
72    OH_JSVM_CreateStringUtf8(env, buf, length, &result);
73    free(buf);
74    return result;
75}
76// GetValueStringUtf8注册回调
77static JSVM_CallbackStruct param[] = {
78    {.data = nullptr, .callback = GetValueStringUtf8},
79};
80static JSVM_CallbackStruct *method = param;
81// GetValueStringUtf8方法别名，供JS调用
82static JSVM_PropertyDescriptor descriptor[] = {
83    {"getValueStringUtf8", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
84};
85
86// 样例测试js
87const char *srcCallNative = R"JS(
88    let data = "aaBC+-$%^你好123";
89    let script = getValueStringUtf8(data);
90)JS";
91```
92<!-- @[oh_jsvm_get_value_string_utf8](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutString/getvaluestringutf8/src/main/cpp/hello.cpp) -->
93
94预期输出结果：
95```cpp
96JSVM GetValueStringUtf8 success: aaBC+-$%^你好123
97```
98**注意事项**：`getValueStringUtf8(arg)`入参`arg`非字符串型数据时接口会调用失败。
99
100### OH_JSVM_CreateStringUtf8
101
102用于创建一个UTF-8编码的JavaScript字符串。
103
104cpp部分代码：
105
106```cpp
107// hello.cpp
108#include "napi/native_api.h"
109#include "ark_runtime/jsvm.h"
110#include <hilog/log.h>
111#include <string>
112// OH_JSVM_CreateStringUtf8的样例方法
113static JSVM_Value CreateStringUtf8(JSVM_Env env, JSVM_CallbackInfo info)
114{
115    const char *str = u8"你好, World!, successes to create UTF-8 string!";
116    size_t length = strlen(str);
117    JSVM_Value result = nullptr;
118    JSVM_Status status = OH_JSVM_CreateStringUtf8(env, str, length, &result);
119    if (status != JSVM_OK) {
120        OH_JSVM_ThrowError(env, nullptr, "Failed to create UTF-8 string");
121        return nullptr;
122    } else {
123        OH_LOG_INFO(LOG_APP, "JSVM CreateStringUtf8 success: %{public}s", str);
124    }
125    return result;
126}
127// CreateStringUtf8注册回调
128static JSVM_CallbackStruct param[] = {
129    {.data = nullptr, .callback = CreateStringUtf8},
130};
131static JSVM_CallbackStruct *method = param;
132// CreateStringUtf8方法别名，供JS调用
133static JSVM_PropertyDescriptor descriptor[] = {
134    {"createStringUtf8", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
135};
136
137// 样例测试js
138const char *srcCallNative = R"JS(
139    let script = createStringUtf8();
140)JS";
141```
142<!-- @[oh_jsvm_create_string_utf8](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutString/createstringutf8/src/main/cpp/hello.cpp) -->
143
144预期输出结果：
145```cpp
146JSVM CreateStringUtf8 success: 你好, World!, successes to create UTF-8 string!
147```
148### OH_JSVM_GetValueStringUtf16
149
150OH_JSVM_GetValueStringUtf16，将JavaScript的字符类型的数据转换为utf16编码的字符。
151
152cpp部分代码：
153
154```cpp
155// hello.cpp
156#include "napi/native_api.h"
157#include "ark_runtime/jsvm.h"
158#include <hilog/log.h>
159#include <codecvt>
160#include <locale>
161#include <cstdlib>
162
163// OH_JSVM_GetValueStringUtf16的样例方法
164// 定义字符串缓冲区的最大长度
165static const int MAX_BUFFER_SIZE = 128;
166static JSVM_Value GetValueStringUtf16(JSVM_Env env, JSVM_CallbackInfo info) {
167    size_t argc = 1;
168    JSVM_Value args[1] = {nullptr};
169    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
170    JSVM_Value result = nullptr;
171    size_t length = 0;
172    char16_t buffer[MAX_BUFFER_SIZE] = {0};
173    // 字符串的缓冲区大小
174    size_t bufferSize = MAX_BUFFER_SIZE;
175    JSVM_Status status = OH_JSVM_GetValueStringUtf16(env, args[0], buffer, bufferSize, &length);
176    // 将 char16_t 转换为 std::u16string
177    std::u16string u16str = {buffer};
178    // 将 std::u16string 转换为 std::string
179    std::wstring_convert<std::codecvt_utf8_utf16<char16_t>, char16_t> converter;
180    std::string str = converter.to_bytes(u16str);
181    // 获取字符串返回结果
182    if (status != JSVM_OK) {
183        OH_LOG_ERROR(LOG_APP, "JSVM GetValueStringUtf16 fail");
184        return nullptr;
185    } else {
186        OH_LOG_INFO(LOG_APP, "JSVM GetValueStringUtf16 success: %{public}s", str.c_str());
187    }
188    return result;
189}
190// GetValueStringUtf16注册回调
191static JSVM_CallbackStruct param[] = {
192    {.data = nullptr, .callback = GetValueStringUtf16},
193};
194static JSVM_CallbackStruct *method = param;
195// GetValueStringUtf16方法别名，供JS调用
196static JSVM_PropertyDescriptor descriptor[] = {
197    {"getValueStringUtf16", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
198};
199
200// 样例测试js
201const char *srcCallNative = R"JS(
202    let data = "ahello。";
203    let script = getValueStringUtf16(data);
204)JS";
205```
206<!-- @[oh_jsvm_get_value_string_utf16](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutString/getvaluestringutf16/src/main/cpp/hello.cpp) -->
207
208预期输出结果：
209```cpp
210JSVM GetValueStringUtf16 success: ahello。
211```
212**注意事项**：`getValueStringUtf16(arg)`的参数`arg`必须是字符串，否则接口会调用失败。
213
214### OH_JSVM_CreateStringUtf16
215
216用于创建一个UTF-16编码的JavaScript字符串。
217
218cpp部分代码：
219
220```cpp
221// hello.cpp
222#include "napi/native_api.h"
223#include "ark_runtime/jsvm.h"
224#include <hilog/log.h>
225#include <codecvt>
226#include <locale>
227#include <cstring>
228
229// OH_JSVM_CreateStringUtf16的样例方法
230static JSVM_Value CreateStringUtf16(JSVM_Env env, JSVM_CallbackInfo info)
231{
232    const char16_t *str = u"你好, World!, successes to create UTF-16 string!";
233    std::u16string ustr(str);
234    size_t length = ustr.length();
235    JSVM_Value result = nullptr;
236    JSVM_Status status = OH_JSVM_CreateStringUtf16(env, str, length, &result);
237    std::u16string u16str = {str};
238    // 将 std::u16string 转换为 std::string
239    std::wstring_convert<std::codecvt_utf8_utf16<char16_t>, char16_t> converter;
240    std::string strResult = converter.to_bytes(u16str);
241    if (status != JSVM_OK) {
242        OH_LOG_ERROR(LOG_APP, "JSVM CreateStringUtf16 fail");
243    }else {
244        OH_LOG_INFO(LOG_APP, "JSVM CreateStringUtf16 success: %{public}s", strResult.c_str());
245    }
246    return result;
247}
248// CreateStringUtf16注册回调
249static JSVM_CallbackStruct param[] = {
250    {.data = nullptr, .callback = CreateStringUtf16},
251};
252static JSVM_CallbackStruct *method = param;
253// CreateStringUtf16方法别名，供JS调用
254static JSVM_PropertyDescriptor descriptor[] = {
255    {"createStringUtf16", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
256};
257
258// 样例测试js
259const char *srcCallNative = R"JS(
260    let script = createStringUtf16();
261)JS";
262```
263<!-- @[oh_jsvm_create_string_utf16](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutString/createstringutf16/src/main/cpp/hello.cpp) -->
264
265预期输出结果：
266```cpp
267JSVM CreateStringUtf16 success: 你好, World!, successes to create UTF-16 string!
268```
269### OH_JSVM_GetValueStringLatin1
270
271OH_JSVM_GetValueStringLatin1接口可以将JavaScript的字符类型的数据转换为ISO-8859-1编码的字符。
272
273cpp部分代码：
274
275```cpp
276// hello.cpp
277#include "napi/native_api.h"
278#include "ark_runtime/jsvm.h"
279#include <hilog/log.h>
280#include <cstdlib>
281// OH_JSVM_GetValueStringLatin1的样例方法
282// 定义字符串缓冲区的最大长度
283static const int MAX_BUFFER_SIZE = 128;
284static JSVM_Value GetValueStringLatin1(JSVM_Env env, JSVM_CallbackInfo info)
285{
286    size_t argc = 1;
287    JSVM_Value args[1] = {nullptr};
288    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
289    char buf[MAX_BUFFER_SIZE];
290    size_t length = 0;
291    JSVM_Value jsvmRes = nullptr;
292    JSVM_Status status = OH_JSVM_GetValueStringLatin1(env, args[0], buf, MAX_BUFFER_SIZE, &length);
293    if (status != JSVM_OK) {
294        OH_LOG_ERROR(LOG_APP, "JSVM GetValueStringLatin1 fail");
295    } else {
296        OH_LOG_INFO(LOG_APP, "JSVM GetValueStringLatin1 success: %{public}s", buf);
297    }
298    OH_JSVM_CreateStringLatin1(env, buf, length, &jsvmRes);
299    return jsvmRes;
300}
301// GetValueStringLatin1注册回调
302static JSVM_CallbackStruct param[] = {
303    {.data = nullptr, .callback = GetValueStringLatin1},
304};
305static JSVM_CallbackStruct *method = param;
306// GetValueStringLatin1方法别名，供JS调用
307static JSVM_PropertyDescriptor descriptor[] = {
308    {"getValueStringLatin1", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
309};
310
311// 样例测试js
312const char *srcCallNative = R"JS(
313    let data = "中文";
314    let script = getValueStringLatin1(data);
315)JS";
316```
317<!-- @[oh_jsvm_get_value_string_latin1](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutString/getvaluestringlatin1/src/main/cpp/hello.cpp) -->
318
319预期输出结果（ISO-8859-1编码不支持中文，传入中文字符会导致乱码）：
320
321![GetValueStringLatin1](figures/jsvm_about_string_GetValueStringLatin1.png)
322
323**注意事项**：`getValueStringLatin1(arg)`入参`arg`必须为字符串类型，否则接口调用会失败。
324
325### OH_JSVM_CreateStringLatin1
326
327用于创建一个Latin1编码的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#include <cstring>
337// CreateStringLatin1注册回调
338// 定义字符串缓冲区的最大长度
339static const int MAX_BUFFER_SIZE = 128;
340// OH_JSVM_CreateStringLatin1的样例方法
341static JSVM_Value CreateStringLatin1(JSVM_Env env, JSVM_CallbackInfo info)
342{
343    const char *str = "Hello, World! éçñ, successes to create Latin1 string!";
344    size_t length = JSVM_AUTO_LENGTH;
345    JSVM_Value result = nullptr;
346    JSVM_Status status = OH_JSVM_CreateStringLatin1(env, str, length, &result);
347    if (status != JSVM_OK) {
348        OH_LOG_ERROR(LOG_APP, "JSVM CreateStringLatin1 fail");
349    } else {
350        char buf[MAX_BUFFER_SIZE];
351        size_t length = 0;
352        OH_JSVM_GetValueStringLatin1(env, result, buf, MAX_BUFFER_SIZE, &length);
353        OH_LOG_INFO(LOG_APP, "JSVM CreateStringLatin1 success: %{public}s", buf);
354    }
355    return result;
356}
357static JSVM_CallbackStruct param[] = {
358    {.data = nullptr, .callback = CreateStringLatin1},
359};
360static JSVM_CallbackStruct *method = param;
361// CreateStringLatin1方法别名，供JS调用
362static JSVM_PropertyDescriptor descriptor[] = {
363    {"createStringLatin1", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
364};
365
366// 样例测试js
367const char *srcCallNative = R"JS(
368    let script = createStringLatin1();
369)JS";
370```
371<!-- @[oh_jsvm_create_string_latin1](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutString/createstringlatin1/src/main/cpp/hello.cpp) -->
372
373预期输出结果：
374```cpp
375JSVM CreateStringLatin1 success: Hello, World! éçñ, successes to create Latin1 string!
376```