SaveButton

Overview

SaveButton is a system API for the save security control. It applies to scenarios where apps need temporary media library access permissions to save images or videos, such as saving images to albums and exporting media content.

After the SaveButton component is integrated into an app, a confirmation dialog will appear when the user taps the component for the first time. If the user allows access, the app obtains temporary authorization to call media library APIs. For related APIs, see Interface (PhotoAccessHelper). If the user denies access or dismisses the dialog, authorization will not be granted for this operation. No dialog box will appear for subsequent uses.

For API version 19 and earlier, the authorization duration is 10 seconds. For API version 20 and later, the authorization duration is 1 minute.

You need to call media library APIs to obtain file handles and complete temporary-authorized operations such as creating media resources within the authorization period. After authorization expires, existing file handles acquired during the valid period remain available for read and write operations.

Key Classes and APIs

Key Enums

• SaveIconStyle: Enumeration of icon styles for the save button. Specifies the icon style displayed.
• SaveDescription: Enumeration of text descriptions for the save button. Specifies the text description displayed.
• SaveButtonOnClickResult: Enumeration of click results for the save button. Indicates whether authorization succeeds after a click.

Key APIs

• SaveButtonOptions: Configuration object for the save button. Defines properties including icon, text and button type.
• SaveButtonCallback: Callback for save button clicks. Returns click events, authorization results and error messages.

Child Components

Not supported

APIs

SaveButton

SaveButton()

Creates a SaveButton component with an icon, text, and background. When the user taps the save button for the first time, a dialog will pop up. Once the user grants permission, the app obtains temporary authorization to access media library APIs. No dialog box will appear for subsequent uses.

In API version 19 or earlier, authorization remains valid for 10 seconds. After authorization expires, existing file handles acquired during the valid period remain available for read and write operations.

In API version 20 or later, authorization remains valid for 1 minute. After authorization expires, existing file handles acquired during the valid period remain available for read and write operations.

You may want to learn the restrictions on security component styles to avoid authorization failures caused by incompliant styles.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

SaveButton

SaveButton(options: SaveButtonOptions)

Creates a save button with the specified icon, text and button type. When the user taps the save button for the first time, a dialog will pop up. Once the user grants permission, the app obtains temporary authorization to access media library APIs. No dialog box will appear for subsequent uses.

In API version 19 or earlier, authorization remains valid for 10 seconds. After authorization expires, existing file handles acquired during the valid period remain available for read and write operations.

In API version 20 or later, authorization remains valid for 1 minute. After authorization expires, existing file handles acquired during the valid period remain available for read and write operations.

You may want to learn the restrictions on security component styles to avoid authorization failures caused by incompliant styles.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

SaveButtonOptions

Defines options for the save button, including icon, text, and button type.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

SaveIconStyle

Enumerates icon styles of the SaveButton component.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

SaveDescription

Enumerates text descriptions of the SaveButton component.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

SaveButtonOnClickResult

Enumerates the authorization results after the SaveButton component is tapped.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

SaveButtonCallback¹⁸⁺

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

Triggered when the SaveButton component is clicked.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Attributes

Universal attributes are not supported. This component supports the attributes listed below, as well as universal attributes of security components.

setIcon²⁰⁺

setIcon(icon: Resource)

Sets the icon of the SaveButton component.

Model restriction: This API can be used only in the stage model.

Required permissions: ohos.permission.CUSTOMIZE_SAVE_BUTTON

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

setText²⁰⁺

setText(text: string | Resource)

Sets the text of the SaveButton component.

Model restriction: This API can be used only in the stage model.

Required permissions: ohos.permission.CUSTOMIZE_SAVE_BUTTON

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

iconSize²⁰⁺

iconSize(size: Dimension | SizeOptions)

Sets the icon size of the SaveButton component.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

iconBorderRadius²⁰⁺

iconBorderRadius(radius: Dimension | BorderRadiuses)

Sets the corner radius of the SaveButton component.

Model restriction: This API can be used only in the stage model.

Required permissions: ohos.permission.CUSTOMIZE_SAVE_BUTTON

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

stateEffect²⁰⁺

stateEffect(enabled: boolean)

Sets the press effect of the SaveButton component.

Model restriction: This API can be used only in the stage model.

Required permissions: ohos.permission.CUSTOMIZE_SAVE_BUTTON

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

userCancelEvent²¹⁺

userCancelEvent(enabled: boolean)

