1# LocationButton
2
3安全控件的位置控件，用户通过点击该位置按钮，可以临时获取精准定位权限，而不需要权限弹框授权确认。
4
5> **说明：**
6>
7> 该组件从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
8
9## 子组件
10
11不支持。
12
13## 接口
14
15### LocationButton
16
17LocationButton()
18
19默认创建带有图标、文本、背景的位置按钮。
20
21为避免控件样式不合法导致授权失败，请开发者先了解安全控件样式的[约束与限制](../../../security/AccessToken/security-component-overview.md#约束与限制)。
22
23**原子化服务API：** 从API version 11开始，该接口支持在元服务中使用。
24
25**系统能力：** SystemCapability.ArkUI.ArkUI.Full
26
27### LocationButton
28
29LocationButton(options:LocationButtonOptions)
30
31创建包含指定元素的位置按钮。
32
33为避免控件样式不合法导致授权失败，请开发者先了解安全控件样式的[约束与限制](../../../security/AccessToken/security-component-overview.md#约束与限制)。
34
35**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
36
37**系统能力：** SystemCapability.ArkUI.ArkUI.Full
38
39**参数：**
40
41| 参数名 | 类型 | 必填 | 说明 |
42| -------- | -------- | -------- | -------- |
43| options | [LocationButtonOptions](#locationbuttonoptions) | 是 | 创建包含指定元素的位置按钮。 |
44
45## LocationButtonOptions
46
47用于指定位置按钮的图标、文本等指定元素。
48
49> **说明：**
50>
51> - icon或text需至少传入一个。<br>
52> - 如果icon、text都不传入，[LocationButton](#locationbutton-1)中的options参数不起效，创建的LocationButton为默认样式，默认样式：
53>
54>   LocationIconStyle默认样式为LINES；
55>
56>   LocationDescription默认样式为CURRENT_LOCATION；
57>
58>   ButtonType默认样式为Capsule。
59> - icon、text、buttonType不支持动态修改。
60
61**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
62
63**系统能力：** SystemCapability.ArkUI.ArkUI.Full
64
65| 名称 | 类型 | 必填 | 说明 |
66| -------- | -------- | -------- | -------- |
67| icon | [LocationIconStyle](#locationiconstyle枚举说明) | 否 | 设置位置按钮的图标风格。<br/>不传入该参数表示没有图标。 |
68| text | [LocationDescription](#locationdescription枚举说明) | 否 | 设置位置按钮的文本描述。<br/>不传入该参数表示没有文字描述。 |
69| buttonType | [ButtonType](ts-basic-components-button.md#buttontype枚举说明) | 否 | 设置位置按钮的背景样式。<br/>不传入该参数，系统默认提供Capsule类型按钮。 |
70
71## LocationIconStyle枚举说明
72
73**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
74
75**系统能力：** SystemCapability.ArkUI.ArkUI.Full
76
77| 名称 | 值 | 说明 |
78| -------- | -------- | -------- |
79| FULL_FILLED |  0 | 位置按钮展示填充样式图标。 |
80| LINES | 1 | 位置按钮展示线条样式图标。 |
81
82## LocationDescription枚举说明
83
84**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
85
86**系统能力：** SystemCapability.ArkUI.ArkUI.Full
87
88| 名称 | 值 | 说明 |
89| -------- | -------- | -------- |
90| CURRENT_LOCATION | 0 | 位置按钮的文字描述为“当前位置”。 |
91| ADD_LOCATION | 1 | 位置按钮的文字描述为“添加位置”。 |
92| SELECT_LOCATION | 2 | 位置按钮的文字描述为“选择位置”。 |
93| SHARE_LOCATION | 3 | 位置按钮的文字描述为“共享位置”。 |
94| SEND_LOCATION | 4 | 位置按钮的文字描述为“发送位置”。 |
95| LOCATING | 5 | 位置按钮的文字描述为“定位”。 |
96| LOCATION | 6 | 位置按钮的文字描述为“位置”。 |
97| SEND_CURRENT_LOCATION | 7 | 位置按钮的文字描述为“发送实时位置”。 |
98| RELOCATION | 8 | 位置按钮的文字描述为“重定位”。 |
99| PUNCH_IN | 9 | 位置按钮的文字描述为“打卡定位”。 |
100| CURRENT_POSITION | 10 | 位置按钮的文字描述为“所在位置”。 |
101
102## LocationButtonOnClickResult枚举说明
103
104**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
105
106**系统能力：** SystemCapability.ArkUI.ArkUI.Full
107
108| 名称 | 值 | 说明 |
109| -------- | -------- | -------- |
110| SUCCESS | 0 | 位置按钮点击成功。 |
111| TEMPORARY_AUTHORIZATION_FAILED | 1 | 位置按钮点击后位置权限授权失败。 |
112
113## 属性
114
115不支持通用属性，仅继承[安全控件通用属性](ts-securitycomponent-attributes.md#属性)。
116
117## 事件
118
119不支持通用事件，仅支持以下事件：
120
121### onClick
122
123onClick(event: (event: ClickEvent, result: LocationButtonOnClickResult) =&gt; void)
124
125点击动作触发该回调
126
127**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
128
129**系统能力：** SystemCapability.ArkUI.ArkUI.Full
130
131**参数：**
132
133| 参数名 | 类型                   | 必填 | 说明                   |
134|------------|------|-------|---------|
135| event  | [ClickEvent](ts-universal-events-click.md#clickevent对象说明) |是 |见ClickEvent对象说明|
136| result | [LocationButtonOnClickResult](#locationbuttononclickresult枚举说明)| 是 | 位置权限的授权结果。|
137
138## 示例
139
140```ts
141// xxx.ets
142@Entry
143@Component
144struct Index {
145  build() {
146    Row() {
147      Column({space:10}) {
148        // 默认参数下，图标、文字、背景都存在
149        LocationButton().onClick((event: ClickEvent, result: LocationButtonOnClickResult)=>{
150          console.info("result " + result)
151        })
152        // 传入参数即表示元素存在，不传入的参数表示元素不存在，如果不传入buttonType，会默认添加ButtonType.Capsule配置，显示图标+背景。
153        LocationButton({icon:LocationIconStyle.LINES})
154        // 只显示图标+背景，如果设置背景色高八位的α值低于0x1A，则会被系统强制调整为0xFF
155        LocationButton({icon:LocationIconStyle.LINES, buttonType:ButtonType.Capsule})
156          .backgroundColor(0x10007dff)
157        // 图标、文字、背景都存在，如果设置背景色高八位的α值低于0x1A，则会被系统强制调整为0xFF
158        LocationButton({icon:LocationIconStyle.LINES, text:LocationDescription.CURRENT_LOCATION, buttonType:ButtonType.Capsule})
159        // 图标、文字、背景都存在，如果设置宽度小于当前属性组合下允许的最小宽度时，宽度仍为设置值，此时按钮文本信息会自动换行，以保证安全控件显示的完整性。
160        LocationButton({icon:LocationIconStyle.LINES, text:LocationDescription.CURRENT_LOCATION, buttonType:ButtonType.Capsule})
161          .fontSize(16)
162          .width(30)
163        // 图标、文字、背景都存在，如果设置宽度小于当前属性组合下允许的最小宽度时，宽度仍为设置值，此时按钮文本信息会自动换行，以保证安全控件显示的完整性。
164        LocationButton({icon:LocationIconStyle.LINES, text:LocationDescription.CURRENT_LOCATION, buttonType:ButtonType.Capsule})
165          .fontSize(16)
166          .size({width: 30, height: 30})
167        // 图标、文字、背景都存在，如果设置宽度小于当前属性组合下允许的最小宽度时，宽度仍为设置值，此时按钮文本信息会自动换行，以保证安全控件显示的完整性。
168        LocationButton({icon:LocationIconStyle.LINES, text:LocationDescription.CURRENT_LOCATION, buttonType:ButtonType.Capsule})
169          .fontSize(16)
170          .constraintSize({minWidth: 0, maxWidth: 30, minHeight: 0, maxHeight: 30})
171      }.width('100%')
172    }.height('100%')
173  }
174}
175```
176
177![zh-cn_image_0000001593518280](figures/zh-cn_image_0000001593518280.png)
178