• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Security Component Development
2
3
4## When to Use
5
6Security components are a set of ArkUI components provided by OpenHarmony. You can integrate the security components to your app UI. The security components come with automatic authorization, which eliminates authorization dialog boxes.
7
8Currently, OpenHarmony provides security components **\<LocationButton>**, **\<PasteButton>**, and **\<SaveButton>**, with precise positioning, clipboard reading, and media library writing permissions, respectively.
9
10- **\<LocationButton>**
11
12  When **\<LocationButton>** is tapped, the app can call the location service to obtain the precise location no matter whether the app has applied for or is granted with the precise location permission. The temporary authorization for precise location remains valid until the location component is destroyed, the screen is turned off, the app is switched to the background, or the app exits. Then, the permission state transits to the state prior to the temporary authorization. During the temporary authorization period, there is no limit on the number of times that the app calls the APIs that request the permission.
13
14  You can use the **\<LocationButton>** component for apps that may use the location information in certain scenarios, such as city location, clock-in/out, and location sharing. This component is not applicable for location-based apps, such as navigation and health apps. If location information needs to be used for a long period of time or in the background, apply for the location permission for your app.
15
16- **\<PasteButton>**
17
18  When **\<PasteButton>** is tapped, no toast message is displayed when the app reads data from the clipboard. The temporary authorization for reading data from the clipboard remains invalid only when data is written to the clipboard (for example, the user copies new data). The authorization is not affected when the screen is turned off, the app is switched to the background, or the app exits. During the temporary authorization period, there is no limit on the number of times that the app calls the APIs that request the permission.
19
20  You can use the **\<PasteButton>** component for apps that need to read data from the clipboard.
21
22- **\<SaveButton>**
23
24  When **\<SaveButton>** is tapped, the app can access the **mediaLibrary** APIs once within 5 seconds.
25
26  When using **\<SaveButton>**, observe the following:
27
28  - The interval for calling **onClick()** to trigger a **mediaLibrary** API cannot exceed 5 seconds after **\<SaveButton>** is tapped.
29  - The app obtains one-time authorization only each time **\<SaveButton>** is tapped.
30
31You can use **\<SaveButton>** for apps that need to save files to the media library (such as saving images and videos). The **\<SaveButton>** component features simpler and faster operations than **filePicker**, which needs to start the system application and requires the user to select a directory for saving the file.
32
33
34## Creating a Security Component
35
36A security component is a button consisting of an icon, text, and background. Either the icon or text is mandatory, and the background is optional. The icon and text cannot be customized. You can only select from the existing options.
37
38When declaring the API for creating a security component, you can determine whether to pass in parameters. If parameters are passed in, the component is created based on the specified parameters. If no parameter is passed in, a component with default icon, text, and background is created.
39
40The following uses the **\<SaveButton>** component as an example.
41
42```
43/* Create a default <SaveButton>. */
44SaveButton()
45
46/* Create a <SaveButton> with the icon only. */
47SaveButton({ icon:SaveIconStyle.FULL_FILLED })
48
49/* Create a <SaveButton> with the text and icon only. */
50SaveButton({ icon:SaveIconStyle.FULL_FILLED, text:SaveDescription.DOWNLOAD })
51```
52
53
54## Common Attributes
55
56The following table describes the common UX attributes for security components.
57
58| Attribute| Description|
59| -------- | -------- |
60| iconSize(value: Dimension) | Icon size of the security component.|
61| layoutDirection(value: SecurityComponentLayoutDirection) | Direction of the icon and text on the security component.|
62| position(value: Position) | Absolute position of the security component.|
63| markAnchor(value: Position) | Anchor for the absolute position.|
64| offset(value: Position) | Offset of the position of the security component.|
65| fontSize(value: Dimension) | Font size of the text on the security component.|
66| fontStyle(value: FontStyle) | Font style of the text on the security component.|
67| fontWeight(value: number \| FontWeight \| string) | Font weight of the text on the security component.|
68| fontFamily(value: string \| Resource) | Font family of the text on the security component.|
69| fontColor(value: ResourceColor) | Font color of the text on the security component.|
70| iconColor(value: ResourceColor) | Color of the icon on the security component.|
71| backgroundColor(value: ResourceColor) | Background color of the icon on the security component.|
72| borderStyle(value: BorderStyle) | Border style of the security component.|
73| borderWidth(value: Dimension) | Border width of the security component.|
74| borderColor(value: ResourceColor) | Border color of the security component.|
75| borderRadius(value: Dimension) | Radius of the rounded border corners of the security component.|
76| padding(value: Padding \| Dimension) | Inner margins of the security component.|
77| textIconSpace(value: Dimension) | Space between the icon and text on the security component.|
78
79
80## How to Develop
81
821. Declare the security component in the .ets file.
83   ```
84      LocationButton()
85   ```
86
872. Configure the attributes of the security component.
88   ```
89      LocationButton().iconSize(40.0)
90   ```
91
923. Register the **onClick** callback for calling the API protected by the permission. The following uses the **\<LocationButton>** component as an example.
93   ```
94   import geoLocationManager from '@ohos.geoLocationManager';
95   import BusinessError from "@ohos.base";
96   @Entry
97   @Component
98   struct locationButton {
99     build() {
100       Row() {
101         Column() {
102           LocationButton({ icon: LocationIconStyle.FULL_FILLED }).iconSize(40.0)
103             .onClick((event: ClickEvent, result: LocationButtonOnClickResult) => {
104               if (result == LocationButtonOnClickResult.SUCCESS) {
105                 /* The API to call is js-apis-geoLocationManager.md#currentlocationrequest. */
106                 let requestInfo:geoLocationManager.CurrentLocationRequest = {'priority': geoLocationManager.LocationRequestPriority.FIRST_FIX, 'scenario': geoLocationManager.LocationRequestScenario.UNSET,'maxAccuracy': 0};
107                 let locationChange = (err:BusinessError.BusinessError, location:geoLocationManager.Location):void => {
108                   if (err) {
109                     console.log('locationChanger: err=' + JSON.stringify(err));
110                   }
111                   if (location) {
112                     console.log('locationChanger: location=' + JSON.stringify(location));
113                   }
114                 };
115
116                 try {
117                   geoLocationManager.getCurrentLocation(requestInfo, locationChange);
118                 } catch (err) {
119                   console.error("errCode:" + (err as BusinessError.BusinessError).code + ",errMessage:" + (err as BusinessError.BusinessError).message);
120                 }
121               }
122             })
123         }.width('100%')
124       }.height('100%')
125     }
126   }
127   ```
128