Sets the user authorization cancellation event for the SaveButton component. This API can be used to distinguish between user cancellation and authorization failures for differentiated service logic, such as logging user behaviors or prompting users to retry.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 21.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

symbolIconColor

symbolIconColor(color: Array<ResourceColor>)

Sets the color of the symbol icon for the save button.

• Before calling this method, you need to call setIcon to configure a symbol-style icon resource (i.e., $r('sys.symbol.xxx')).
• If no symbol icon is set, the color set via this method does not take effect.
• It is recommended that you use this API together with symbolRenderingStrategy to achieve different rendering effects.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

Required permissions: ohos.permission.CUSTOMIZE_SAVE_BUTTON

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

symbolFontWeight

symbolFontWeight(fontWeight: number | FontWeight | string | Resource)

Sets the font weight of the symbol icon for the save button.

• Before calling this method, you need to call setIcon to configure a symbol-style icon resource (i.e., $r('sys.symbol.xxx')).
• If no symbol icon is configured, the font weight setting will not apply.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

Required permissions: ohos.permission.CUSTOMIZE_SAVE_BUTTON

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

symbolRenderingStrategy

symbolRenderingStrategy(strategy: SymbolRenderingStrategy)

Sets the rendering strategy for the symbol icon of the save button.

• Before calling this method, you need to call setIcon to configure a symbol-style icon resource (i.e., $r('sys.symbol.xxx')).
• The configured rendering strategy will not apply if no symbol icon is set.
• When this parameter is used together with symbolIconColor, the rendering strategy determines how the color array is applied.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

Required permissions: ohos.permission.CUSTOMIZE_SAVE_BUTTON

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

The figure below shows the effects of different rendering strategies.

Events

Only the following events are supported.

onClick

onClick(event: SaveButtonCallback)

Triggered when the SaveButton component is clicked. When a user clicks the save button for the first time, an authorization dialog box is displayed. If the user allows authorization, the app obtains temporary access to media library APIs. For details about the authorization duration, see the description of the SaveButton constructor. Authorization fails if the user declines authorization or closes the dialog box.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Example 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) => {
      if (result === SaveButtonOnClickResult.SUCCESS) {
        try {
          // Obtain the app context.
          const context = this.getUIContext().getHostContext();
          // Create an instance of the image access helper.
          let helper = photoAccessHelper.getPhotoAccessHelper(context);
          // Create an image resource and obtain its URI.
          let uri = await helper.createAsset(photoAccessHelper.PhotoType.IMAGE, 'png');
          // Open the file based on its URI. The write process is not time bound.
          let file = await fileIo.open(uri, fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE);
          // Write to the file.
          await fileIo.write(file.fd, "context");
          // Close the file.
          await fileIo.close(file.fd);
        } catch (err) {
          console.error(`errCode: ${err.code}, errMessage: ${err.message}`);
        }
      } else if (result === SaveButtonOnClickResult.CANCELED_BY_USER) {
        console.info("errCode: " + error?.code);
        console.info("errMessage: " + error?.message);
      } else {
        console.error(`errCode: ${error.code}, errMessage: ${error.message}`);
      }
    };

  build() {
    Row() {
      Column({ space: 10 }) {
        // Create a default button with an icon, text, and background.
        SaveButton().onClick((this.handleSaveButtonClick))
        // Whether the button has an icon, text, and background depends on whether the corresponding parameter is passed in. If buttonType is not passed in, the button uses the ButtonType.Capsule settings.
        SaveButton({ icon: SaveIconStyle.FULL_FILLED })
        // 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.
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, buttonType: ButtonType.Capsule })
          .backgroundColor(0x10007dff)
        // 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.
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD, buttonType: ButtonType.Capsule })
        // 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.
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD, buttonType: ButtonType.Capsule })
          .fontSize(16)
          .width(30)
        // 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.
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD, buttonType: ButtonType.Capsule })
          .fontSize(16)
          .size({ width: 30, height: 30 })
        // 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.
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD, buttonType: ButtonType.Capsule })
          .fontSize(16)
          .constraintSize({
            minWidth: 0,
            maxWidth: 30,
            minHeight: 0,
            maxHeight: 30
          })
        // Configure the SaveButton component to receive the user authorization cancellation event.
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .onClick((this.handleSaveButtonClick))
          .userCancelEvent(true)
      }.width('100%')
    }.height('100%')
  }
}

Example 2

The app requires the ohos.permission.CUSTOMIZE_SAVE_BUTTON permission.

