1# SaveButton 2 3<!--Kit: ArkUI--> 4<!--Subsystem: Security--> 5<!--Owner: @harylee--> 6<!--Designer: @linshuqing; @hehehe-li--> 7<!--Tester: @leiyuqian--> 8<!--Adviser: @zengyawen--> 9 10安全控件的保存控件。用户点击保存控件，应用可以临时获取存储权限，而不需要权限弹框授权确认。 11 12> **说明：** 13> 14> 该组件从API version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 15 16## 子组件 17 18不支持。 19 20## 接口 21 22### SaveButton 23 24SaveButton() 25 26默认创建带有图标、文本、背景的保存控件。 27 28为避免控件样式不合法导致授权失败，请开发者先了解安全控件样式的[约束与限制](../../../security/AccessToken/security-component-overview.md#约束与限制)。 29 30**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 31 32**系统能力：** SystemCapability.ArkUI.ArkUI.Full 33 34### SaveButton 35 36SaveButton(options: SaveButtonOptions) 37 38创建包含指定元素的保存控件。 39 40为避免控件样式不合法导致授权失败，请开发者先了解安全控件样式的[约束与限制](../../../security/AccessToken/security-component-overview.md#约束与限制)。 41 42**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 43 44**系统能力：** SystemCapability.ArkUI.ArkUI.Full 45 46**参数：** 47 48| 参数名 | 类型 | 必填 | 说明 | 49| -------- | -------- | -------- | -------- | 50| options | [SaveButtonOptions](#savebuttonoptions) | 是 | 创建包含指定元素的保存控件。 | 51 52## SaveButtonOptions 53 54用于指定保存控件的图标、文本等指定元素。 55 56> **说明：** 57> 58> - icon或text需至少传入一个。<br> 59> - 如果icon、text都不传入，[SaveButton](#savebutton-1)中的options参数不起效，创建的SaveButton为默认样式，默认样式： 60> 61> SaveIconStyle默认样式为FULL_FILLED； 62> 63> SaveDescription默认样式为DOWNLOAD； 64> 65> ButtonType默认样式为Capsule。 66> - icon、text、buttonType不支持动态修改。 67 68**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 69 70**系统能力：** SystemCapability.ArkUI.ArkUI.Full 71 72| 名称 | 类型 | 只读 | 可选 | 说明 | 73| -------- | -------- | -------- | -------- | -------- | 74| icon | [SaveIconStyle](#saveiconstyle枚举说明) | 否 | 是 | 设置保存控件的图标风格。<br/>不传入该参数表示没有图标。 | 75| text | [SaveDescription](#savedescription枚举说明) | 否 | 是 | 设置保存控件的文本描述。<br/>不传入该参数表示没有文字描述。 | 76| buttonType | [ButtonType](ts-securitycomponent-attributes.md#buttontype枚举说明) | 否 | 是 | 设置保存控件的背景样式。<br/>不传入该参数，系统默认提供Capsule类型按钮。 | 77 78## SaveIconStyle枚举说明 79 80保存控件的图标风格。 81 82**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 83 84**系统能力：** SystemCapability.ArkUI.ArkUI.Full 85 86| 名称 | 值 | 说明 | 87| -------- | -------- | -------- | 88| FULL_FILLED | 0 | 保存控件展示填充样式图标。 | 89| LINES | 1 | 保存控件展示线条样式图标。 | 90 91## SaveDescription枚举说明 92 93保存控件的文本描述。 94 95**系统能力：** SystemCapability.ArkUI.ArkUI.Full 96 97| 名称 | 值 | 说明 | 98| -------- | -------- | -------- | 99| DOWNLOAD | 0 | 保存控件的文字描述为“下载”。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 100| DOWNLOAD_FILE | 1 | 保存控件的文字描述为“下载文件”。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 101| SAVE | 2 | 保存控件的文字描述为“保存”。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 102| SAVE_IMAGE | 3 | 保存控件的文字描述为“保存图片”。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 103| SAVE_FILE | 4 | 保存控件的文字描述为“保存文件”。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 104| DOWNLOAD_AND_SHARE | 5 | 保存控件的文字描述为“下载分享”。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 105| RECEIVE | 6 | 保存控件的文字描述为“接收”。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 106| CONTINUE_TO_RECEIVE | 7 | 保存控件的文字描述为“继续接收”。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 107| SAVE_TO_GALLERY<sup>12+</sup> | 8 | 保存控件的文字描述为“保存至图库”。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 108| EXPORT_TO_GALLERY<sup>12+</sup> | 9 | 保存控件的文字描述为“导出”。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 109| QUICK_SAVE_TO_GALLERY<sup>12+</sup> | 10 | 保存控件的文字描述为“快速保存图片”。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 110| RESAVE_TO_GALLERY<sup>12+</sup> | 11 | 保存控件的文字描述为“重新保存”。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 111| SAVE_ALL<sup>18+</sup> | 12 | 保存控件的文字描述为“全部保存”。 <br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 112 113## SaveButtonOnClickResult枚举说明 114 115保存控件点击后的授权结果。 116 117**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 118 119**系统能力：** SystemCapability.ArkUI.ArkUI.Full 120 121| 名称 | 值 | 说明 | 122| -------- | -------- | -------- | 123| SUCCESS | 0 | 保存控件点击后权限授权成功。 | 124| TEMPORARY_AUTHORIZATION_FAILED | 1 | 保存控件点击后权限授权失败。 | 125 126## SaveButtonCallback<sup>18+</sup> 127 128type SaveButtonCallback = (event: ClickEvent, result: SaveButtonOnClickResult, error?: BusinessError<void>) => void 129 130点击保存控件触发该回调。 131 132**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 133 134**系统能力：** SystemCapability.ArkUI.ArkUI.Full 135 136**参数：** 137 138| 参数名 | 类型 | 必填 | 说明 | 139|------------|------|-------|---------| 140| event | [ClickEvent](ts-universal-events-click.md#clickevent对象说明) |是 |见ClickEvent对象说明。| 141| result | [SaveButtonOnClickResult](#savebuttononclickresult枚举说明)| 是 | 存储权限的授权结果，授权时长为一分钟，即触发点击后，可以在一分钟之内不限制次数的调用特定媒体库接口，超出一分钟的调用会鉴权失败。| 142| 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. 相关属性设置影响安全控件显示。| 143 144## SaveButtonAttribute 145SaveButtonAttribute提供自定义图标（setIcon）、自定义文本（setText）、图标尺寸（iconSize）、图标圆角（iconBorderRadius），以及按压态效果（stateEffect）等属性设置的方法。 146 147**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 148 149### setIcon<sup>20+</sup> 150 151setIcon(icon: Resource) 152 153设置保存控件的图标。 154 155**需要权限**：ohos.permission.CUSTOMIZE_SAVE_BUTTON 156 157**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 158 159**系统能力：** SystemCapability.ArkUI.ArkUI.Full 160 161**参数：** 162 163| 参数名 | 类型 | 必填 | 说明 | 164|------------|------|-------|---------| 165| icon | [Resource](ts-types.md#resource) |是 |自定义图标资源信息，仅支持Resource类型的数据源。<br/>可支持的图片格式：png、jpg、jpeg、bmp、svg、webp、gif和heif等，支持的图片格式范围见[Image](ts-basic-components-image.md)。当资源为非图片资源或不支持的格式时，图标显示为空白。<br/>如果应用无ohos.permission.CUSTOMIZE_SAVE_BUTTON权限，则自定义图标设置不生效，保存控件保持默认样式。详见[SaveButtonOptions](#savebuttonoptions)说明。| 166 167### setText<sup>20+</sup> 168 169setText(text: string | Resource) 170 171设置保存控件的文本。 172 173**需要权限**：ohos.permission.CUSTOMIZE_SAVE_BUTTON 174 175**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 176 177**系统能力：** SystemCapability.ArkUI.ArkUI.Full 178 179**参数：** 180 181| 参数名 | 类型 | 必填 | 说明 | 182|------------|------|-------|---------| 183| text | string \| [Resource](ts-types.md#resource) |是 |自定义文本信息。<br/>如果应用无ohos.permission.CUSTOMIZE_SAVE_BUTTON权限，则自定义文本设置不生效，保存控件保持默认样式。详见[SaveButtonOptions](#savebuttonoptions)说明。| 184 185### iconSize<sup>20+</sup> 186 187iconSize(size: Dimension | SizeOptions) 188 189设置保存控件的图标尺寸。 190 191**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 192 193**系统能力：** SystemCapability.ArkUI.ArkUI.Full 194 195**参数：** 196 197| 参数名 | 类型 | 必填 | 说明 | 198|------------|------|-------|---------| 199| size | [Dimension](ts-types.md#dimension10) \| [SizeOptions](ts-types.md#sizeoptions) |是 |图标尺寸，不支持设置百分比字符串。宽高默认值均为16vp。<br/>对于保存控件提供的系统图标：<br/>- 使用Dimension类型入参时，宽、高相等，均为设定值。<br/>- 使用SizeOptions类型入参时，若宽、高设定值不一致，则宽、高相等取两者较小值；若仅设定其中一个值，则取该值作为宽、高值。<br/>对于自定义图标：<br/>- 使用Dimension类型入参时，宽、高相等，均为设定值。<br/>- 使用SizeOptions类型入参时，建议同时设定宽和高，此时按照指定宽、高生效；若仅设定其中一个值，则宽高均显示为该设定值。<br/>- 当设定的宽高与自定义图标的宽高比例不一致时，图片按[ImageFit.Cover](ts-appendix-enums.md#imagefit)的方式填充显示区域。| 200 201### iconBorderRadius<sup>20+</sup> 202 203iconBorderRadius(radius: Dimension | BorderRadiuses) 204 205设置保存控件图标的边框圆角半径。 206 207**需要权限**：ohos.permission.CUSTOMIZE_SAVE_BUTTON 208 209**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 210 211**系统能力：** SystemCapability.ArkUI.ArkUI.Full 212 213**参数：** 214 215| 参数名 | 类型 | 必填 | 说明 | 216|------------|------|-------|---------| 217| radius | [Dimension](ts-types.md#dimension10) \| [BorderRadiuses](ts-types.md#borderradiuses9) |是 |保存控件图标的圆角半径，支持设置四个圆角。<br/>如果应用无ohos.permission.CUSTOMIZE_SAVE_BUTTON权限，则图标的圆角半径设置不生效。 | 218 219### stateEffect<sup>20+</sup> 220 221stateEffect(enabled: boolean) 222 223设置保存控件的按压效果。 224 225**需要权限**：ohos.permission.CUSTOMIZE_SAVE_BUTTON 226 227**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 228 229**系统能力：** SystemCapability.ArkUI.ArkUI.Full 230 231**参数：** 232 233| 参数名 | 类型 | 必填 | 说明 | 234|------------|------|-------|---------| 235| enabled | boolean |是 | 表示是否开启按压效果，true表示保存控件按压时显示按压效果，false表示保存控件按压时不显示按压效果。<br/>默认值：true。<br/>如果应用无ohos.permission.CUSTOMIZE_SAVE_BUTTON权限，按压效果设置不生效。 | 236 237## 属性 238 239不支持通用属性，仅继承[安全控件通用属性](ts-securitycomponent-attributes.md)。 240 241## 事件 242 243不支持通用事件，仅支持以下事件： 244 245### onClick 246 247onClick(event: SaveButtonCallback) 248 249点击动作触发该回调。 250 251**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 252 253**系统能力：** SystemCapability.ArkUI.ArkUI.Full 254 255**参数：** 256 257| 参数名 | 类型 | 必填 | 说明 | 258|------------|------|-------|---------| 259| event | [SaveButtonCallback](#savebuttoncallback18) |是 |见SaveButtonCallback。<br>在API10-17时，参数类型为：(event: [ClickEvent](ts-universal-events-click.md#clickevent对象说明), result: [SaveButtonOnClickResult](#savebuttononclickresult枚举说明)) => void。<br>从API18开始，变更为SaveButtonCallback。| 260 261## 示例1 262 263```ts 264// xxx.ets 265import { photoAccessHelper } from '@kit.MediaLibraryKit'; 266import { fileIo } from '@kit.CoreFileKit'; 267import { BusinessError } from '@kit.BasicServicesKit'; 268 269@Entry 270@Component 271struct Index { 272 handleSaveButtonClick: SaveButtonCallback = 273 async (event: ClickEvent, result: SaveButtonOnClickResult, error?: BusinessError) => { 274 if (result === SaveButtonOnClickResult.SUCCESS) { 275 try { 276 const context = this.getUIContext().getHostContext(); 277 let helper = photoAccessHelper.getPhotoAccessHelper(context); 278 // onClick触发后一分钟内通过createAsset接口创建图片文件，一分钟后createAsset权限收回。 279 let uri = await helper.createAsset(photoAccessHelper.PhotoType.IMAGE, 'png'); 280 // 使用uri打开文件，可以持续写入内容，写入过程不受时间限制。 281 let file = await fileIo.open(uri, fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE); 282 // 写入文件 283 await fileIo.write(file.fd, "context"); 284 // 关闭文件 285 await fileIo.close(file.fd); 286 } catch (error) { 287 console.error("error is " + JSON.stringify(error)); 288 } 289 } else { 290 console.error("errCode: " + error?.code); 291 console.error("errMessage: " + error?.message); 292 } 293 }; 294 295 build() { 296 Row() { 297 Column({ space: 10 }) { 298 // 默认参数下，图标、文字、背景都存在。 299 SaveButton().onClick((this.handleSaveButtonClick)) 300 // 传入参数即表示元素存在，不传入的参数表示元素不存在，如果不传入buttonType，会默认添加ButtonType.Capsule配置，显示图标+背景。 301 SaveButton({ icon: SaveIconStyle.FULL_FILLED }) 302 // 只显示图标+背景，如果设置背景色高八位的α值低于0x1a，则会被系统强制调整为0xff。 303 SaveButton({ icon: SaveIconStyle.FULL_FILLED, buttonType: ButtonType.Capsule }) 304 .backgroundColor(0x10007dff) 305 // 图标、文字、背景都存在，如果设置背景色高八位的α值低于0x1a，则会被系统强制调整为0xff。 306 SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD, buttonType: ButtonType.Capsule }) 307 // 图标、文字、背景都存在，如果设置宽度小于当前属性组合下允许的最小宽度时，宽度仍为设置值，此时按钮文本信息会自动换行，以保证安全控件显示的完整性。 308 SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD, buttonType: ButtonType.Capsule }) 309 .fontSize(16) 310 .width(30) 311 // 图标、文字、背景都存在，如果设置宽度小于当前属性组合下允许的最小宽度时，宽度仍为设置值，此时按钮文本信息会自动换行，以保证安全控件显示的完整性。 312 SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD, buttonType: ButtonType.Capsule }) 313 .fontSize(16) 314 .size({ width: 30, height: 30 }) 315 // 图标、文字、背景都存在，如果设置宽度小于当前属性组合下允许的最小宽度时，宽度仍为设置值，此时按钮文本信息会自动换行，以保证安全控件显示的完整性。 316 SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD, buttonType: ButtonType.Capsule }) 317 .fontSize(16) 318 .constraintSize({ 319 minWidth: 0, 320 maxWidth: 30, 321 minHeight: 0, 322 maxHeight: 30 323 }) 324 }.width('100%') 325 }.height('100%') 326 } 327} 328``` 329 330 331 332## 示例2 333 334应用需要申请权限：ohos.permission.CUSTOMIZE_SAVE_BUTTON 335 336```ts 337// xxx.ets 338@Entry 339@Component 340struct SetIcon { 341 build() { 342 Row() { 343 Column({ space: 10 }) { 344 // 设置图标为resource类型，有权限时显示设置的图标。 345 SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD }) 346 .setIcon($r('app.media.startIcon')) 347 // 设置文本为string类型，有权限时显示设置的文本。 348 SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD }) 349 .setText("保存控件设置文本") 350 // 设置文本为resource类型，有权限时显示设置的资源文本。 351 SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD }) 352 .setText($r('app.string.app_name')) 353 // 设置保存控件图标大小，入参为Dimension类型。 354 SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD }) 355 .iconSize(28) 356 // 设置保存控件的默认图标大小，入参为SizeOptions类型。将默认图标设置为宽高中的较小值。 357 SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD }) 358 .iconSize({ width: 20, height: 40 }) 359 // 设置保存控件的自定义图标大小，入参为SizeOptions类型。图片按设置的宽高显示。 360 SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD }) 361 .setIcon($r('app.media.startIcon')) 362 .iconSize({ width: 30, height: 40 }) 363 // 设置保存控件的自定义图标大小，入参为SizeOptions类型且只设置一个值。图片宽高均显示为设置值。 364 SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD }) 365 .setIcon($r('app.media.startIcon')) 366 .iconSize({ width: 40 }) 367 // 设置保存控件的图标圆角，入参为Dimension类型。图片四个圆角的半径均为入参大小。 368 SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD }) 369 .backgroundColor(Color.Orange) 370 .setIcon($r('app.media.background')) 371 .iconSize(30) 372 .iconBorderRadius(6) 373 // 设置正方形图标圆角大于边长一半时图标显示为圆形。 374 SaveButton({ icon: SaveIconStyle.FULL_FILLED, buttonType: ButtonType.Circle }) 375 .backgroundColor(Color.Orange) 376 .setIcon($r('app.media.foreground')) 377 .iconSize(30) 378 .iconBorderRadius(30) 379 .padding(0) 380 // 自定义图标通过iconBorderRadius设置为圆形，背托设置为透明色并设置边框。 381 SaveButton({ icon: SaveIconStyle.FULL_FILLED, buttonType:ButtonType.Circle }) 382 .setIcon($r('app.media.background')) 383 .backgroundColor(Color.Transparent) 384 .iconSize(40) 385 .iconBorderRadius(30) 386 .borderWidth(1) 387 .borderColor(Color.Black) 388 .borderStyle(BorderStyle.Solid) 389 .padding(10) 390 // 设置保存控件的图标圆角，入参为BorderRadiuses类型。图片四个圆角的半径分别为对应入参大小，未设置的无圆角。 391 SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD }) 392 .backgroundColor(Color.Orange) 393 .setIcon($r('app.media.background')) 394 .iconSize(30) 395 .iconBorderRadius({ topLeft: 10, topRight: 16, bottomRight: 20 }) 396 // 设置保存控件的按压特效为无按压特效。 397 SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD }) 398 .stateEffect(false) 399 }.width('100%') 400 }.height('100%') 401 } 402} 403``` 404 405
