• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 使用Node-API接口进行Date相关开发
2<!--Kit: NDK-->
3<!--Subsystem: arkcompiler-->
4<!--Owner: @xliu-huanwei; @shilei123; @huanghello-->
5<!--Designer: @shilei123-->
6<!--Tester: @kirl75; @zsw_zhushiwei-->
7<!--Adviser: @fang-jinxu-->
8
9## 简介
10
11Node-API中date相关接口用于处理ArkTS Date对象，并在Node-API模块和ArkTS代码之间进行日期数据的转换和处理。这对于在Node-API模块中处理时间和日期相关逻辑非常有用。
12
13## 基本概念
14
15在Node-API的中，ArkTS Date对象的数据表示从UTC时间1970年1月1日0时0分0秒起至现在的总毫秒数。
16
17ArkTS Date对象提供了一种在ArkTS中表示和操作日期和时间的方式。它们允许您创建表示特定时刻的日期对象，执行各种日期和时间相关的计算（如添加或减去时间间隔），以及格式化日期为字符串以供显示。
18
19在Node-API中，通过提供与Date对象交互的函数，Node-API模块能够更紧密地与ArkTS环境集成，执行更复杂的日期和时间相关操作。
20
21## 场景和功能介绍
22
23以下Node-API函数通常在开发Node-API模块中与ArkTS的Date对象进行交互时使用，来处理和操作日期数据。以下是一些可能的使用场景：
24| 接口 | 描述 |
25| -------- | -------- |
26| napi_create_date | 在需要根据当前系统时间或特定计算生成一个Date对象时，可通过使用此接口创建表示这些时间的ArkTS Date对象，然后将其传递给ArkTS代码进行进一步处理。 |
27| napi_get_date_value | 在Node-API模块中接收到一个ArkTS的Date对象，并且需要获取其对应的时间戳或日期值时，可以使用此接口。|
28| napi_is_date | 在需要确定一个ArkTS对象是否为Date对象时，可使用此接口判断给定的值是否为Date对象。例如，在接收函数参数时，需要验证参数是否为Date对象以确保正确的数据类型。 |
29
30## 使用示例
31
32Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅对接口对应的C++及ArkTS相关代码进行展示。
33
34### napi_create_date
35
36通过一个C++的double数据创建ArkTS的Date对象。
37
38cpp部分代码
39
40```cpp
41#include "napi/native_api.h"
42
43static napi_value CreateDate(napi_env env, napi_callback_info info)
44{
45    // 获取传入的Unix Time Stamp时间
46    double value = 1501924876711;
47    // 调用napi_create_date接口将double值转换成表示日期时间的ArkTS对象，并放入returnValue中
48    napi_value returnValue = nullptr;
49    napi_create_date(env, value, &returnValue);
50    return returnValue;
51}
52```
53<!-- @[napi_create_date](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIDate/entry/src/main/cpp/napi_init.cpp) -->
54
55接口声明
56
57```ts
58// index.d.ts
59export const createDate: () => Date;
60```
61<!-- @[napi_create_date_api](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIDate/entry/src/main/cpp/types/libentry/Index.d.ts) -->
62
63ArkTS侧示例代码
64
65```ts
66import { hilog } from '@kit.PerformanceAnalysisKit';
67import testNapi from 'libentry.so';
68
69hilog.info(0x0000, 'testTag', 'Test Node-API napi_create_date: %{public}s', testNapi.createDate().toString());
70```
71<!-- @[ark_napi_create_date](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIDate/entry/src/main/ets/pages/Index.ets) -->
72
73### napi_get_date_value
74
75获取给定ArkTS Date对应的C++ double值。
76
77cpp部分代码
78
79```cpp
80#include <hilog/log.h>
81#include "napi/native_api.h"
82
83static napi_value GetDateValue(napi_env env, napi_callback_info info)
84{
85    size_t argc = 1;
86    napi_value args[1] = {nullptr};
87    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
88
89    // 获取传入的Unix Time Stamp时间
90    double value = 0;
91    napi_status status = napi_get_date_value(env, args[0], &value);
92    if (status != napi_ok) {
93        napi_throw_error(env, nullptr, "napi_get_date_value fail");
94        return nullptr;
95    }
96
97    // 将获取到的Unix Time Stamp时间打印
98    OH_LOG_INFO(LOG_APP, "Node-API gets unix time stamp is:%{public}lf.", value);
99
100    // 把转换后的Unix Time Stamp时间创建成ArkTS double数值，并放入returnValue中
101    napi_value returnValue = nullptr;
102    napi_create_double(env, value, &returnValue);
103    return returnValue;
104}
105```
106<!-- @[napi_get_date_value](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIDate/entry/src/main/cpp/napi_init.cpp) -->
107
108接口声明
109
110```ts
111// index.d.ts
112export const getDateValue: (date: Date) => number | undefined;
113```
114<!-- @[napi_get_date_value_api](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIDate/entry/src/main/cpp/types/libentry/Index.d.ts) -->
115
116ArkTS侧示例代码
117
118```ts
119import { hilog } from '@kit.PerformanceAnalysisKit';
120import testNapi from 'libentry.so';
121try {
122  const date = new Date();
123  hilog.info(0x0000, 'testTag', 'Node-API: output the Unix Time Stamp: %{public}d', date.getTime());
124  hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_date_value: %{public}d', testNapi.getDateValue(date));
125} catch (error) {
126  hilog.error(0x0000, 'testTag', 'Test Node-API napi_get_date_value error: %{public}s', error.message);
127}
128```
129<!-- @[ark_napi_get_date_value](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIDate/entry/src/main/ets/pages/Index.ets) -->
130
131### napi_is_date
132
133判断给定ArkTS value是否为ArkTS Date对象。
134
135cpp部分代码
136
137```cpp
138#include "napi/native_api.h"
139
140static napi_value IsDate(napi_env env, napi_callback_info info)
141{
142    // 接受一个入参
143    size_t argc = 1;
144    napi_value args[1] = {nullptr};
145    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
146
147    // 调用napi_is_date接口判断给定入参是否为Date数据
148    bool result = false;
149    napi_status status = napi_is_date(env, args[0], &result);
150    if (status != napi_ok) {
151        napi_throw_error(env, nullptr, "Node-API napi_is_date fail");
152        return nullptr;
153    }
154    // 将结果转成napi_value类型返回
155    napi_value returnValue = nullptr;
156    napi_get_boolean(env, result, &returnValue);
157
158    return returnValue;
159}
160```
161<!-- @[napi_is_date](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIDate/entry/src/main/cpp/napi_init.cpp) -->
162
163接口声明
164
165```ts
166// index.d.ts
167export const isDate: <T>(date: T) => boolean | undefined;
168```
169<!-- @[napi_is_date_api](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIDate/entry/src/main/cpp/types/libentry/Index.d.ts) -->
170
171ArkTS侧示例代码
172
173```ts
174import { hilog } from '@kit.PerformanceAnalysisKit';
175import testNapi from 'libentry.so';
176try {
177  let now: Date = new Date();
178  let date = "123";
179  hilog.info(0x0000, 'testTag', 'Test Node-API napi_is_date: %{public}s', testNapi.isDate(now));
180  hilog.info(0x0000, 'testTag', 'Test Node-API napi_is_date: %{public}s', testNapi.isDate(date));
181} catch (error) {
182  hilog.error(0x0000, 'testTag', 'Test Node-API napi_is_date error: %{public}s', error.message);
183}
184```
185<!-- @[ark_napi_is_date](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIDate/entry/src/main/ets/pages/Index.ets) -->
186
187以上代码如果要在native cpp中打印日志，需在CMakeLists.txt文件中添加以下配置信息（并添加头文件：#include "hilog/log.h"）：
188
189```text
190// CMakeLists.txt
191add_definitions( "-DLOG_DOMAIN=0xd0d0" )
192add_definitions( "-DLOG_TAG=\"testTag\"" )
193target_link_libraries(entry PUBLIC libace_napi.z.so libhilog_ndk.z.so)
194```
195