1# Interface (PhotoSession) 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> - 本Interface首批接口从API version 11开始支持。 13 14PhotoSession 继承自 [Session](arkts-apis-camera-Session.md)、[Flash](arkts-apis-camera-Flash.md)、[AutoExposure](arkts-apis-camera-AutoExposure.md)、[WhiteBalance](arkts-apis-camera-WhiteBalance.md)、[Focus](arkts-apis-camera-Focus.md)、[Zoom](arkts-apis-camera-Zoom.md)、[ColorManagement](arkts-apis-camera-ColorManagement.md)、[AutoDeviceSwitch](arkts-apis-camera-AutoDeviceSwitch.md)、[Macro](arkts-apis-camera-Macro.md)。 15 16普通拍照模式会话类，提供了对闪光灯、曝光、白平衡、对焦、变焦、色彩空间及微距的操作。 17 18> **说明：** 19> 20> 默认的拍照模式，用于拍摄标准照片。支持多种照片格式和分辨率，适合大多数日常拍摄场景。 21 22## 导入模块 23 24```ts 25import { camera } from '@kit.CameraKit'; 26``` 27 28## canPreconfig<sup>12+</sup> 29 30canPreconfig(preconfigType: PreconfigType, preconfigRatio?: PreconfigRatio): boolean 31 32查询当前Session是否支持指定的预配置类型。 33 34**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 35 36**系统能力：** SystemCapability.Multimedia.Camera.Core 37 38**参数：** 39 40| 参数名 | 类型 | 必填 | 说明 | 41|----------------|-------------------------------------|-----|-----------------| 42| preconfigType | [PreconfigType](arkts-apis-camera-e.md#preconfigtype12) | 是 | 指定配置预期分辨率。 | 43| preconfigRatio | [PreconfigRatio](arkts-apis-camera-e.md#preconfigratio12) | 否 | 可选画幅比例，默认为4:3。 | 44 45**返回值：** 46 47| 类型 | 说明 | 48|---------|-----------------------------------------| 49| boolean | true: 支持指定预配值类型。<br/>false: 不支持指定预配值类型。 | 50 51**错误码：** 52 53以下错误码的详细介绍请参见[Camera错误码](errorcode-camera.md)。 54 55| 错误码ID | 错误信息 | 56|---------|-----------------------------| 57| 7400201 | Camera service fatal error. | 58 59**示例：** 60 61```ts 62import { BusinessError } from '@kit.BasicServicesKit'; 63 64function testCanPreconfig(photoSession: camera.PhotoSession, preconfigType: camera.PreconfigType, 65 preconfigRatio: camera.PreconfigRatio): void { 66 try { 67 let result = photoSession.canPreconfig(preconfigType, preconfigRatio); 68 console.info(`canPreconfig ${preconfigType} ${preconfigRatio} result is : ${result}`); 69 } catch (error) { 70 let err = error as BusinessError; 71 console.error(`The canPreconfig call failed. error code: ${err.code}`); 72 } 73} 74``` 75 76## preconfig<sup>12+</sup> 77 78preconfig(preconfigType: PreconfigType, preconfigRatio?: PreconfigRatio): void 79 80对当前Session进行预配置。 81 82**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 83 84**系统能力：** SystemCapability.Multimedia.Camera.Core 85 86**参数：** 87 88| 参数名 | 类型 | 必填 | 说明 | 89|----------------|-------------------------------------|-----|-----------------| 90| preconfigType | [PreconfigType](arkts-apis-camera-e.md#preconfigtype12) | 是 | 指定配置预期分辨率。 | 91| preconfigRatio | [PreconfigRatio](arkts-apis-camera-e.md#preconfigratio12) | 否 | 可选画幅比例，默认为4:3。 | 92 93**错误码：** 94 95以下错误码的详细介绍请参见[Camera错误码](errorcode-camera.md)。 96 97| 错误码ID | 错误信息 | 98|---------|-----------------------------| 99| 7400201 | Camera service fatal error. | 100 101**示例：** 102 103```ts 104import { BusinessError } from '@kit.BasicServicesKit'; 105 106function testPreconfig(photoSession: camera.PhotoSession, preconfigType: camera.PreconfigType, 107 preconfigRatio: camera.PreconfigRatio): void { 108 try { 109 photoSession.preconfig(preconfigType, preconfigRatio); 110 console.info(`preconfig success preconfigType: ${preconfigType}, preconfigRatio: ${preconfigRatio}`); 111 } catch (error) { 112 let err = error as BusinessError; 113 console.error(`The preconfig call failed. error code: ${err.code}`); 114 } 115} 116``` 117 118## on('error')<sup>11+</sup> 119 120on(type: 'error', callback: ErrorCallback): void 121 122监听普通拍照会话的错误事件，通过注册回调函数获取结果。使用callback异步回调。 123 124> **说明：** 125> 126> 当前注册监听接口，不支持在on监听的回调方法里，调用off注销回调。 127 128**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 129 130**系统能力：** SystemCapability.Multimedia.Camera.Core 131 132**参数：** 133 134| 参数名 | 类型 | 必填 | 说明 | 135| -------- | ----------------------------------------------------------- | ---- | ------------------------------ | 136| type | string | 是 | 监听事件，固定为'error'，session创建成功之后可监听该接口。session调用相关接口出现错误时会触发该事件，比如调用[beginConfig](arkts-apis-camera-Session.md#beginconfig11)，[commitConfig](arkts-apis-camera-Session.md#commitconfig11)，[addInput](arkts-apis-camera-Session.md#addinput11)等接口发生错误时返回错误信息。 | 137| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback)| 是 | 回调函数，用于获取错误信息。返回错误码，错误码类型[CameraErrorCode](arkts-apis-camera-e.md#cameraerrorcode)。 | 138 139**示例：** 140 141```ts 142import { BusinessError } from '@kit.BasicServicesKit'; 143 144function callback(err: BusinessError): void { 145 console.error(`Photo session error code: ${err.code}`); 146} 147 148function registerSessionError(photoSession: camera.PhotoSession): void { 149 photoSession.on('error', callback); 150} 151``` 152 153## off('error')<sup>11+</sup> 154 155off(type: 'error', callback?: ErrorCallback): void 156 157注销监听普通拍照会话的错误事件，通过注册回调函数获取结果。 158 159**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 160 161**系统能力：** SystemCapability.Multimedia.Camera.Core 162 163**参数：** 164 165| 参数名 | 类型 | 必填 | 说明 | 166| -------- | -------------------------------- | ---- | ------------------------------ | 167| type | string | 是 | 监听事件，固定为'error'，session创建成功之后可监听该接口。 | 168| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback)| 否 | 回调函数，如果指定参数则取消对应callback（callback对象不可是匿名函数），否则取消所有callback。 | 169 170**示例：** 171 172```ts 173function unregisterSessionError(photoSession: camera.PhotoSession): void { 174 photoSession.off('error'); 175} 176``` 177 178## on('focusStateChange')<sup>11+</sup> 179 180on(type: 'focusStateChange', callback: AsyncCallback\<FocusState\>): void 181 182监听相机聚焦的状态变化，通过注册回调函数获取结果。使用callback异步回调。 183 184> **说明：** 185> 186> 当前注册监听接口，不支持在on监听的回调方法里，调用off注销回调。 187 188**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 189 190**系统能力：** SystemCapability.Multimedia.Camera.Core 191 192**参数：** 193 194| 参数名 | 类型 | 必填 | 说明 | 195| -------- | ---------------- | ---- | ------------------------ | 196| type | string | 是 | 监听事件，固定为'focusStateChange'，session创建成功可监听。仅当自动对焦模式时，且相机对焦状态发生改变时可触发该事件。 | 197| callback | AsyncCallback\<[FocusState](arkts-apis-camera-e.md#focusstate)\> | 是 | 回调函数，用于获取当前对焦状态。 | 198 199**示例：** 200 201```ts 202import { BusinessError } from '@kit.BasicServicesKit'; 203 204function callback(err: BusinessError, focusState: camera.FocusState): void { 205 if (err !== undefined && err.code !== 0) { 206 console.error(`Callback Error, errorCode: ${err.code}`); 207 return; 208 } 209 console.info(`Focus state: ${focusState}`); 210} 211 212function registerFocusStateChange(photoSession: camera.PhotoSession): void { 213 photoSession.on('focusStateChange', callback); 214} 215``` 216 217## off('focusStateChange')<sup>11+</sup> 218 219off(type: 'focusStateChange', callback?: AsyncCallback\<FocusState\>): void 220 221注销监听相机聚焦的状态变化。 222 223**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 224 225**系统能力：** SystemCapability.Multimedia.Camera.Core 226 227**参数：** 228 229| 参数名 | 类型 | 必填 | 说明 | 230| -------- | ----------------------------------------- | ---- | ------------------------ | 231| type | string | 是 | 监听事件，固定为'focusStateChange'，session创建成功可监听。 | 232| callback | AsyncCallback\<[FocusState](arkts-apis-camera-e.md#focusstate)\> | 否 | 回调函数，如果指定参数则取消对应callback（callback对象不可是匿名函数），否则取消所有callback。 | 233 234**示例：** 235 236```ts 237function unregisterFocusStateChange(photoSession: camera.PhotoSession): void { 238 photoSession.off('focusStateChange'); 239} 240``` 241 242## on('smoothZoomInfoAvailable')<sup>11+</sup> 243 244on(type: 'smoothZoomInfoAvailable', callback: AsyncCallback\<SmoothZoomInfo\>): void 245 246监听相机平滑变焦的状态变化，通过注册回调函数获取结果。使用callback异步回调。 247 248> **说明：** 249> 250> 当前注册监听接口，不支持在on监听的回调方法里，调用off注销回调。 251 252**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 253 254**系统能力：** SystemCapability.Multimedia.Camera.Core 255 256**参数：** 257 258| 参数名 | 类型 | 必填 | 说明 | 259| -------- | ----------------------- | ---- | ------------------------ | 260| type | string | 是 | 监听事件，固定为'smoothZoomInfoAvailable'，session创建成功可监听。| 261| callback | AsyncCallback\<[SmoothZoomInfo](arkts-apis-camera-i.md#smoothzoominfo11)\> | 是 | 回调函数，用于获取当前平滑变焦状态。 | 262 263**示例：** 264 265```ts 266import { BusinessError } from '@kit.BasicServicesKit'; 267 268function callback(err: BusinessError, smoothZoomInfo: camera.SmoothZoomInfo): void { 269 if (err !== undefined && err.code !== 0) { 270 console.error(`Callback Error, errorCode: ${err.code}`); 271 return; 272 } 273 console.info(`The duration of smooth zoom: ${smoothZoomInfo.duration}`); 274} 275 276function registerSmoothZoomInfo(photoSession: camera.PhotoSession): void { 277 photoSession.on('smoothZoomInfoAvailable', callback); 278} 279``` 280 281## off('smoothZoomInfoAvailable')<sup>11+</sup> 282 283off(type: 'smoothZoomInfoAvailable', callback?: AsyncCallback\<SmoothZoomInfo\>): void 284 285注销监听相机平滑变焦的状态变化。 286 287**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 288 289**系统能力：** SystemCapability.Multimedia.Camera.Core 290 291**参数：** 292 293| 参数名 | 类型 | 必填 | 说明 | 294| -------- | ----------------------------------------- | ---- | ------------------------ | 295| type | string | 是 | 监听事件，固定为'smoothZoomInfoAvailable'，session创建成功可监听。| 296| callback | AsyncCallback\<[SmoothZoomInfo](arkts-apis-camera-i.md#smoothzoominfo11)\> | 否 | 回调函数，如果指定参数则取消对应callback（callback对象不可是匿名函数），否则取消所有callback。 | 297 298**示例：** 299 300```ts 301function unregisterSmoothZoomInfo(photoSession: camera.PhotoSession): void { 302 photoSession.off('smoothZoomInfoAvailable'); 303} 304``` 305 306## on('autoDeviceSwitchStatusChange')<sup>13+</sup> 307 308on(type: 'autoDeviceSwitchStatusChange', callback: AsyncCallback\<AutoDeviceSwitchStatus\>): void 309 310监听相机自动切换镜头状态变化，通过注册回调函数获取结果。使用callback异步回调。 311 312> **说明：** 313> 314> 当前注册监听接口，不支持在on监听的回调方法里，调用off注销回调。 315 316**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 317 318**系统能力：** SystemCapability.Multimedia.Camera.Core 319 320**参数：** 321 322| 参数名 | 类型 | 必填 | 说明 | 323| -------- |----------------------------------------------------------------------| ---- |--------------------------------------------------------| 324| type | string | 是 | 监听事件，固定为'autoDeviceSwitchStatusChange'，session创建成功可监听。 | 325| callback | AsyncCallback\<[AutoDeviceSwitchStatus](arkts-apis-camera-i.md#autodeviceswitchstatus13)\> | 是 | 回调函数，用于获取当前自动切换镜头的状态。 | 326 327**示例：** 328 329```ts 330import { BusinessError } from '@kit.BasicServicesKit'; 331 332function callback(err: BusinessError, autoDeviceSwitchStatus: camera.AutoDeviceSwitchStatus): void { 333 if (err !== undefined && err.code !== 0) { 334 console.error(`Callback Error, errorCode: ${err.code}`); 335 return; 336 } 337 console.info(`isDeviceSwitched: ${autoDeviceSwitchStatus.isDeviceSwitched}, isDeviceCapabilityChanged: ${autoDeviceSwitchStatus.isDeviceCapabilityChanged}`); 338} 339 340function registerAutoDeviceSwitchStatus(photoSession: camera.PhotoSession): void { 341 photoSession.on('autoDeviceSwitchStatusChange', callback); 342} 343``` 344 345## off('autoDeviceSwitchStatusChange')<sup>13+</sup> 346 347off(type: 'autoDeviceSwitchStatusChange', callback?: AsyncCallback\<AutoDeviceSwitchStatus\>): void 348 349注销监听相机自动切换镜头状态变化。 350 351**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 352 353**系统能力：** SystemCapability.Multimedia.Camera.Core 354 355**参数：** 356 357| 参数名 | 类型 | 必填 | 说明 | 358| -------- |----------------------------------------------| ---- | ------------------------ | 359| type | string | 是 | 监听事件，固定为'autoDeviceSwitchStatusChange'，session创建成功可监听。| 360| callback | AsyncCallback\<[AutoDeviceSwitchStatus](arkts-apis-camera-i.md#autodeviceswitchstatus13)\> | 否 | 回调函数，如果指定参数则取消对应callback（callback对象不可是匿名函数），否则取消所有callback。 | 361 362**示例：** 363 364```ts 365function unregisterSmoothZoomInfo(photoSession: camera.PhotoSession): void { 366 photoSession.off('autoDeviceSwitchStatusChange'); 367} 368``` 369 370## on('systemPressureLevelChange')<sup>20+</sup> 371 372on(type: 'systemPressureLevelChange', callback: AsyncCallback\<SystemPressureLevel\>): void 373 374监听系统压力状态变化，通过注册回调函数获取结果。使用callback异步回调。 375 376> **说明：** 377> 378> 当前注册监听接口，不支持在on监听的回调方法里，调用off注销回调。 379 380**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 381 382**系统能力：** SystemCapability.Multimedia.Camera.Core 383 384**参数：** 385 386| 参数名 | 类型 | 必填 | 说明 | 387|---------|----------------------------------------------------------|------|-------------------------------------------------------------------| 388|type | string | 是 | 监听事件，固定为'systemPressureLevelChange'，session创建成功可监听。 | 389|callback | AsyncCallback\<[SystemPressureLevel](arkts-apis-camera-e.md#systempressurelevel20)\> | 是 | 回调函数，用于获取当前系统压力状态. | 390 391**示例：** 392 393```ts 394import { BusinessError } from '@kit.BasicServicesKit'; 395 396function callback(err: BusinessError, systemPressureLevel: camera.SystemPressureLevel): void { 397 if (err !== undefined && err.code !== 0) { 398 console.error(`Callback Error, errorCode: ${err.code}`); 399 return; 400 } 401 console.info(`systemPressureLevel: ${systemPressureLevel}`); 402} 403 404function registerSystemPressureLevelChangeCallback(photoSession: camera.PhotoSession): void { 405 photoSession.on('systemPressureLevelChange', callback); 406} 407``` 408 409## off('systemPressureLevelChange')<sup>20+</sup> 410 411off(type: 'systemPressureLevelChange', callback?: AsyncCallback\<SystemPressureLevel\>): void 412 413注销监听系统压力状态变化。 414 415**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 416 417**系统能力：** SystemCapability.Multimedia.Camera.Core 418 419**参数：** 420 421| 参数名 | 类型 | 必填 | 说明 | 422|----------|--------------------------------|---------|------------------------------------------------------------------| 423| type | string | 是 | 注销监听事件，固定为'systemPressureLevelChange'，session创建成功可触发此事件。| 424| callback | AsyncCallback\<[SystemPressureLevel](arkts-apis-camera-e.md#systempressurelevel20)\> | 否 | 回调函数，如果指定参数则取消对应callback (callback对象不可是匿名函数)，否则参数默认为空，取消所有callback。 | 425 426**示例：** 427 428```ts 429function unregisterSystemPressureLevelChangeCallback(photoSession: camera.PhotoSession): void { 430 photoSession.off('systemPressureLevelChange'); 431} 432``` 433 434## on('macroStatusChanged')<sup>20+</sup> 435 436on(type: 'macroStatusChanged', callback: AsyncCallback\<boolean\>): void 437 438监听相机微距状态变化，通过注册回调函数获取结果。使用callback异步回调。 439 440**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 441 442**系统能力：** SystemCapability.Multimedia.Camera.Core 443 444**参数：** 445 446| 参数名 | 类型 | 必填 | 说明 | 447| -------- | ----------------------------------------- | ---- | ------------------------ | 448| type | string | 是 | 监听事件，固定为'macroStatusChanged'，session创建成功可监听。 | 449| callback | AsyncCallback\<boolean\> | 是 | 回调函数，用于获取当前微距状态，返回true为开启状态，返回false为禁用状态。 | 450 451**示例：** 452 453```ts 454import { BusinessError } from '@kit.BasicServicesKit'; 455 456function callback(err: BusinessError, macroStatus: boolean): void { 457 if (err !== undefined && err.code !== 0) { 458 console.error(`Callback Error, errorCode: ${err.code}`); 459 return; 460 } 461 console.info(`Macro state: ${macroStatus}`); 462} 463 464function registerMacroStatusChanged(photoSession: camera.PhotoSession): void { 465 photoSession.on('macroStatusChanged', callback); 466} 467``` 468 469## off('macroStatusChanged')<sup>20+</sup> 470 471off(type: 'macroStatusChanged', callback?: AsyncCallback\<boolean\>): void 472 473注销相机微距状态变化的监听。 474 475**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 476 477**系统能力：** SystemCapability.Multimedia.Camera.Core 478 479**参数：** 480 481| 参数名 | 类型 | 必填 | 说明 | 482| -------- | ------------------------ | ---- |------------------------------------------------------------------------| 483| type | string | 是 | 注销监听事件，固定为'macroStatusChanged'，session创建成功可触发此事件。| 484| callback | AsyncCallback\<boolean\> | 否 | 回调函数，可选，如果指定参数则取消对应callback (callback对象不可是匿名函数)，否则参数默认为空，取消所有callback。 | 485 486**示例：** 487 488```ts 489function unregisterMacroStatusChanged(photoSession: camera.PhotoSession): void { 490 photoSession.off('macroStatusChanged'); 491} 492``` 493