// xxx.ets
@Entry
@Component
struct SetIcon {
  build() {
    Row() {
      Column({ space: 10 }) {
        // Set icon to the resource type. The icon is displayed when permission is granted.
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .setIcon($r('app.media.startIcon'))
        // Set text to the string type. The text is displayed when permission is granted.
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .setText("Set Text for SaveButton")
        // Set text to the resource type. The resource text is displayed when permission is granted.
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .setText($r('app.string.app_name'))
        // Set the save button icon size. The input parameter is of the Dimension type.
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .iconSize(28)
        // Set the default save button icon size. The input parameter is SizeOptions type. It uses smaller value between width and height as the default icon size.
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .iconSize({ width: 20, height: 40 })
        // Set the custom save button icon size. The input parameter is SizeOptions type. The image is displayed based on the configured width and height.
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .setIcon($r('app.media.startIcon'))
          .iconSize({ width: 30, height: 40 })
        // Set the custom save button icon size. The input parameter is of the SizeOptions type with a single value. The image is displayed based on the configured width and height.
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .setIcon($r('app.media.startIcon'))
          .iconSize({ width: 40 })
        // Set the corner radius of the save button icon. The input parameter is of the Dimension type. All four corners use the input parameter value.
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .backgroundColor(Color.Orange)
          .setIcon($r('app.media.background'))
          .iconSize(30)
          .iconBorderRadius(6)
        // Set the square icon corner radius greater than half side length to display as circle.
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, buttonType: ButtonType.Circle })
          .backgroundColor(Color.Orange)
          .setIcon($r('app.media.foreground'))
          .iconSize(30)
          .iconBorderRadius(30)
          .padding(0)
        // Set the custom icon to a circle via iconBorderRadius, with a transparent background and visible border.
        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)
        // Set the border radius for the SaveButton component corners. The input parameter is of the BorderRadiuses type. Each corner uses the corresponding input parameter value. Unset corners remain square.
        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 })
        // Disable the pressed state effect for the SaveButton component.
        SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.DOWNLOAD })
          .stateEffect(false)
      }.width('100%')
    }.height('100%')
  }
}

Example 3

The app requires the ohos.permission.CUSTOMIZE_SAVE_BUTTON permission.

// xxx.ets
@Entry
@Component
struct Index {

  build() {
    Row() {
      Column({ space: 10 }) {
        // Set the symbol icon for the save button.
        SaveButton()
          .setIcon($r('sys.symbol.ohos_folder_badge_plus'))

        // Set the symbol icon color to green and white, and apply the single-color rendering strategy.
        SaveButton()
          .setIcon($r('sys.symbol.ohos_folder_badge_plus'))
          .symbolIconColor([Color.Green, Color.White])
          .symbolRenderingStrategy(SymbolRenderingStrategy.SINGLE)

        // Set the symbol icon color to green and white, and apply the multi-color rendering strategy.
        SaveButton()
          .setIcon($r('sys.symbol.ohos_folder_badge_plus'))
          .symbolIconColor([Color.Green, Color.White])
          .symbolRenderingStrategy(SymbolRenderingStrategy.MULTIPLE_COLOR)

        // Set the symbol icon color to green, and apply the multi-color rendering strategy.
        SaveButton()
          .setIcon($r('sys.symbol.ohos_folder_badge_plus'))
          .symbolIconColor([Color.Green])
          .symbolRenderingStrategy(SymbolRenderingStrategy.MULTIPLE_COLOR)

        // Set the symbol icon color to green and white, and apply the layered rendering strategy.
        SaveButton()
          .setIcon($r('sys.symbol.ohos_folder_badge_plus'))
          .symbolIconColor([Color.Green, Color.White])
          .symbolRenderingStrategy(SymbolRenderingStrategy.MULTIPLE_OPACITY)

        // Set the font weight of the symbol icon to Lighter.
        SaveButton()
          .setIcon($r('sys.symbol.ohos_folder_badge_plus'))
          .symbolIconColor([Color.Green])
          .symbolRenderingStrategy(SymbolRenderingStrategy.MULTIPLE_COLOR)
          .symbolFontWeight(FontWeight.Lighter)

        // Set the font weight of the symbol icon to Bolder.
        SaveButton()
          .setIcon($r('sys.symbol.ohos_folder_badge_plus'))
          .symbolIconColor([Color.Green])
          .symbolRenderingStrategy(SymbolRenderingStrategy.MULTIPLE_COLOR)
          .symbolFontWeight(FontWeight.Bolder)
      }
      .width('100%')
    }
    .height('100%')
  }
}