• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Timer (定时器)
2
3本模块提供基础的定时器能力，支持按照指定的时间执行对应函数。
4
5> **说明：**
6>
7> 本模块首批接口从API version 3开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> 在UI界面中使用定时器时，定时器的触发机制会受UI底层原理管控。如果UI界面退到后台，定时器会被冻结。
10
11## setTimeout
12
13setTimeout(handler: Function | string, delay?: number, ...arguments: any[]): number
14
15设置一个定时器，该定时器在定时器到期后执行一个函数。
16该定时器在回调被执行后自动删除，或使用clearTimeout接口手动删除。
17
18**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
19
20**系统能力：** SystemCapability.ArkUI.ArkUI.Full
21
22**参数：**
23
24| 参数名 | 类型 | 必填 | 说明 |
25| -------- | -------- | -------- | -------- |
26| handler | Function \| string | 是 | 类型为Function表示定时器到期后执行函数；<br>类型为string则通过Error方式打印string中内容，不进行其他处理。 |
27| delay | number | 否 | 延迟的毫秒数，函数的调用会在该延迟之后发生。建议传入整数，若传入小数，会被向下取整。<br>如果省略该参数，delay取默认值0。<br>**注意**：<br>1. 无论是哪种情况，实际延迟可能会比预期长一些。<br>2. 如果值小于1，会被默认取0。<br>3. delay值受系统限制，超出2^32 - 1时会溢出，delay值为0。|
28| ...arguments | any[] | 否 | 附加参数，仅当handler类型为Function时生效，作为参数传递给handler。<br/>arguments参数数量少于handler函数参数数量时，未被arguments覆盖的参数会被设为undefined。<br/>arguments参数数量多于handler函数参数数量时，多余的arguments参数会被忽略，但可通过handler函数内部的arguments对象访问。|
29
30**返回值：**
31
32| 类型 | 说明 |
33| -------- | -------- |
34| number | 该定时器的ID，定时器ID为进程共享，是从0开始顺序增加的整数，无重复值。 |
35
36**示例1**：不带参数。
37
38  ```ts
39  setTimeout(() => {
40    console.info('delay 1s');
41  }, 1000);
42  ```
43
44**示例2**：带参数传递给函数(handle为function时参数与arguments参数个数一致)。
45
46  ```ts
47  function myFunction(param1: string, param2: string) {
48    console.info(param1, param2);
49  }
50  setTimeout(myFunction, 1000, 'Hello', 'World');
51  ```
52
53**示例3**：带参数传递给函数(handle为function时参数比arguments参数个数少)。
54
55  ```ts
56  function myFunction(a: string, b: string) {
57    console.info(a);
58    // Output: hello
59    console.info(b);
60    // Output: world
61    console.info(JSON.stringify(arguments));
62    // Output: {"0":"hello","1":"world","2":"c++","3":"js"}
63  }
64  setTimeout(myFunction, 1000, 'hello', 'world', 'C++', 'js');
65  ```
66**示例4**：带参数传递给函数(handle为function时参数比arguments参数个数多)。
67
68  ```ts
69  function myFunction(a: string, b: string) {
70    console.info(a);
71    // Output: hello
72    console.info(b);
73    // Output: undefined
74    console.info(JSON.stringify(arguments));
75    // Output: {"0":"hello"}
76  }
77  setTimeout(myFunction, 1000, 'hello');
78  ```
79
80## clearTimeout
81
82clearTimeout(timeoutID?: number): void
83
84可取消通过调用setTimeout()建立的定时器。
85
86定时器对象保存在创建它的线程内，删除定时器时需要在该线程中进行。
87
88**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
89
90**系统能力：** SystemCapability.ArkUI.ArkUI.Full
91
92**参数：**
93
94| 参数名 | 类型 | 必填 | 说明 |
95| -------- | -------- | -------- | -------- |
96| timeoutID | number | 否 | 要取消定时器的ID，需要与调用setTimeout设置定时器的返回值一致。如果省略该参数或指定的定时器ID不存在时，不会取消任何定时任务。|
97
98**示例：**
99
100  ```js
101  let timeoutID = setTimeout(() => {
102    console.log('do after 1s delay.');
103  }, 1000);
104  clearTimeout(timeoutID);
105  ```
106
107
108## setInterval
109
110setInterval(handler: Function | string, delay: number, ...arguments: any[]): number
111
112重复调用一个函数，在每次调用之间具有固定的时间延迟。
113删除该定时器需手动调用clearInterval接口。
114
115**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
116
117**系统能力：** SystemCapability.ArkUI.ArkUI.Full
118
119**参数：**
120
121| 参数名 | 类型 | 必填 | 说明 |
122| -------- | -------- | -------- | -------- |
123| handler | Function \| string | 是 | 类型为Function表示定时器到期后执行函数；<br>类型为string则通过Error方式打印string中内容，不进行其他处理。 |
124| delay | number | 否 | 延迟的毫秒数，函数的调用会在该延迟之后发生。建议传入整数，若传入小数，会被向下取整。<br>如果省略该参数，delay取默认值0。<br>**注意**：<br>1. 无论是哪种情况，实际延迟可能会比预期长一些。<br>2. 如果值小于1，将被默认设置为0。<br>3. delay值受系统限制，超出2^32 - 1时会溢出，delay值为0。|
125| ...arguments | any[] | 否 | 附加参数，仅当handler类型为Function时生效，作为参数传递给handler。<br/>arguments参数数量少于handler函数参数数量时，未被arguments覆盖的参数会被设为undefined。<br/>arguments参数数量多于handler函数参数数量时，多余的arguments参数会被忽略，但可通过handler函数内部的arguments对象访问。|
126
127**返回值：**
128
129| 类型 | 说明 |
130| -------- | -------- |
131| number | 该定时器的ID，定时器ID为进程共享，是从0开始顺序增加的整数，无重复值。 |
132
133**示例：**
134
135  ```js
136  setInterval(() => {
137    console.log('do every 1s.');
138  }, 1000);
139  ```
140
141
142## clearInterval
143
144clearInterval(intervalID?: number): void
145
146可取消通过setInterval()设置的重复定时任务。
147
148定时器对象保存在创建它的线程内，删除定时器时需要在该线程中进行。
149
150**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
151
152**系统能力：** SystemCapability.ArkUI.ArkUI.Full
153
154**参数：**
155
156| 参数名 | 类型 | 必填 | 说明 |
157| -------- | -------- | -------- | -------- |
158| intervalID | number | 否 | 要取消的重复定时器的ID，需要与调用setInterval设置重复定时器的返回值一致。如果省略该参数或指定的重复定时器ID不存在时，不会取消任何定时任务。|
159
160**示例：**
161
162  ```js
163  let intervalID = setInterval(() => {
164    console.log('do every 1s.');
165  }, 1000);
166  clearInterval(intervalID);
167  ```
168
169## 其他说明
170### 超时延迟
171如果页面正忙于其他任务，超时可能比预期晚。setTimeout的函数或代码片段在下一个时间周期执行。例如：
172  ```ts
173  function foo() {
174    console.info('OH test foo is called')
175  }
176  setTimeout(foo, 0);
177  console.info('After OH test setTimeout')
178
179  // output
180  After OH test setTimeout
181  OH test foo is called
182  ```
183这是因为，虽然setTimeout设置了0ms的延迟，但任务不会立即执行，而是被放入队列中，等待下一次事件循环。当前代码执行完毕后，队列中的函数才会被执行，因此最终的执行顺序可能与预期不一致。
184
185### 最大延迟值
186定时器内部使用32位带符号整数存储延时。因此，当延时超过2147483647毫秒（约24.8天）时，定时器会溢出并立即执行。
187
188### 定时器冻结
189定时器的触发受底层任务调度。当前应用被切换到后台后，定时器到期不会触发。应用被重新拉起到前台后，到期定时器会按序触发。可以使用trace查看进程是否还存在调度，如果没有调度，定时器会被冻结。
190### 定时器ID
191setTimeout()和setInterval()使用同一个ID池，这意味着技术上可以混用clearTimeout()和clearInterval()。然而，为了代码的清晰性，建议不要混用它们。