harmony 鸿蒙SaveButton

2025-06-12
浏览 (4)

SaveButton

安全控件的保存控件。用户点击保存控件，应用可以临时获取存储权限，而不需要权限弹框授权确认。

说明：

该组件从API version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

子组件

不支持。

接口

SaveButton

SaveButton()

默认创建带有图标、文本、背景的保存控件。

为避免控件样式不合法导致授权失败，请开发者先了解安全控件样式的约束与限制。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

SaveButton

SaveButton(options: SaveButtonOptions)

创建包含指定元素的保存控件。

为避免控件样式不合法导致授权失败，请开发者先了解安全控件样式的约束与限制。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
options	SaveButtonOptions	是	创建包含指定元素的保存控件。

SaveButtonOptions

用于指定保存控件的图标、文本等指定元素。

说明：

icon或text需至少传入一个。

如果icon、text都不传入，SaveButton中的options参数不起效，创建的SaveButton为默认样式，默认样式：

SaveIconStyle默认样式为FULL_FILLED；

SaveDescription默认样式为DOWNLOAD；

ButtonType默认样式为Capsule。 - icon、text、buttonType不支持动态修改。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
icon	SaveIconStyle	否	设置保存控件的图标风格。不传入该参数表示没有图标。
text	SaveDescription	否	设置保存控件的文本描述。不传入该参数表示没有文字描述。
buttonType	ButtonType	否	设置保存控件的背景样式。不传入该参数，系统默认提供Capsule类型按钮。

SaveIconStyle枚举说明

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	值	说明
FULL_FILLED	0	保存控件展示填充样式图标。
LINES	1	保存控件展示线条样式图标。

SaveDescription枚举说明

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	值	说明
DOWNLOAD	0	保存控件的文字描述为“下载”。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
DOWNLOAD_FILE	1	保存控件的文字描述为“下载文件”。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
SAVE	2	保存控件的文字描述为“保存”。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
SAVE_IMAGE	3	保存控件的文字描述为“保存图片”。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
SAVE_FILE	4	保存控件的文字描述为“保存文件”。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
DOWNLOAD_AND_SHARE	5	保存控件的文字描述为“下载分享”。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
RECEIVE	6	保存控件的文字描述为“接收”。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
CONTINUE_TO_RECEIVE	7	保存控件的文字描述为“继续接收”。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
SAVE_TO_GALLERY¹²⁺	8	保存控件的文字描述为“保存至图库”。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
EXPORT_TO_GALLERY¹²⁺	9	保存控件的文字描述为“导出”。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
QUICK_SAVE_TO_GALLERY¹²⁺	10	保存控件的文字描述为“快速保存图片”。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
RESAVE_TO_GALLERY¹²⁺	11	保存控件的文字描述为“重新保存”。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
SAVE_ALL¹⁸⁺	12	保存控件的文字描述为“全部保存”。原子化服务API：从API version 18开始，该接口支持在原子化服务中使用。

SaveButtonOnClickResult枚举说明

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	值	说明
SUCCESS	0	保存控件点击后权限授权成功。
TEMPORARY_AUTHORIZATION_FAILED	1	保存控件点击后权限授权失败。

SaveButtonTipPosition²⁰⁺枚举说明

原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	值	说明
ABOVE_BOTTOM	0	保存控件系统提示弹框距离屏幕底部80vp，有导航栏时距离导航栏80vp。
BELOW_TOP	1	保存控件系统提示弹框距离屏幕顶部112vp。

SaveButtonCallback¹⁸⁺

type SaveButtonCallback = (event: ClickEvent, result: SaveButtonOnClickResult, error?: BusinessError<void>) => void

点击保存控件触发该回调。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数名	类型	必填	说明
event	ClickEvent	是	见ClickEvent对象说明。
result	SaveButtonOnClickResult	是	存储权限的授权结果，授权时长为10秒，即触发点击后，可以在10秒之内不限制次数的调用特定媒体库接口，超出10秒的调用会鉴权失败。
error	BusinessError<void>	否	点击按钮时的错误码和错误信息。错误码0表示点击保存控件授权成功。错误码1表示系统内部错误。错误码2表示属性设置错误，包括但不限于： 1. 字体或图标设置过小。 2. 字体或图标与背托颜色相近。 3. 字体或图标颜色过于透明。 4. padding为负值。 5. 按钮被其他组件或窗口遮挡。 6. 文本超出背托范围。 7. 按钮超出窗口或屏幕。 8. 按钮整体尺寸过大。 9. 按钮文本被截断，显示不全。 10. 相关属性设置影响安全控件显示。

