1# @ohos.graphics.displaySync (可变帧率) 2<!--Kit: ArkGraphics 2D--> 3<!--Subsystem: Graphics--> 4<!--Owner: @hudi33--> 5<!--Designer: @hudi33--> 6<!--Tester: @zhaoxiaoguang2--> 7<!--Adviser: @ge-yafang--> 8 9可变帧率支持让开发者以指定帧率来运行UI业务，一般用于开发者自绘制UI，并且对于帧率有特定诉求的场景。 10 11> **说明：** 12> 13> 本模块首批接口和数据定义从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14 15 16## 导入模块 17 18```ts 19import { displaySync } from '@kit.ArkGraphics2D'; 20``` 21 22## displaySync.create 23create(): DisplaySync 24 25创建DisplaySync对象，通过此对象设置UI自绘制内容帧率。 26 27**系统能力：** SystemCapability.ArkUI.ArkUI.Full 28 29**返回值：** 30 31| 类型 | 说明 | 32| ------------------ | ------------------------ | 33| [DisplaySync](#displaysync) | 返回当前创建的DisplaySync对象实例。 | 34 35**示例：** 36 37```ts 38let backDisplaySync: displaySync.DisplaySync = displaySync.create(); 39``` 40## IntervalInfo 41 42开发者可以从订阅函数中获取帧绘制的时间戳信息，包含当前帧到达的时间timestamp和下一帧预期到达的时间targetTimestamp。 43 44**系统能力：** SystemCapability.ArkUI.ArkUI.Full 45 46| 名称 | 类型 | 只读 | 可选 | 说明 | 47| ---------------- | ----------------------------------------- | ---- | ---- | ------------------------------------------ | 48| timestamp | number | 否 | 否 | 当前帧到达的时间（单位：纳秒）。 | 49| targetTimestamp | number| 否 | 否 | 下一帧预期到达的时间（单位：纳秒）。 | 50 51## DisplaySync 52 53 帧率和回调函数设置实例。用于帧率设置和回调函数的注册，以及启动和停止回调函数的调用。 54 55 下列API示例中都需先使用[displaySync.create()](#displaysynccreate)方法获取到DisplaySync实例，再通过此实例调用对应方法。 56 57### setExpectedFrameRateRange 58 59setExpectedFrameRateRange(rateRange: ExpectedFrameRateRange) : void 60 61设置期望的帧率范围。 62 63**系统能力：** SystemCapability.ArkUI.ArkUI.Full 64 65**参数：** 66 67| 参数名 | 类型 | 必填 | 说明 | 68| --------------- | ------------------------------------------ | ---- | -----------------------------| 69| rateRange | [ExpectedFrameRateRange](../apis-arkui/arkui-ts/ts-explicit-animation.md#expectedframeraterange11)| 是 | 设置DisplaySync期望的帧率。| 70 71**错误码**： 72 73以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 74 75| 错误码ID | 错误信息 | 76| ------- | -------- | 77| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2.Incorrect parameters types. 3. Parameter verification failed. or check ExpectedFrameRateRange if valid.| 78 79**示例：** 80 81```ts 82let range : ExpectedFrameRateRange = { 83 expected: 10, 84 min:0, 85 max:120 86}; 87 88// 设置DisplaySync期望的帧率 89backDisplaySync?.setExpectedFrameRateRange(range) 90``` 91 92### on('frame') 93 94on(type: 'frame', callback: Callback\<IntervalInfo\>): void 95 96订阅每一帧的变化。 97 98**系统能力：** SystemCapability.ArkUI.ArkUI.Full 99 100**参数：** 101 102| 参数名 | 类型 | 必填 | 说明 | 103| --------------- | ------------------------------------------ | ---- | -----------------------------| 104| type | 'frame'| 是 | 设置注册回调的类型（只能是'frame'类型）。| 105| callback | Callback<[IntervalInfo](#intervalinfo)>| 是 | 订阅函数。| 106 107 108**示例：** 109 110```ts 111let callback = (frameInfo: displaySync.IntervalInfo) => { 112 console.info("DisplaySync", 'TimeStamp:' + frameInfo.timestamp + ' TargetTimeStamp: ' + frameInfo.targetTimestamp); 113} 114 115// 注册订阅函数 116backDisplaySync?.on("frame", callback) 117``` 118 119### off('frame') 120 121off(type: 'frame', callback\?: Callback\<IntervalInfo\>): void 122 123取消订阅每一帧的变化。 124 125**系统能力：** SystemCapability.ArkUI.ArkUI.Full 126 127**参数：** 128 129| 参数名 | 类型 | 必填 | 说明 | 130| --------------- | ------------------------------------------ | ---- | -----------------------------| 131| type | 'frame'| 是 | 设置注册回调的类型（只能是'frame'类型）。| 132| callback | Callback<[IntervalInfo](#intervalinfo)>| 否 | 订阅函数，参数不填时，默认取消全部订阅函数。| 133 134 135**示例：** 136 137```ts 138let callback = (frameInfo: displaySync.IntervalInfo) => { 139 console.info("DisplaySync", 'TimeStamp:' + frameInfo.timestamp + ' TargetTimeStamp: ' + frameInfo.targetTimestamp); 140} 141 142backDisplaySync?.on("frame", callback) 143 144// 取消订阅函数 145backDisplaySync?.off("frame", callback) 146``` 147 148### start 149 150start(): void 151 152开始每帧回调。 153 154**系统能力：** SystemCapability.ArkUI.ArkUI.Full 155 156**示例：** 157 158```ts 159let range : ExpectedFrameRateRange = { 160 expected: 10, 161 min:0, 162 max:120 163}; 164 165backDisplaySync?.setExpectedFrameRateRange(range) 166 167let callback = (frameInfo: displaySync.IntervalInfo) => { 168 console.info("DisplaySync", 'TimeStamp:' + frameInfo.timestamp + ' TargetTimeStamp: ' + frameInfo.targetTimestamp); 169} 170 171backDisplaySync?.on("frame", callback) 172 173// 开始每帧回调 174backDisplaySync?.start() 175``` 176 177> **说明：** 178> 179> start接口是将DisplaySync关联到UI实例和窗口，若在非UI页面中或者一些异步回调中进行start操作，可能无法跟踪到当前UI的上下文，导致start接口失败，会进一步导致订阅函数无法执行。 180> 因此可以使用UIContext的[runScopedTask](../apis-arkui/arkts-apis-uicontext-uicontext.md#runscopedtask)接口来指定start函数执行的UI上下文。 181 182**示例：** 183 184```ts 185import { displaySync } from '@kit.ArkGraphics2D'; 186import { UIContext } from '@kit.ArkUI'; 187 188// xxx.ets 189@Entry 190@Component 191struct Index { 192 // 创建DisplaySync实例 193 backDisplaySync: displaySync.DisplaySync = displaySync.create(); 194 195 aboutToAppear() { 196 // 获取UIContext实例 197 let uiContext: UIContext = this.getUIContext(); 198 // 在当前UI上下文中执行DisplaySync的start接口 199 uiContext?.runScopedTask(() => { 200 this.backDisplaySync?.start(); 201 }) 202 } 203 204 build() { 205 // ... 206 } 207} 208 209``` 210 211### stop 212 213stop(): void 214 215停止每帧回调。 216 217 218**系统能力：** SystemCapability.ArkUI.ArkUI.Full 219 220 221**示例：** 222 223```ts 224let range : ExpectedFrameRateRange = { 225 expected: 10, 226 min:0, 227 max:120 228}; 229 230backDisplaySync?.setExpectedFrameRateRange(range) 231 232let callback = (frameInfo: displaySync.IntervalInfo) => { 233 console.info("DisplaySync", 'TimeStamp:' + frameInfo.timestamp + ' TargetTimeStamp: ' + frameInfo.targetTimestamp); 234} 235 236backDisplaySync?.on("frame", callback) 237 238backDisplaySync?.start() 239 240// ... 241 242// 停止每帧回调 243backDisplaySync?.stop() 244```