1# 分段式拍照(ArkTS)
2
3分段式拍照是相机的重要功能之一，即应用下发拍照任务后，系统将分多阶段上报不同质量的图片。
4- 在第一阶段，系统快速上报轻量处理的图片，轻量处理的图片比全质量图低，出图速度快。应用通过回调会收到一个PhotoAsset对象，通过该对象可调用媒体库接口，读取图片或落盘图片。
5- 在第二阶段，相机框架会根据应用的请求图片诉求或者在系统闲时，进行图像增强处理得到全质量图，将处理好的图片传回给媒体库，替换轻量处理的图片。
6
7通过分段式拍照，优化了系统的拍照响应时延，从而提升用户体验。
8
9应用开发分段式拍照主要分为以下步骤：
10
11- 通过PhotoOutput，监听photoAssetAvailable回调，获取[photoAccessHelper](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md)的PhotoAsset对象。
12- 通过PhotoAsset对象，调用媒体库相关接口，读取或落盘图片。
13
14> **说明：**
15>
16> - 分段式拍照能力是根据**设备**和**模式**决定的，不同的设备支持不同的模式，不同的模式下分段式能力也各有不同，所以应用在切换设备或模式后分段式能力可能会发生变化。
17> - 分段式拍照能力应用无需主动使能，相机框架会在配流期间判断设备和模式是否支持分段式，如果支持会使能分段式拍照。
18
19## 开发步骤
20
21详细的API说明请参考[Camera API参考](../../reference/apis-camera-kit/js-apis-camera.md)。
22
231. 导入依赖，需要导入相机框架、媒体库、图片相关领域依赖。
24
25   ```ts
26   import { camera } from '@kit.CameraKit';
27   import { BusinessError } from '@kit.BasicServicesKit';
28   import { common } from '@kit.AbilityKit';
29   import { photoAccessHelper } from '@kit.MediaLibraryKit';
30   ```
31
322. 确定拍照输出流。
33
34   通过[CameraOutputCapability](../../reference/apis-camera-kit/js-apis-camera.md#cameraoutputcapability)类中的photoProfiles属性，可获取当前设备支持的拍照输出流，通过[createPhotoOutput](../../reference/apis-camera-kit/js-apis-camera.md#createphotooutput11)方法创建拍照输出流。
35
36   ```ts
37   function getPhotoOutput(cameraManager: camera.CameraManager,
38                           cameraOutputCapability: camera.CameraOutputCapability): camera.PhotoOutput | undefined {
39     let photoProfilesArray: Array<camera.Profile> = cameraOutputCapability.photoProfiles;
40     if (!photoProfilesArray) {
41       console.error("createOutput photoProfilesArray == null || undefined");
42     }
43     let photoOutput: camera.PhotoOutput | undefined = undefined;
44     try {
45       photoOutput = cameraManager.createPhotoOutput(photoProfilesArray[0]);
46     } catch (error) {
47       let err = error as BusinessError;
48       console.error(`Failed to createPhotoOutput. error: ${JSON.stringify(err)}`);
49     }
50     return photoOutput;
51   }
52   ```
53
543. 设置拍照photoAssetAvailable的回调。
55
56   > **注意：**
57   > 如果已经注册了photoAssetAvailable回调，并且在Session开始之后又注册了photoAvailable回调，photoAssetAvailable和photoAvailable同时注册，会导致流被重启，仅photoAssetAvailable生效。
58   >
59   > 不建议开发者同时注册photoAvailable和photoAssetAvailable。
60
61   ```ts
62   function photoAssetAvailableCallback(err: BusinessError, photoAsset: photoAccessHelper.PhotoAsset): void {
63     if (err) {
64       console.error(`photoAssetAvailable error: ${JSON.stringify(err)}.`);
65       return;
66     }
67     console.info('photoOutPutCallBack photoAssetAvailable');
68     // 开发者可通过photoAsset调用媒体库相关接口，自定义处理图片
69     // 处理方式一：调用媒体库落盘接口保存一阶段图，二阶段图就绪后媒体库会主动帮应用替换落盘图片
70     mediaLibSavePhoto(photoAsset);
71     // 处理方式二：调用媒体库接口请求图片并注册一阶段图或二阶段图buffer回调，自定义使用
72     mediaLibRequestBuffer(photoAsset);
73   }
74
75   function onPhotoOutputPhotoAssetAvailable(photoOutput: camera.PhotoOutput): void {
76     photoOutput.on('photoAssetAvailable', photoAssetAvailableCallback);
77   }
78
79   let context = getContext(this);
80   let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
81
82   async function mediaLibSavePhoto(photoAsset: photoAccessHelper.PhotoAsset): Promise<void> {
83     try {
84       let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(photoAsset);
85       assetChangeRequest.saveCameraPhoto();
86       await phAccessHelper.applyChanges(assetChangeRequest);
87       console.info('apply saveCameraPhoto successfully');
88     } catch (err) {
89       console.error(`apply saveCameraPhoto failed with error: ${err.code}, ${err.message}`);
90     }
91   }
92
93   class MediaDataHandler implements photoAccessHelper.MediaAssetDataHandler<ArrayBuffer> {
94     onDataPrepared(data: ArrayBuffer) {
95       if (data === undefined) {
96         console.error('Error occurred when preparing data');
97         return;
98       }
99       // 应用获取到图片buffer后可自定义处理
100       console.info('on image data prepared');
101     }
102   }
103
104   async function mediaLibRequestBuffer(photoAsset: photoAccessHelper.PhotoAsset) {
105     let requestOptions: photoAccessHelper.RequestOptions = {
106       // 按照业务需求配置回图模式
107       // FAST_MODE：仅接收一阶段低质量图回调
108       // HIGH_QUALITY_MODE：仅接收二阶段全质量图回调
109       // BALANCE_MODE：接收一阶段及二阶段图片回调
110       deliveryMode: photoAccessHelper.DeliveryMode.FAST_MODE,
111     }
112     const handler = new MediaDataHandler();
113     await photoAccessHelper.MediaAssetManager.requestImageData(context, photoAsset, requestOptions, handler);
114     console.info('requestImageData successfully');
115   }
116   ```
117
118   落盘图片参考媒体库接口：[saveCameraPhoto](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#savecameraphoto12)
119
120   请求图片参考媒体库接口：[requestImageData](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#requestimagedata11) 和 [onDataPrepared](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#ondataprepared11)
121
1224. 拍照时的会话配置及触发拍照的方式，与普通拍照相同，请参考[拍照](camera-shooting.md)的步骤4-5。
123
124## 状态监听
125
126在相机应用开发过程中，可以随时监听拍照输出流状态，包括拍照流开始、拍照帧的开始与结束、拍照输出流的错误。
127
128- 通过注册固定的captureStart回调函数获取监听拍照开始结果，photoOutput创建成功时即可监听，相机设备已经准备开始这次拍照时触发，该事件返回此次拍照的captureId。
129
130  ```ts
131  function onPhotoOutputCaptureStart(photoOutput: camera.PhotoOutput): void {
132    photoOutput.on('captureStartWithInfo', (err: BusinessError, captureStartInfo: camera.CaptureStartInfo) => {
133      if (err !== undefined && err.code !== 0) {
134        return;
135      }
136      console.info(`photo capture started, captureId : ${captureStartInfo.captureId}`);
137    });
138  }
139  ```
140
141- 通过注册固定的captureEnd回调函数获取监听拍照结束结果，photoOutput创建成功时即可监听，该事件返回结果为拍照完全结束后的相关信息[CaptureEndInfo](../../reference/apis-camera-kit/js-apis-camera.md#captureendinfo)。
142
143  ```ts
144  function onPhotoOutputCaptureEnd(photoOutput: camera.PhotoOutput): void {
145    photoOutput.on('captureEnd', (err: BusinessError, captureEndInfo: camera.CaptureEndInfo) => {
146      if (err !== undefined && err.code !== 0) {
147        return;
148      }
149      console.info(`photo capture end, captureId : ${captureEndInfo.captureId}`);
150      console.info(`frameCount : ${captureEndInfo.frameCount}`);
151    });
152  }
153  ```
154
155- 通过注册固定的captureReady回调函数获取监听可拍下一张结果，photoOutput创建成功时即可监听，当下一张可拍时触发，该事件返回结果为下一张可拍的相关信息。
156
157  ```ts
158  function onPhotoOutputCaptureReady(photoOutput: camera.PhotoOutput): void {
159    photoOutput.on('captureReady', (err: BusinessError) => {
160      if (err !== undefined && err.code !== 0) {
161        return;
162      }
163      console.info(`photo capture ready`);
164    });
165  }
166  ```
167
168- 通过注册固定的error回调函数获取监听拍照输出流的错误结果。callback返回拍照输出接口使用错误时的对应错误码，错误码类型参见[Camera错误码](../../reference/apis-camera-kit/js-apis-camera.md#cameraerrorcode)。
169
170  ```ts
171  function onPhotoOutputError(photoOutput: camera.PhotoOutput): void {
172    photoOutput.on('error', (error: BusinessError) => {
173      console.error(`Photo output error code: ${error.code}`);
174    });
175  }
176  ```