1# LocationButton 2 3The **LocationButton** security component represents a location button that allows you to obtain temporary, precise location permissions from users with a simple button touch, eliminating the need for a permission request dialog box. 4 5> **NOTE** 6> 7> - This component is supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version. 8> 9> - Since API version 15, the **LocationButton** component is deprecated. You are advised to call [requestPermissionsFromUser](../../apis-ability-kit/js-apis-abilityAccessCtrl.md#requestpermissionsfromuser9-1) to open a dialog box to request the required permissions from users. 10 11## Child Components 12 13Not supported 14 15## APIs 16 17### LocationButton 18 19LocationButton() 20 21Creates a **LocationButton** component with an icon, text, and background. 22 23You may want to learn the [restrictions on security component styles](../../../security/AccessToken/security-component-overview.md#constraints) to avoid authorization failures caused by incompliant styles. 24 25**Atomic service API**: This API can be used in atomic services since API version 11. 26 27**System capability**: SystemCapability.ArkUI.ArkUI.Full 28 29### LocationButton 30 31LocationButton(options: LocationButtonOptions) 32 33Creates a **LocationButton** component that contains the specified elements. 34 35You may want to learn the [restrictions on security component styles](../../../security/AccessToken/security-component-overview.md#constraints) to avoid authorization failures caused by incompliant styles. 36 37**Atomic service API**: This API can be used in atomic services since API version 11. 38 39**System capability**: SystemCapability.ArkUI.ArkUI.Full 40 41**Parameters** 42 43| Name| Type| Mandatory| Description| 44| -------- | -------- | -------- | -------- | 45| options | [LocationButtonOptions](#locationbuttonoptions) | Yes| Options of the **LocationButton** component.| 46 47## LocationButtonOptions 48 49Describes the icon, text, and other specific elements for the **LocationButton** component. 50 51> **NOTE** 52> 53> - At least one of **icon** or **text** must be provided.<br> 54> - If neither **icon** nor **text** is provided, the **options** parameter in [LocationButton](#locationbutton-1) will not take effect, and the created **LocationButton** component will use the default style: 55> 56> The default value of **LocationIconStyle** is **LINES**. 57> 58> The default style of **LocationDescription** is **CURRENT_LOCATION**. 59> 60> The default value of **ButtonType** is **Capsule**. 61> - The **icon**, **text**, and **buttonType** parameters do not support dynamic modification. 62 63**Atomic service API**: This API can be used in atomic services since API version 11. 64 65**System capability**: SystemCapability.ArkUI.ArkUI.Full 66 67| Name| Type| Mandatory| Description| 68| -------- | -------- | -------- | -------- | 69| icon | [LocationIconStyle](#locationiconstyle) | No| Icon style of the **LocationButton** component.<br>If this parameter is not specified, there is no icon.| 70| text | [LocationDescription](#locationdescription) | No| Text on the **LocationButton** component.<br>If this parameter is not specified, there is no text description.| 71| buttonType | [ButtonType](ts-securitycomponent-attributes.md#buttontype) | No| Background style of the **LocationButton** component.<br>If this parameter is not specified, the component takes on the capsule style.| 72 73## LocationIconStyle 74 75**Atomic service API**: This API can be used in atomic services since API version 11. 76 77**System capability**: SystemCapability.ArkUI.ArkUI.Full 78 79| Name| Value| Description| 80| -------- | -------- | -------- | 81| FULL_FILLED | 0 | Filled style icon.| 82| LINES | 1 | Line style icon.| 83 84## LocationDescription 85 86**Atomic service API**: This API can be used in atomic services since API version 11. 87 88**System capability**: SystemCapability.ArkUI.ArkUI.Full 89 90| Name| Value| Description| 91| -------- | -------- | -------- | 92| CURRENT_LOCATION | 0 | The text on the **LocationButton** component is **Current location**.| 93| ADD_LOCATION | 1 | The text on the **LocationButton** component is **Add location**.| 94| SELECT_LOCATION | 2 | The text on the **LocationButton** component is **Select location**.| 95| SHARE_LOCATION | 3 | The text on the **LocationButton** component is **Share location**.| 96| SEND_LOCATION | 4 | The text on the **LocationButton** component is **Send location**.| 97| LOCATING | 5 | The text on the **LocationButton** component is **Locate**.| 98| LOCATION | 6 | The text on the **LocationButton** component is **Location**.| 99| SEND_CURRENT_LOCATION | 7 | The text on the **LocationButton** component is **Send current location**.| 100| RELOCATION | 8 | The text on the **LocationButton** component is **Relocate**.| 101| PUNCH_IN | 9 | The text on the **LocationButton** component is **Punch in**.| 102| CURRENT_POSITION | 10 | The text on the **LocationButton** component is **Current position**.| 103 104## LocationButtonOnClickResult 105 106**Atomic service API**: This API can be used in atomic services since API version 11. 107 108**System capability**: SystemCapability.ArkUI.ArkUI.Full 109 110| Name| Value| Description| 111| -------- | -------- | -------- | 112| SUCCESS | 0 | The **LocationButton** component is touched successfully.| 113| TEMPORARY_AUTHORIZATION_FAILED | 1 | Temporary authorization fails after the **LocationButton** component is touched.| 114 115## LocationButtonCallback<sup>18+</sup> 116 117type LocationButtonCallback = (event: ClickEvent, result: LocationButtonOnClickResult, error?: BusinessError<void>) => void 118 119Triggered when the **LocationButton** component is clicked. 120 121**Atomic service API**: This API can be used in atomic services since API version 18. 122 123**System capability**: SystemCapability.ArkUI.ArkUI.Full 124 125| Name| Type | Mandatory| Description | 126|------------|------|-------|---------| 127| event | [ClickEvent](ts-universal-events-click.md#clickevent) |Yes|See **ClickEvent**.| 128| result | [LocationButtonOnClickResult](#locationbuttononclickresult)| Yes| Authorization result.| 129| error | [BusinessError<void>](../../apis-basic-services-kit/js-apis-base.md#businesserror)| No | Error code and message when the component is clicked.<br>Error code 0 indicates successful authorization.<br>Error code 1 indicates an internal system error.<br>Error code 2 indicates attribute setting errors, including but not limited to:<br>1. The font or icon size is too small.<br>2. The font or icon color is too similar to the background color.<br>3. The font or icon color is too transparent.<br>4. The padding is negative.<br>5. The component is obscured by other components or windows.<br>6. The text exceeds the background range.<br>7. The component exceeds the window or screen bounds.<br>8. The component size is too large.<br>9. The component text is truncated and not fully displayed.<br>10. Related attribute settings affect the display of security components.| 130 131## Attributes 132 133This component can only inherit the [universal attributes of security components](ts-securitycomponent-attributes.md). 134 135## Events 136 137Only the following events are supported. 138 139### onClick 140 141onClick(event: LocationButtonCallback) 142 143Called when a click event occurs. 144 145**Atomic service API**: This API can be used in atomic services since API version 11. 146 147**System capability**: SystemCapability.ArkUI.ArkUI.Full 148 149**Parameters** 150 151| Name| Type | Mandatory| Description | 152|------------|------|-------|---------| 153| event | [LocationButtonCallback](#locationbuttoncallback18) |Yes|See **LocationButtonCallback**.<br>In API versions 10 to 17, the parameter type is event: [ClickEvent](ts-universal-events-click.md#clickevent), result: [LocationButtonOnClickResult](#locationbuttononclickresult)) => void.<br>Since API version 18, the parameter type changes into LocationButtonCallback.| 154 155## Example 156 157```ts 158// xxx.ets 159import { BusinessError } from '@kit.BasicServicesKit'; 160 161@Entry 162@Component 163struct Index { 164 handleLocationButtonClick: LocationButtonCallback = 165 (event: ClickEvent, result: LocationButtonOnClickResult, error: BusinessError<void>) => { 166 if (result == LocationButtonOnClickResult.SUCCESS) { 167 console.info("success"); 168 } else { 169 console.info("errCode: " + error.code); 170 console.info("errMessage: " + error.message); 171 } 172 }; 173 174 build() { 175 Row() { 176 Column({ space: 10 }) { 177 // Create a default button with an icon, text, and background. 178 LocationButton().onClick(this.handleLocationButtonClick) 179 // Whether an element is contained depends on whether the parameter corresponding to the element is specified. If buttonType is not passed in, the button uses the ButtonType.Capsule settings. 180 LocationButton({ icon: LocationIconStyle.LINES }) 181 // Create a button with only an icon and background. If the alpha value of the most significant eight bits of the background color is less than 0x1A, the system forcibly adjusts the alpha value to 0xFF. 182 LocationButton({ icon: LocationIconStyle.LINES, buttonType: ButtonType.Capsule }) 183 .backgroundColor(0x10007dff) 184 // Create a button with an icon, text, and background. If the alpha value of the most significant eight bits of the background color is less than 0x1A, the system forcibly adjusts the alpha value to 0xFF. 185 LocationButton({ 186 icon: LocationIconStyle.LINES, 187 text: LocationDescription.CURRENT_LOCATION, 188 buttonType: ButtonType.Capsule 189 }) 190 // Create a button with an icon, text, and background. If the set width is less than the minimum allowed, the button's text will wrap to guarantee full text display. 191 LocationButton({ 192 icon: LocationIconStyle.LINES, 193 text: LocationDescription.CURRENT_LOCATION, 194 buttonType: ButtonType.Capsule 195 }) 196 .fontSize(16) 197 .width(30) 198 // Create a button with an icon, text, and background. If the set width is less than the minimum allowed, the button's text will wrap to guarantee full text display. 199 LocationButton({ 200 icon: LocationIconStyle.LINES, 201 text: LocationDescription.CURRENT_LOCATION, 202 buttonType: ButtonType.Capsule 203 }) 204 .fontSize(16) 205 .size({ width: 30, height: 30 }) 206 // Create a button with an icon, text, and background. If the set width is less than the minimum allowed, the button's text will wrap to guarantee full text display. 207 LocationButton({ 208 icon: LocationIconStyle.LINES, 209 text: LocationDescription.CURRENT_LOCATION, 210 buttonType: ButtonType.Capsule 211 }) 212 .fontSize(16) 213 .constraintSize({ 214 minWidth: 0, 215 maxWidth: 30, 216 minHeight: 0, 217 maxHeight: 30 218 }) 219 }.width('100%') 220 }.height('100%') 221 } 222} 223``` 224 225 226
