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