SaveButtonAttribute

SaveButtonAttribute提供设置自定义图标（setIcon）、自定义文本（setText）、图标尺寸设置（iconSize）、图标圆角设置（iconBorderRadius），是否显示按压态（stateEffect）以及系统提示弹框位置设置的方法属性。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

setIcon²⁰⁺

setIcon(icon: Resource): SaveButtonAttribute

设置保存控件的图标。

需要权限：ohos.permission.CUSTOMIZE_SAVE_BUTTON

原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
icon	Resource	是	自定义图标资源信息，仅支持Resource类型的数据源。可支持的图片格式：png、jpg、jpeg、bmp、svg、webp、gif和heif等，支持的图片格式范围见Image。当资源为非图片资源或不支持的格式时，图标显示为空白。如果应用无ohos.permission.CUSTOMIZE_SAVE_BUTTON权限，则自定义图标设置不生效，保存控件保持默认样式。详见SaveButtonOptions说明。

返回值：

类型	说明
SaveButtonAttribute	返回保存控件的属性。

setText²⁰⁺

setText(text: string|Resource): SaveButtonAttribute

设置保存控件的文本。

需要权限：ohos.permission.CUSTOMIZE_SAVE_BUTTON

原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
text	string \|Resource	是	自定义文本信息。如果应用无ohos.permission.CUSTOMIZE_SAVE_BUTTON权限，则自定义文本设置不生效，保存控件保持默认样式。详见SaveButtonOptions说明。

返回值：

类型	说明
SaveButtonAttribute	返回保存控件的属性。

iconSize²⁰⁺

iconSize(size: Dimension|SizeOptions): SaveButtonAttribute

设置保存控件的图标尺寸。

原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
size	Dimension \|SizeOptions	是	图标尺寸，不支持设置百分比字符串。 - 保存控件提供的系统图标，宽高默认值均为16vp。宽高设置值不一致时，取其中最小值作为宽高值；宽高仅设置其中一个值时，取该值作为宽高值。 - 对于自定义图标，宽默认值为16vp，高根据自定义图标实际尺寸做自适应处理。宽高仅设置其中一个值时，未设置的另一个值做自适应处理；宽高均设置时按照指定宽高生效，当设置的宽高比例与自定义图标的宽高比例不一致时，图片被截断。

返回值：

类型	说明
SaveButtonAttribute	返回保存控件的属性。

iconBorderRadius²⁰⁺

iconBorderRadius(radius: Dimension|BorderRadiuses): SaveButtonAttribute

设置保存控件图标的边框圆角半径。

需要权限：ohos.permission.CUSTOMIZE_SAVE_BUTTON

原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
radius	Dimension \|BorderRadiuses	是	保存控件边框圆角半径，支持设置四个圆角。如果应用无ohos.permission.CUSTOMIZE_SAVE_BUTTON权限，则圆角半径设置不生效。

返回值：

类型	说明
SaveButtonAttribute	返回保存控件的属性。

stateEffect²⁰⁺

stateEffect(enabled: boolean): SaveButtonAttribute

设置保存控件的按压效果。

需要权限：ohos.permission.CUSTOMIZE_SAVE_BUTTON

原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
enabled	boolean	是	表示是否开启按压效果，true表示保存控件按压时显示按压效果，false表示保存控件按压时不显示按压效果。默认值：true。如果应用无ohos.permission.CUSTOMIZE_SAVE_BUTTON权限，按压效果设置不生效。

返回值：

类型	说明
SaveButtonAttribute	返回保存控件的属性。

tipPosition²⁰⁺

tipPosition(position: SaveButtonTipPosition): SaveButtonAttribute

设置保存控件系统提示弹框的位置信息。

原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
position	SaveButtonTipPosition	是	保存控件系统提示弹框的显示位置信息。默认值：SaveButtonTipPosition.ABOVE_BOTTOM。适用场景：使用保存控件自定义图标和文本。

