1# LocationButton 2 3安全控件的位置控件，用户通过点击该位置按钮，可以临时获取精准定位权限，而不需要权限弹框授权确认。 4 5> **说明：** 6> 7> - 该组件从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9> - 从API Version 15开始，位置控件不再维护，推荐调用[requestPermissionsFromUser](../../apis-ability-kit/js-apis-abilityAccessCtrl.md#requestpermissionsfromuser9-1)拉起权限弹窗，请求用户授权。 10 11## 子组件 12 13不支持。 14 15## 接口 16 17### LocationButton 18 19LocationButton() 20 21默认创建带有图标、文本、背景的位置按钮。 22 23为避免控件样式不合法导致授权失败，请开发者先了解安全控件样式的[约束与限制](../../../security/AccessToken/security-component-overview.md#约束与限制)。 24 25**原子化服务API：** 从API version 11开始，该接口支持在元服务中使用。 26 27**系统能力：** SystemCapability.ArkUI.ArkUI.Full 28 29### LocationButton 30 31LocationButton(options: LocationButtonOptions) 32 33创建包含指定元素的位置按钮。 34 35为避免控件样式不合法导致授权失败，请开发者先了解安全控件样式的[约束与限制](../../../security/AccessToken/security-component-overview.md#约束与限制)。 36 37**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 38 39**系统能力：** SystemCapability.ArkUI.ArkUI.Full 40 41**参数：** 42 43| 参数名 | 类型 | 必填 | 说明 | 44| -------- | -------- | -------- | -------- | 45| options | [LocationButtonOptions](#locationbuttonoptions) | 是 | 创建包含指定元素的位置按钮。 | 46 47## LocationButtonOptions 48 49用于指定位置按钮的图标、文本等指定元素。 50 51> **说明：** 52> 53> - icon或text需至少传入一个。<br> 54> - 如果icon、text都不传入，[LocationButton](#locationbutton-1)中的options参数不起效，创建的LocationButton为默认样式，默认样式： 55> 56> LocationIconStyle默认样式为LINES； 57> 58> LocationDescription默认样式为CURRENT_LOCATION； 59> 60> ButtonType默认样式为Capsule。 61> - icon、text、buttonType不支持动态修改。 62 63**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 64 65**系统能力：** SystemCapability.ArkUI.ArkUI.Full 66 67| 名称 | 类型 | 必填 | 说明 | 68| -------- | -------- | -------- | -------- | 69| icon | [LocationIconStyle](#locationiconstyle枚举说明) | 否 | 设置位置按钮的图标风格。<br/>不传入该参数表示没有图标。 | 70| text | [LocationDescription](#locationdescription枚举说明) | 否 | 设置位置按钮的文本描述。<br/>不传入该参数表示没有文字描述。 | 71| buttonType | [ButtonType](ts-securitycomponent-attributes.md#buttontype枚举说明) | 否 | 设置位置按钮的背景样式。<br/>不传入该参数，系统默认提供Capsule类型按钮。 | 72 73## LocationIconStyle枚举说明 74 75**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 76 77**系统能力：** SystemCapability.ArkUI.ArkUI.Full 78 79| 名称 | 值 | 说明 | 80| -------- | -------- | -------- | 81| FULL_FILLED | 0 | 位置按钮展示填充样式图标。 | 82| LINES | 1 | 位置按钮展示线条样式图标。 | 83 84## LocationDescription枚举说明 85 86**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 87 88**系统能力：** SystemCapability.ArkUI.ArkUI.Full 89 90| 名称 | 值 | 说明 | 91| -------- | -------- | -------- | 92| CURRENT_LOCATION | 0 | 位置按钮的文字描述为“当前位置”。 | 93| ADD_LOCATION | 1 | 位置按钮的文字描述为“添加位置”。 | 94| SELECT_LOCATION | 2 | 位置按钮的文字描述为“选择位置”。 | 95| SHARE_LOCATION | 3 | 位置按钮的文字描述为“共享位置”。 | 96| SEND_LOCATION | 4 | 位置按钮的文字描述为“发送位置”。 | 97| LOCATING | 5 | 位置按钮的文字描述为“定位”。 | 98| LOCATION | 6 | 位置按钮的文字描述为“位置”。 | 99| SEND_CURRENT_LOCATION | 7 | 位置按钮的文字描述为“发送实时位置”。 | 100| RELOCATION | 8 | 位置按钮的文字描述为“重定位”。 | 101| PUNCH_IN | 9 | 位置按钮的文字描述为“打卡定位”。 | 102| CURRENT_POSITION | 10 | 位置按钮的文字描述为“所在位置”。 | 103 104## LocationButtonOnClickResult枚举说明 105 106**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 107 108**系统能力：** SystemCapability.ArkUI.ArkUI.Full 109 110| 名称 | 值 | 说明 | 111| -------- | -------- | -------- | 112| SUCCESS | 0 | 位置按钮点击成功。 | 113| TEMPORARY_AUTHORIZATION_FAILED | 1 | 位置按钮点击后位置权限授权失败。 | 114 115## LocationButtonCallback<sup>18+</sup> 116 117type LocationButtonCallback = (event: ClickEvent, result: LocationButtonOnClickResult, error?: BusinessError<void>) => void 118 119点击位置按钮触发该回调。 120 121**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 122 123**系统能力：** SystemCapability.ArkUI.ArkUI.Full 124 125| 参数名 | 类型 | 必填 | 说明 | 126|------------|------|-------|---------| 127| event | [ClickEvent](ts-universal-events-click.md#clickevent对象说明) |是 |见ClickEvent对象说明。| 128| result | [LocationButtonOnClickResult](#locationbuttononclickresult枚举说明)| 是 | 位置权限的授权结果。| 129| error | [BusinessError<void>](../../apis-basic-services-kit/js-apis-base.md#businesserror)| 否 | 点击按钮时的错误码和错误信息。<br>错误码0表示点击位置按钮授权成功。<br>错误码1表示系统内部错误。<br>错误码2表示属性设置错误，包括但不限于：<br>1. 字体或图标设置过小。<br>2. 字体或图标与背托颜色相近。<br>3. 字体或图标颜色过于透明。<br>4. padding为负值。<br>5. 按钮被其他组件或窗口遮挡。<br>6. 文本超出背托范围。<br>7. 按钮超出窗口或屏幕。<br>8. 按钮整体尺寸过大。<br>9. 按钮文本被截断，显示不全。<br>10. 相关属性设置影响安全控件显示。| 130 131## 属性 132 133不支持通用属性，仅继承[安全控件通用属性](ts-securitycomponent-attributes.md#属性)。 134 135## 事件 136 137不支持通用事件，仅支持以下事件： 138 139### onClick 140 141onClick(event: LocationButtonCallback) 142 143点击动作触发该回调。 144 145**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 146 147**系统能力：** SystemCapability.ArkUI.ArkUI.Full 148 149**参数：** 150 151| 参数名 | 类型 | 必填 | 说明 | 152|------------|------|-------|---------| 153| event | [LocationButtonCallback](#locationbuttoncallback18) |是 |见LocationButtonCallback。<br>在API10-17时，参数类型为：(event: [ClickEvent](ts-universal-events-click.md#clickevent对象说明), result: [LocationButtonOnClickResult](#locationbuttononclickresult枚举说明)) => void。<br>从API18开始，变更为LocationButtonCallback。| 154 155## 示例 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 // 默认参数下，图标、文字、背景都存在。 178 LocationButton().onClick(this.handleLocationButtonClick) 179 // 传入参数即表示元素存在，不传入的参数表示元素不存在，如果不传入buttonType，会默认添加ButtonType.Capsule配置，显示图标+背景。 180 LocationButton({ icon: LocationIconStyle.LINES }) 181 // 只显示图标+背景，如果设置背景色高八位的α值低于0x1A，则会被系统强制调整为0xFF。 182 LocationButton({ icon: LocationIconStyle.LINES, buttonType: ButtonType.Capsule }) 183 .backgroundColor(0x10007dff) 184 // 图标、文字、背景都存在，如果设置背景色高八位的α值低于0x1A，则会被系统强制调整为0xFF。 185 LocationButton({ 186 icon: LocationIconStyle.LINES, 187 text: LocationDescription.CURRENT_LOCATION, 188 buttonType: ButtonType.Capsule 189 }) 190 // 图标、文字、背景都存在，如果设置宽度小于当前属性组合下允许的最小宽度时，宽度仍为设置值，此时按钮文本信息会自动换行，以保证安全控件显示的完整性。 191 LocationButton({ 192 icon: LocationIconStyle.LINES, 193 text: LocationDescription.CURRENT_LOCATION, 194 buttonType: ButtonType.Capsule 195 }) 196 .fontSize(16) 197 .width(30) 198 // 图标、文字、背景都存在，如果设置宽度小于当前属性组合下允许的最小宽度时，宽度仍为设置值，此时按钮文本信息会自动换行，以保证安全控件显示的完整性。 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 // 图标、文字、背景都存在，如果设置宽度小于当前属性组合下允许的最小宽度时，宽度仍为设置值，此时按钮文本信息会自动换行，以保证安全控件显示的完整性。 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
