• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Camera Preview (ArkTS)
2
3Preview is the image you see after you start the camera application but before you take photos or record videos.
4
5## How to Develop
6
7Read [Camera](../reference/apis/js-apis-camera.md) for the API reference.
8
91. Import the camera module, which provides camera-related attributes and methods.
10
11   ```ts
12   import camera from '@ohos.multimedia.camera';
13   import { BusinessError } from '@ohos.base';
14   ```
15
162. Create a surface.
17
18    The **\<XComponent>**, the capabilities of which are provided by the UI, offers the surface for preview streams. For details, see [XComponent](../reference/arkui-ts/ts-basic-components-xcomponent.md).
19
20    **NOTE**: The preview stream and video output stream must have the same aspect ratio of the resolution. For example, the aspect ratio in the code snippet below is 1920:1080 (which is equal to 16:9), then the aspect ratio of the resolution of the preview stream must also be 16:9. This means that the resolution can be 640:360, 960:540, 1920:1080, or the like.
21
22   ```ets
23   // xxx.ets
24   // Create an XComponentController object.
25   @Component
26   struct XComponentPage {
27     // Create an XComponentController object.
28     mXComponentController: XComponentController = new XComponentController;
29     surfaceId: string = '';
30
31     build() {
32       Flex() {
33         // Create an XComponent object.
34         XComponent({
35           id: '',
36           type: 'surface',
37           libraryname: '',
38           controller: this.mXComponentController
39         })
40           .onLoad(() => {
41             // Set the surface width and height (1920 x 1080). For details about how to set the preview size, see the preview resolutions supported by the current device, which are obtained from previewProfilesArray.
42             // The preview stream and video output stream must have the same aspect ratio of the resolution.
43             this.mXComponentController.setXComponentSurfaceSize({surfaceWidth:1920,surfaceHeight:1080});
44             // Obtain the surface ID.
45             this.surfaceId = this.mXComponentController.getXComponentSurfaceId();
46           })
47           .width('1920px')
48           .height('1080px')
49       }
50     }
51   }
52   ```
53
543. Call **previewProfiles()** in the **CameraOutputCapability** class to obtain the preview output capabilities, in the format of an **previewProfilesArray** array, supported by the current device. Then call **createPreviewOutput()** to create a **PreviewOutput** object, with the first parameter set to the first item in the **previewProfilesArray** array and the second parameter set to the surface ID obtained in step 2.
55
56   ```ts
57   function getPreviewOutput(cameraManager: camera.CameraManager, cameraOutputCapability: camera.CameraOutputCapability, surfaceId: string): camera.PreviewOutput | undefined {
58     let previewProfilesArray: Array<camera.Profile> = cameraOutputCapability.previewProfiles;
59     let previewOutput: camera.PreviewOutput | undefined = undefined;
60     try {
61       previewOutput = cameraManager.createPreviewOutput(previewProfilesArray[0], surfaceId);
62     } catch (error) {
63       let err = error as BusinessError;
64       console.error("Failed to create the PreviewOutput instance. error code: " + err.code);
65     }
66     return previewOutput;
67   }
68   ```
69
704. Call **start()** to start outputting the preview stream. If the call fails, an error code is returned. For details, see [Camera Error Codes](../reference/apis/js-apis-camera.md#cameraerrorcode).
71
72   ```ts
73   function startPreviewOutput(previewOutput: camera.PreviewOutput): void {
74     previewOutput.start().then(() => {
75       console.info('Callback returned with previewOutput started.');
76     }).catch((err: BusinessError) => {
77       console.error('Failed to previewOutput start '+ err.code);
78     });
79   }
80   ```
81
82
83## Status Listening
84
85During camera application development, you can listen for the preview output stream status, including preview stream start, preview stream end, and preview stream output errors.
86
87- Register the **'frameStart'** event to listen for preview start events. This event can be registered when a **PreviewOutput** object is created and is triggered when the bottom layer starts exposure for the first time. The preview stream starts as long as a result is returned.
88
89  ```ts
90  function onPreviewOutputFrameStart(previewOutput: camera.PreviewOutput): void {
91    previewOutput.on('frameStart', () => {
92      console.info('Preview frame started');
93    });
94  }
95  ```
96
97- Register the **'frameEnd'** event to listen for preview end events. This event can be registered when a **PreviewOutput** object is created and is triggered when the last frame of preview ends. The preview stream ends as long as a result is returned.
98
99  ```ts
100  function onPreviewOutputFrameEnd(previewOutput: camera.PreviewOutput): void {
101    previewOutput.on('frameEnd', () => {
102      console.info('Preview frame ended');
103    });
104  }
105  ```
106
107- Register the **'error'** event to listen for preview output errors. The callback function returns an error code when an API is incorrectly used. For details about the error code types, see [Camera Error Codes](../reference/apis/js-apis-camera.md#cameraerrorcode).
108
109  ```ts
110  function onPreviewOutputError(previewOutput: camera.PreviewOutput): void {
111    previewOutput.on('error', (previewOutputError: BusinessError) => {
112      console.info(`Preview output error code: ${previewOutputError.code}`);
113    });
114  }
115  ```
116