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 | 是 | 定时器到期后执行函数。类型为string则打印Error信息，不进行其他处理。 |
27| delay | number | 否 | 延迟的毫秒数，函数的调用会在该延迟之后发生。建议整数，若传入小数，会被向下取整。<br>如果省略该参数，delay取默认值0，意味着“马上”执行，更准确的说，在下一个事件循环执行。<br>注意：<br>1. 无论是哪种情况，实际延迟可能会比预期长一些。<br>2. 如果值小于1，会被默认取0。 |
28| ...arguments | any[] | 否 | 附加参数，一旦定时器到期，它们会作为参数传递给handler。 |
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：带参数传递给函数**
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## clearTimeout
54
55clearTimeout(timeoutID?: number): void
56
57可取消通过调用setTimeout()建立的定时器。
58
59定时器对象保存在创建它的线程内，删除定时器需要在创建该定时器的线程删除。
60
61**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
62
63**系统能力：** SystemCapability.ArkUI.ArkUI.Full
64
65**参数：**
66
67| 参数名 | 类型 | 必填 | 说明 |
68| -------- | -------- | -------- | -------- |
69| timeoutID | number | 否 | 要取消定时器的ID，&nbsp;是由setTimeout()返回的。如果省略该参数，则不取消任何定时任务，无任何处理。|
70
71**示例：**
72
73  ```js
74  let timeoutID = setTimeout(() => {
75    console.log('do after 1s delay.');
76  }, 1000);
77  clearTimeout(timeoutID);
78  ```
79
80
81## setInterval
82
83setInterval(handler: Function | string, delay: number, ...arguments: any[]): number
84
85重复调用一个函数，在每次调用之间具有固定的时间延迟。
86删除该定时器需手动调用clearInterval接口。
87
88**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
89
90**系统能力：** SystemCapability.ArkUI.ArkUI.Full
91
92**参数：**
93
94| 参数名 | 类型 | 必填 | 说明 |
95| -------- | -------- | -------- | -------- |
96| handler | Function \| string | 是 | 要重复调用的函数。类型为string则打印Error信息，不进行其他处理。|
97| delay | number | 是 | 延迟的毫秒数，函数的调用会在该延迟之后发生。 |
98| ...arguments | any[] | 否 | 附加参数，一旦定时器到期，他们会作为参数传递给handler。 |
99
100**返回值：**
101
102| 类型 | 说明 |
103| -------- | -------- |
104| number | 该定时器的ID，定时器ID为进程共享，是从0开始顺序增加的整数，无重复值。 |
105
106**示例：**
107
108  ```js
109  setInterval(() => {
110    console.log('do every 1s.');
111  }, 1000);
112  ```
113
114
115## clearInterval
116
117clearInterval(intervalID?: number): void
118
119可取消通过setInterval()设置的重复定时任务。
120
121定时器对象保存在创建它的线程内，删除定时器需要在创建该定时器的线程删除。
122
123**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
124
125**系统能力：** SystemCapability.ArkUI.ArkUI.Full
126
127**参数：**
128
129| 参数名 | 类型 | 必填 | 说明 |
130| -------- | -------- | -------- | -------- |
131| intervalID | number | 否 | 要取消的重复定时器的ID，是由&nbsp;setInterval()&nbsp;返回的。如果省略该参数，则不取消任何定时任务，无任何处理。|
132
133**示例：**
134
135  ```js
136  let intervalID = setInterval(() => {
137    console.log('do every 1s.');
138  }, 1000);
139  clearInterval(intervalID);
140  ```
141
142## 其他说明
143### 超时延迟
144如果页面正忙于其他任务，超时也可能比预期的晚。setTimeout的函数或代码片段是在下一个时间周期执行的。例如：
145  ```ts
146  function foo() {
147    console.info('OH test foo is called')
148  }
149  setTimeout(foo, 0);
150  console.info('After OH test setTimeout')
151
152  // output
153  After OH test setTimeout
154  OH test foo is called
155  ```
156这是因为，虽然setTimeout设置了0ms的延迟，但任务不是立即执行，而是会被放入队列中，等待下一次事件循环执行。当前正在执行的代码必须先完成，队列中的函数才会被执行，因此最终的执行顺序可能和预期不一致。
157
158### 最大延迟值
159timer内部以32位带符号整数存储延时，这就会导致如果一个延时大于2147483647毫秒（大约24.8天）时就会溢出，导致定时器将会被立即执行。
160
161### 定时器冻结
162定时器的触发受底层任务调度。当前应用被切换到后台后，定时器到期也不会触发。应用被重新拉起到前台后，到期定时器会按序触发。可使用trace查看进程是否还存在调度，如果没有调度，则定时器被冻结。
163
164### 定时器ID
165setTimeout()和setInterval()使用共享的ID池，意味着在技术上可以混用clearTimeout()和clearInterval()。但出于代码清晰性考虑，我们应该避免混用它们。