1# Interface (PreviewOutput) 2<!--Kit: Camera Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @qano--> 5<!--Designer: @leo_ysl--> 6<!--Tester: @xchaosioda--> 7<!--Adviser: @zengyawen--> 8 9> **说明：** 10> 11> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 12 13预览输出类。继承[CameraOutput](arkts-apis-camera-CameraOutput.md)。 14 15## 导入模块 16 17```ts 18import { camera } from '@kit.CameraKit'; 19``` 20 21## on('frameStart') 22 23on(type: 'frameStart', callback: AsyncCallback\<void\>): void 24 25监听预览帧启动，通过注册回调函数获取结果。使用callback异步回调。 26 27> **说明：** 28> 29> 当前注册监听接口，不支持在on监听的回调方法里，调用off注销回调。 30 31**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 32 33**系统能力：** SystemCapability.Multimedia.Camera.Core 34 35**参数：** 36 37| 参数名 | 类型 | 必填 | 说明 | 38| -------- | -------------------- | ---- | --------------------------------------- | 39| type | string | 是 | 监听事件，固定为'frameStart'，previewOutput创建成功可监听。底层第一次开始曝光时触发该事件并返回。 | 40| callback | AsyncCallback\<void\> | 是 | 回调函数，用于获取结果。只要有该事件返回就证明预览开始。 | 41 42**示例：** 43 44```ts 45import { BusinessError } from '@kit.BasicServicesKit'; 46 47function callback(err: BusinessError): void { 48 if (err !== undefined && err.code !== 0) { 49 console.error(`Callback Error, errorCode: ${err.code}`); 50 return; 51 } 52 console.info('Preview frame started'); 53} 54 55function registerPreviewOutputFrameStart(previewOutput: camera.PreviewOutput): void { 56 previewOutput.on('frameStart', callback); 57} 58``` 59 60## off('frameStart') 61 62off(type: 'frameStart', callback?: AsyncCallback\<void\>): void 63 64注销预览帧启动的监听。 65 66**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 67 68**系统能力：** SystemCapability.Multimedia.Camera.Core 69 70**参数：** 71 72| 参数名 | 类型 | 必填 | 说明 | 73| -------- | -------------------- | ---- | --------------------------------------- | 74| type | string | 是 | 监听事件，固定为'frameStart'，previewOutput创建成功可监听。 | 75| callback | AsyncCallback\<void\> | 否 | 回调函数，如果指定参数则取消对应callback（callback对象不可是匿名函数），否则取消所有callback。 | 76 77**示例：** 78 79```ts 80function unregisterPreviewOutputFrameStart(previewOutput: camera.PreviewOutput): void { 81 previewOutput.off('frameStart'); 82} 83``` 84 85## on('frameEnd') 86 87on(type: 'frameEnd', callback: AsyncCallback\<void\>): void 88 89监听预览帧结束，通过注册回调函数获取结果。使用callback异步回调。 90 91> **说明：** 92> 93> 当前注册监听接口，不支持在on监听的回调方法里，调用off注销回调。 94 95**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 96 97**系统能力：** SystemCapability.Multimedia.Camera.Core 98 99**参数：** 100 101| 参数名 | 类型 | 必填 | 说明 | 102| -------- | -------------------- | ---- | ------------------------------------- | 103| type | string | 是 | 监听事件，固定为'frameEnd'，previewOutput创建成功可监听。预览完全结束最后一帧时触发该事件并返回。 | 104| callback | AsyncCallback\<void\> | 是 | 回调函数，用于获取结果。只要有该事件返回就证明预览结束。 | 105 106**示例：** 107 108```ts 109import { BusinessError } from '@kit.BasicServicesKit'; 110 111function callback(err: BusinessError): void { 112 if (err !== undefined && err.code !== 0) { 113 console.error(`Callback Error, errorCode: ${err.code}`); 114 return; 115 } 116 console.info('Preview frame ended'); 117} 118 119function registerPreviewOutputFrameEnd(previewOutput: camera.PreviewOutput): void { 120 previewOutput.on('frameEnd', callback); 121} 122``` 123 124## off('frameEnd') 125 126off(type: 'frameEnd', callback?: AsyncCallback\<void\>): void 127 128注销监听预览帧结束。 129 130**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 131 132**系统能力：** SystemCapability.Multimedia.Camera.Core 133 134**参数：** 135 136| 参数名 | 类型 | 必填 | 说明 | 137| -------- | -------------------- | ---- | ------------------------------------- | 138| type | string | 是 | 监听事件，固定为'frameEnd'，previewOutput创建成功可监听。 | 139| callback | AsyncCallback\<void\> | 否 | 回调函数，如果指定参数则取消对应callback（callback对象不可是匿名函数），否则取消所有callback。 | 140 141**示例：** 142 143```ts 144function unregisterPreviewOutputFrameEnd(previewOutput: camera.PreviewOutput): void { 145 previewOutput.off('frameEnd'); 146} 147``` 148 149## on('error') 150 151on(type: 'error', callback: ErrorCallback): void 152 153监听预览输出的错误事件，通过注册回调函数获取结果。使用callback异步回调。 154 155> **说明：** 156> 157> 当前注册监听接口，不支持在on监听的回调方法里，调用off注销回调。 158 159**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 160 161**系统能力：** SystemCapability.Multimedia.Camera.Core 162 163**参数：** 164 165| 参数名 | 类型 | 必填 | 说明 | 166| -------- | --------------| ---- | ------------------------ | 167| type | string | 是 | 监听事件，固定为'error'，previewOutput创建成功可监听。预览接口使用错误时触发该事件，比如调用[Session.start](arkts-apis-camera-Session.md#start11-1)，[CameraOutput.release](arkts-apis-camera-CameraOutput.md#release-1)等接口发生错误时返回对应错误信息。 | 168| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 回调函数，用于获取错误信息。返回错误码，错误码类型[CameraErrorCode](arkts-apis-camera-e.md#cameraerrorcode)。 | 169 170**示例：** 171 172```ts 173import { BusinessError } from '@kit.BasicServicesKit'; 174 175function callback(previewOutputError: BusinessError): void { 176 console.error(`Preview output error code: ${previewOutputError.code}`); 177} 178 179function registerPreviewOutputError(previewOutput: camera.PreviewOutput): void { 180 previewOutput.on('error', callback) 181} 182``` 183 184## off('error') 185 186off(type: 'error', callback?: ErrorCallback): void 187 188注销监听预览输出的错误事件。 189 190**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 191 192**系统能力：** SystemCapability.Multimedia.Camera.Core 193 194**参数：** 195 196| 参数名 | 类型 | 必填 | 说明 | 197| -------- | --------------| ---- | ------------------------ | 198| type | string | 是 | 监听事件，固定为'error'，previewOutput创建成功可监听。 | 199| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否 | 回调函数，如果指定参数则取消对应callback（callback对象不可是匿名函数），否则取消所有callback。 | 200 201**示例：** 202 203```ts 204function unregisterPreviewOutputError(previewOutput: camera.PreviewOutput): void { 205 previewOutput.off('error'); 206} 207``` 208 209## getSupportedFrameRates<sup>12+</sup> 210 211 getSupportedFrameRates(): Array\<FrameRateRange\> 212 213查询支持的帧率范围。 214 215**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 216 217**系统能力：** SystemCapability.Multimedia.Camera.Core 218 219**返回值：** 220 221| 类型 | 说明 | 222| ------------- | ------------ | 223| Array<[FrameRateRange](arkts-apis-camera-i.md#frameraterange)> | 支持的帧率范围列表 | 224 225**示例：** 226 227```ts 228function getSupportedFrameRates(previewOutput: camera.PreviewOutput): Array<camera.FrameRateRange> { 229 let supportedFrameRatesArray: Array<camera.FrameRateRange> = previewOutput.getSupportedFrameRates(); 230 return supportedFrameRatesArray; 231} 232``` 233 234## setFrameRate<sup>12+</sup> 235 236setFrameRate(minFps: number, maxFps: number): void 237 238设置预览流帧率范围，设置的范围必须在支持的帧率范围内。 239进行设置前，可通过[getSupportedFrameRates](#getsupportedframerates12)接口查询支持的帧率范围。 240 241> **说明：** 242> 仅在[PhotoSession](arkts-apis-camera-PhotoSession.md)或[VideoSession](arkts-apis-camera-VideoSession.md)模式下支持。 243 244**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 245 246**系统能力：** SystemCapability.Multimedia.Camera.Core 247 248**参数：** 249 250| 参数名 | 类型 | 必填 | 说明 | 251| -------- | --------------| ---- | ------------------------ | 252| minFps | number | 是 | 最小帧率（单位：fps），当传入的最大值小于最小值时，传参异常，接口不生效。 | 253| maxFps | number | 是 | 最大帧率（单位：fps），当传入的最小值大于最大值时，传参异常，接口不生效。| 254 255**错误码：** 256 257以下错误码的详细介绍请参见[Camera错误码](errorcode-camera.md)。 258 259| 错误码ID | 错误信息 | 260| --------------- | --------------- | 261| 7400101 | Parameter missing or parameter type incorrect. | 262| 7400110 | Unresolved conflicts with current configurations. | 263 264**示例：** 265 266```ts 267function setFrameRateRange(previewOutput: camera.PreviewOutput, frameRateRange: Array<number>): void { 268 previewOutput.setFrameRate(frameRateRange[0], frameRateRange[1]); 269} 270``` 271 272## getActiveFrameRate<sup>12+</sup> 273 274getActiveFrameRate(): FrameRateRange 275 276获取已设置的帧率范围。 277 278使用[setFrameRate](#setframerate12)接口对预览流设置过帧率后可查询。 279 280**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 281 282**系统能力：** SystemCapability.Multimedia.Camera.Core 283 284**返回值：** 285 286| 类型 | 说明 | 287| ------------- | ------------ | 288| [FrameRateRange](arkts-apis-camera-i.md#frameraterange) | 帧率范围 | 289 290**示例：** 291 292```ts 293function getActiveFrameRate(previewOutput: camera.PreviewOutput): camera.FrameRateRange { 294 let activeFrameRate: camera.FrameRateRange = previewOutput.getActiveFrameRate(); 295 return activeFrameRate; 296} 297``` 298 299## getActiveProfile<sup>12+</sup> 300 301getActiveProfile(): Profile 302 303获取当前生效的配置信息。 304 305**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 306 307**系统能力：** SystemCapability.Multimedia.Camera.Core 308 309**返回值：** 310 311| 类型 | 说明 | 312| ------------- |-----------| 313| [Profile](arkts-apis-camera-i.md#profile) | 当前生效的配置信息 | 314 315**错误码：** 316 317以下错误码的详细介绍请参见[Camera错误码](errorcode-camera.md)。 318 319| 错误码ID | 错误信息 | 320|---------|------------------------------| 321| 7400201 | Camera service fatal error. | 322 323**示例：** 324 325```ts 326import { BusinessError } from '@kit.BasicServicesKit'; 327 328function testGetActiveProfile(previewOutput: camera.PreviewOutput): camera.Profile | undefined { 329 let activeProfile: camera.Profile | undefined = undefined; 330 try { 331 activeProfile = previewOutput.getActiveProfile(); 332 } catch (error) { 333 // 失败返回错误码error.code并处理。 334 let err = error as BusinessError; 335 console.error(`The previewOutput.getActiveProfile call failed. error code: ${err.code}`); 336 } 337 return activeProfile; 338} 339``` 340 341## getPreviewRotation<sup>12+</sup> 342 343getPreviewRotation(displayRotation: number): ImageRotation 344 345获取预览旋转角度。 346 347- 设备自然方向：设备默认使用方向，手机为竖屏（充电口向下）。 348- 相机镜头角度：值等于相机图像顺时针旋转到设备自然方向的角度，手机后置相机传感器是横屏安装的，所以需要顺时针旋转90度到设备自然方向。 349- 屏幕显示方向：需要屏幕显示的图片左上角为第一个像素点为坐标原点。锁屏时与自然方向一致。 350 351**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 352 353**系统能力：** SystemCapability.Multimedia.Camera.Core 354 355**参数：** 356 357| 参数名 | 类型 | 必填 | 说明 | 358| -------- | --------------| ---- | ------------------------ | 359| displayRotation | number | 是 | 显示设备的屏幕旋转角度，通过[display.getDefaultDisplaySync](../apis-arkui/js-apis-display.md#displaygetdefaultdisplaysync9)获得。 | 360 361**返回值：** 362 363| 类型 | 说明 | 364| ------------- |-----------| 365| [ImageRotation](arkts-apis-camera-e.md#imagerotation) | 获取预览旋转角度。 | 366 367**错误码：** 368 369以下错误码的详细介绍请参见[Camera错误码](errorcode-camera.md)。 370 371| 错误码ID | 错误信息 | 372|---------|------------------------------| 373| 7400101 | Parameter missing or parameter type incorrect. | 374| 7400201 | Camera service fatal error. | 375 376**示例：** 377 378```ts 379import { BusinessError } from '@kit.BasicServicesKit'; 380 381function testGetPreviewRotation(previewOutput: camera.PreviewOutput, imageRotation : camera.ImageRotation): camera.ImageRotation { 382 let previewRotation: camera.ImageRotation = camera.ImageRotation.ROTATION_0; 383 try { 384 previewRotation = previewOutput.getPreviewRotation(imageRotation); 385 console.log(`Preview rotation is: ${previewRotation}`); 386 } catch (error) { 387 // 失败返回错误码error.code并处理。 388 let err = error as BusinessError; 389 console.error(`The previewOutput.getPreviewRotation call failed. error code: ${err.code}`); 390 } 391 return previewRotation; 392} 393``` 394 395## setPreviewRotation<sup>12+</sup> 396 397setPreviewRotation(previewRotation: ImageRotation, isDisplayLocked?: boolean): void 398 399设置预览旋转角度。 400 401**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 402 403**系统能力：** SystemCapability.Multimedia.Camera.Core 404 405**参数：** 406 407| 参数名 | 类型 | 必填 | 说明 | 408| -------- | --------------| ---- | ------------------------ | 409| previewRotation | [ImageRotation](arkts-apis-camera-e.md#imagerotation) | 是 | 预览旋转角度 | 410| isDisplayLocked | boolean | 否 | Surface在屏幕旋转时是否锁定方向，未设置时默认取值为false，即不锁定方向。true表示锁定方向，false表示不锁定方向。详情请参考[SurfaceRotationOptions](../../reference/apis-arkui/arkui-ts/ts-basic-components-xcomponent.md#surfacerotationoptions12对象说明)。 | 411 412**错误码：** 413 414以下错误码的详细介绍请参见[Camera错误码](errorcode-camera.md)。 415 416| 错误码ID | 错误信息 | 417|---------|------------------------------| 418| 7400101 | Parameter missing or parameter type incorrect. | 419| 7400201 | Camera service fatal error. | 420 421**示例：** 422 423```ts 424import { BusinessError } from '@kit.BasicServicesKit'; 425 426function testSetPreviewRotation(previewOutput: camera.PreviewOutput, previewRotation : camera.ImageRotation, isDisplayLocked: boolean): void { 427 try { 428 previewOutput.setPreviewRotation(previewRotation, isDisplayLocked); 429 } catch (error) { 430 // 失败返回错误码error.code并处理。 431 let err = error as BusinessError; 432 console.error(`The previewOutput.setPreviewRotation call failed. error code: ${err.code}`); 433 } 434 return; 435} 436``` 437 438 439## start<sup>(deprecated)</sup> 440 441start(callback: AsyncCallback\<void\>): void 442 443开始输出预览流，通过注册回调函数获取结果。使用callback异步回调。 444 445> **说明：** 446>从 API version 10开始支持，从API version 11开始废弃。建议使用[Session.start](arkts-apis-camera-Session.md#start11)替代。 447 448**系统能力：** SystemCapability.Multimedia.Camera.Core 449 450**参数：** 451 452| 参数名 | 类型 | 必填 | 说明 | 453| -------- | -------------------- | ---- | -------------------- | 454| callback | AsyncCallback\<void\> | 是 | 回调函数。当开始输出预览流成功，err为undefined，否则为错误对象。错误码类型[CameraErrorCode](arkts-apis-camera-e.md#cameraerrorcode)。 | 455 456**错误码：** 457 458以下错误码的详细介绍请参见[Camera错误码](errorcode-camera.md)。 459 460| 错误码ID | 错误信息 | 461| --------------- | --------------- | 462| 7400103 | Session not config. | 463 464**示例：** 465 466```ts 467import { BusinessError } from '@kit.BasicServicesKit'; 468 469function startPreviewOutput(previewOutput: camera.PreviewOutput): void { 470 previewOutput.start((err: BusinessError) => { 471 if (err) { 472 console.error(`Failed to start the preview output, error code: ${err.code}.`); 473 return; 474 } 475 console.info('Callback returned with preview output started.'); 476 }); 477} 478``` 479 480## start<sup>(deprecated)</sup> 481 482start(): Promise\<void\> 483 484开始输出预览流。使用Promise异步回调。 485 486> **说明：** 487>从 API version 10开始支持，从API version 11开始废弃。建议使用[Session.start](arkts-apis-camera-Session.md#start11-1)替代。 488 489**系统能力：** SystemCapability.Multimedia.Camera.Core 490 491**返回值：** 492 493| 类型 | 说明 | 494| -------------- |-------------------| 495| Promise\<void\> | Promise对象，无返回结果。 | 496 497**错误码：** 498 499以下错误码的详细介绍请参见[Camera错误码](errorcode-camera.md)。 500 501| 错误码ID | 错误信息 | 502| --------------- | --------------- | 503| 7400103 | Session not config. | 504 505**示例：** 506 507```ts 508import { BusinessError } from '@kit.BasicServicesKit'; 509 510function startPreviewOutput(previewOutput: camera.PreviewOutput): void { 511 previewOutput.start().then(() => { 512 console.info('Promise returned with preview output started.'); 513 }).catch((error: BusinessError) => { 514 console.error(`Failed to preview output start, error code: ${error.code}.`); 515 }); 516} 517``` 518 519## stop<sup>(deprecated)</sup> 520 521stop(callback: AsyncCallback\<void\>): void 522 523停止输出预览流，通过注册回调函数获取结果。使用callback异步回调。 524 525> **说明：** 526>从 API version 10开始支持，从API version 11开始废弃。建议使用[Session.stop](arkts-apis-camera-Session.md#stop11)替代。 527 528**系统能力：** SystemCapability.Multimedia.Camera.Core 529 530**参数：** 531 532| 参数名 | 类型 | 必填 | 说明 | 533| -------- | -------------------- | ---- | -------------------- | 534| callback | AsyncCallback\<void\> | 是 | 回调函数。当停止输出预览流成功，err为undefined，否则为错误对象。 | 535 536**示例：** 537 538```ts 539import { BusinessError } from '@kit.BasicServicesKit'; 540 541function stopPreviewOutput(previewOutput: camera.PreviewOutput): void { 542 previewOutput.stop((err: BusinessError) => { 543 if (err) { 544 console.error(`Failed to stop the preview output, error code: ${err.code}.`); 545 return; 546 } 547 console.info('Returned with preview output stopped.'); 548 }) 549} 550``` 551 552## stop<sup>(deprecated)</sup> 553 554stop(): Promise\<void\> 555 556停止输出预览流。使用Promise异步回调。 557 558> **说明：** 559>从 API version 10开始支持，从API version 11开始废弃。建议使用[Session.stop](arkts-apis-camera-Session.md#stop11-1)替代。 560 561**系统能力：** SystemCapability.Multimedia.Camera.Core 562 563**返回值：** 564 565| 类型 | 说明 | 566| -------------- | ------------------------ | 567| Promise\<void\> | Promise对象，无返回结果。 | 568 569**示例：** 570 571```ts 572import { BusinessError } from '@kit.BasicServicesKit'; 573 574function stopPreviewOutput(previewOutput: camera.PreviewOutput): void { 575 previewOutput.stop().then(() => { 576 console.info('Callback returned with preview output stopped.'); 577 }).catch((error: BusinessError) => { 578 console.error(`Failed to preview output stop, error code: ${error.code}.`); 579 }); 580} 581``` 582 583