返回值：

类型	说明
SaveButtonAttribute	返回保存控件的属性。

属性

不支持通用属性，仅继承安全控件通用属性。

事件

不支持通用事件，仅支持以下事件：

onClick

onClick(event: SaveButtonCallback)

点击动作触发该回调。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
event	SaveButtonCallback	是	见SaveButtonCallback。在API10-17时，参数类型为：(event: ClickEvent, result: SaveButtonOnClickResult) => void。从API18开始，变更为SaveButtonCallback。

示例1

// xxx.ets
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { fileIo } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  handleSaveButtonClick: SaveButtonCallback =
    async (event: ClickEvent, result: SaveButtonOnClickResult, error?: BusinessError<void>) => {
      if (result == SaveButtonOnClickResult.SUCCESS) {
        try {
          const context = this.getUIContext().getHostContext();
          let helper = photoAccessHelper.getPhotoAccessHelper(context);
          // onClick触发后10秒内通过createAsset接口创建图片文件，10秒后createAsset权限收回。
          let uri = await helper.createAsset(photoAccessHelper.PhotoType.IMAGE, 'png');
          // 使用uri打开文件，可以持续写入内容，写入过程不受时间限制。
          let file = await fileIo.open(uri, fileIo.OpenMode.READ_WRITE|fileIo.OpenMode.CREATE);
          // 写入文件
          await fileIo.write(file.fd, "context");
          // 关闭文件
          await fileIo.close(file.fd);
        } catch (error) {
          console.error("error is " + JSON.stringify(error));
        }
      } else {
        console.error("errCode: " + error?.code);
        console.error("errMessage: " + error?.message);
      }
    };

  build() {
    Row() {
      Column({ space: 10 }) {
        // 默认参数下，图标、文字、背景都存在。
        SaveButton().onClick((this.handleSaveButtonClick))
        // 传入参数即表示元素存在，不传入的参数表示元素不存在，如果不传入buttonType，会默认添加ButtonType.Capsule配置，显示图标+背景。
        SaveButton({ icon: SaveIconStyle.FULL_FILLED })
        // 只显示图标+背景，如果设置背景色高八位的α值低于0x1A，则会被系统强制调整为0xFF。
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, buttonType: ButtonType.Capsule })
          .backgroundColor(0x10007dff)
        // 图标、文字、背景都存在，如果设置背景色高八位的α值低于0x1A，则会被系统强制调整为0xFF。
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD, buttonType: ButtonType.Capsule })
        // 图标、文字、背景都存在，如果设置宽度小于当前属性组合下允许的最小宽度时，宽度仍为设置值，此时按钮文本信息会自动换行，以保证安全控件显示的完整性。
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD, buttonType: ButtonType.Capsule })
          .fontSize(16)
          .width(30)
        // 图标、文字、背景都存在，如果设置宽度小于当前属性组合下允许的最小宽度时，宽度仍为设置值，此时按钮文本信息会自动换行，以保证安全控件显示的完整性。
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD, buttonType: ButtonType.Capsule })
          .fontSize(16)
          .size({ width: 30, height: 30 })
        // 图标、文字、背景都存在，如果设置宽度小于当前属性组合下允许的最小宽度时，宽度仍为设置值，此时按钮文本信息会自动换行，以保证安全控件显示的完整性。
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD, buttonType: ButtonType.Capsule })
          .fontSize(16)
          .constraintSize({
            minWidth: 0,
            maxWidth: 30,
            minHeight: 0,
            maxHeight: 30
          })
      }.width('100%')
    }.height('100%')
  }
}

zh-cn_image_0000001643320073

示例2

应用需要申请权限：ohos.permission.CUSTOMIZE_SAVE_BUTTON

