大网数据广告活动
OpenHarmony 设备与应用开发

OpenHarmony 中文参考:PasteButton

· 52CE 我爱测

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

PasteButton

安全控件的粘贴控件。用户点击粘贴控件,应用可以临时获取读取剪贴板权限。

说明:

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

子组件

不支持。

接口

PasteButton

PasteButton()

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

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

模型约束: 此接口仅可在Stage模型下使用。

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

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

PasteButton

PasteButton(options: PasteButtonOptions)

创建包含指定元素的粘贴控件。

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

模型约束: 此接口仅可在Stage模型下使用。

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

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

参数:

参数名 类型 必填 说明
options PasteButtonOptions 是 粘贴控件的配置选项,用于指定图标、文本和按钮类型等元素属性。
默认值:
{
icon: PasteIconStyle.LINES,
text: PasteDescription.PASTE,
buttonType: ButtonType.Capsule
}

PasteButtonOptions

用于设置粘贴控件的图标、文本、按钮类型等属性。

说明:

  • icon或text需至少传入一个。

  • 如果icon、text都不传入,PasteButton中的options参数不生效,创建的PasteButton为默认样式。

    • PasteIconStyle默认样式为LINES。

    • PasteDescription默认样式为PASTE。

    • ButtonType默认样式为Capsule。

  • icon、text和buttonType不支持动态修改。这是因为安全控件的样式和属性在创建时已通过系统校验,动态修改可能导致控件样式不符合安全控件规范,从而影响授权的有效性。

模型约束: 此接口仅可在Stage模型下使用。

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

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

名称 类型 只读 可选 说明
icon PasteIconStyle 否 是 设置粘贴控件的图标风格。
不传入该参数表示没有图标。
text PasteDescription 否 是 设置粘贴控件的文本描述。
不传入该参数表示没有文字描述。
buttonType ButtonType 否 是 设置粘贴控件的背景样式。
不传入该参数,系统默认提供Capsule类型按钮。
注意: 按钮样式需符合安全控件约束,详见约束与限制。

属性

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

PasteIconStyle

粘贴控件的图标风格。

模型约束: 此接口仅可在Stage模型下使用。

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

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

名称 值 说明
LINES 0 粘贴控件展示线条样式图标。

PasteDescription

粘贴控件的文本描述。

模型约束: 此接口仅可在Stage模型下使用。

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

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

名称 值 说明
PASTE 0 粘贴控件的文字描述为“粘贴”。

PasteButtonOnClickResult

粘贴控件点击后的授权结果。

模型约束: 此接口仅可在Stage模型下使用。

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

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

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

PasteButtonCallback18+

type PasteButtonCallback = (event: ClickEvent, result: PasteButtonOnClickResult, error?: BusinessError<void>) => void

点击粘贴控件触发该回调。

模型约束: 此接口仅可在Stage模型下使用。

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

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

参数:

参数名 类型 必填 说明
event ClickEvent 是 点击事件对象,包含点击的位置、时间戳、输入设备等信息。详细信息请参考ClickEvent对象说明。
result PasteButtonOnClickResult 是 剪贴板权限的授权结果,授权后可以读取当前剪贴板内容。
error BusinessError<void> 否 点击按钮时的错误码和错误信息。错误码0表示无错误,授权结果需通过result参数判断。
错误码1表示系统内部错误。
错误码2表示属性设置错误,包括但不限于:
1. 字体或图标设置过小。
2. 字体或图标与背托颜色相近。
3. 字体或图标颜色过于透明。
4. padding为负值。
5. 按钮被其他组件或窗口遮挡。
6. 文本超出背托范围。
7. 按钮超出窗口或屏幕。
8. 按钮整体尺寸过大。
9. 按钮文本被截断,显示不全。
10. 部分安全控件相关属性的设置导致控件无法正常显示。

事件

不支持通用事件,仅支持以下事件:

onClick

onClick(event: PasteButtonCallback)

点击动作触发该回调,回调返回授权结果,授权成功后应用可读取剪贴板内容。

模型约束: 此接口仅可在Stage模型下使用。

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

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

参数:

参数名 类型 必填 说明
event PasteButtonCallback 是 点击事件的回调函数,用于处理粘贴控件点击后的授权结果。见PasteButtonCallback。
在API10-17时,参数类型为:(event: ClickEvent, result: PasteButtonOnClickResult) => void。
从API18开始,变更为PasteButtonCallback。

示例

// xxx.ets

@Entry
@Component
struct Index {
  handlePasteButtonClick: PasteButtonCallback =
    (event: ClickEvent, result: PasteButtonOnClickResult, error?: BusinessError<void>) => {
      if (result === PasteButtonOnClickResult.SUCCESS) {
        console.info("success");
      } else {
        console.error("errCode: " + error?.code);
        console.error("errMessage: " + error?.message);
      }
    };

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

[图示请参阅官方原文]

本文来自 OpenHarmony 文档贡献者,按 CC BY 4.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
OpenHarmony 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。