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