// xxx.ets
@Entry
@Component
struct SetIcon {
  build() {
    Row() {
      Column({ space: 10 }) {
        // 设置图标为resource类型，有权限时显示设置的图标。
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .setIcon($r('app.media.startIcon'))
        // 设置文本为string类型，有权限时显示设置的文本。
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .setText("保存控件设置文本")
        // 设置文本为resource类型，有权限时显示设置的资源文本。
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .setText($r('app.string.app_name'))
        // 设置保存控件图标大小，入参为Dimension类型。
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .iconSize(28)
        // 设置保存控件的默认图标大小，入参为SizeOptions类型。将默认图标设置为宽高中的较小值。
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .iconSize({ width: 20, height: 40 })
        // 设置保存控件的自定义图标大小，入参为SizeOptions类型。图片按设置的宽高显示。
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .setIcon($r('app.media.startIcon'))
          .iconSize({ width: 30, height: 40 })
        // 设置保存控件的自定义图标大小，入参为SizeOptions类型且只设置一个值，宽高中的另一个会按原图比例自适应显示。
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .setIcon($r('app.media.startIcon'))
          .iconSize({ width: 40 })
        // 设置保存控件的图标圆角，入参为Dimension类型。图片四个圆角的半径均为入参大小。
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .backgroundColor(Color.Orange)
          .setIcon($r('app.media.background'))
          .iconSize(30)
          .iconBorderRadius(6)
        // 设置正方形图标圆角大于边长一半时图标显示为圆形。
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, buttonType: ButtonType.Circle })
          .backgroundColor(Color.Orange)
          .setIcon($r('app.media.foreground'))
          .iconSize(30)
          .iconBorderRadius(30)
          .padding(0)
        // 自定义图标通过iconBorderRadius设置为圆形，背托设置为透明色并设置边框。
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, buttonType:ButtonType.Circle })
          .setIcon($r('app.media.background'))
          .backgroundColor(Color.Transparent)
          .iconSize(40)
          .iconBorderRadius(30)
          .borderWidth(1)
          .borderColor(Color.Black)
          .borderStyle(BorderStyle.Solid)
          .padding(10)
        // 设置保存控件的图标圆角，入参为BorderRadiuses类型。图片四个圆角的半径分别为对应入参大小，未设置的无圆角。
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .backgroundColor(Color.Orange)
          .setIcon($r('app.media.background'))
          .iconSize(30)
          .iconBorderRadius({ topLeft: 10, topRight: 16, bottomRight: 20 })
        // 设置保存控件的按压特效为无按压特效。
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .stateEffect(false)
        // 设置保存控件的安全保存提示弹窗位置。
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .tipPosition(SaveButtonTipPosition.BELOW_TOP)
          .setText('保存控件系统提示弹在上方')
      }.width('100%')
    }.height('100%')
  }
}

custom_savebutton

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ComposeListItem

harmony 鸿蒙ComposeTitleBar

harmony 鸿蒙advanced.Counter

harmony 鸿蒙弹出框 (Dialog)

harmony 鸿蒙DialogV2

0 赞

所属分类： 后端技术
本文标签：
版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/u3Kvus

harmony 鸿蒙SaveButton

SaveButton

子组件

接口

SaveButton

SaveButton

SaveButtonOptions

SaveIconStyle枚举说明

SaveDescription枚举说明

SaveButtonOnClickResult枚举说明

SaveButtonTipPosition²⁰⁺枚举说明

SaveButtonCallback¹⁸⁺

SaveButtonAttribute

setIcon²⁰⁺

setText²⁰⁺

iconSize²⁰⁺

iconBorderRadius²⁰⁺

stateEffect²⁰⁺

tipPosition²⁰⁺

属性

事件

onClick

示例1

示例2

你可能感兴趣的鸿蒙文章

热门推荐

标签云

最新文章

本文目录

harmony 鸿蒙SaveButton

SaveButton

子组件

接口

SaveButton

SaveButton

SaveButtonOptions

SaveIconStyle枚举说明

SaveDescription枚举说明

SaveButtonOnClickResult枚举说明

SaveButtonTipPosition20+枚举说明

SaveButtonCallback18+

SaveButtonAttribute

setIcon20+

setText20+

iconSize20+

iconBorderRadius20+

stateEffect20+

tipPosition20+

属性

事件

onClick

示例1

示例2

你可能感兴趣的鸿蒙文章

热门推荐

标签云

最新文章

本文目录

SaveButtonTipPosition²⁰⁺枚举说明

SaveButtonCallback¹⁸⁺

setIcon²⁰⁺

setText²⁰⁺

iconSize²⁰⁺

iconBorderRadius²⁰⁺

stateEffect²⁰⁺

tipPosition²⁰⁺