鸿蒙开发进阶（HarmonyOS）使用安全控件

** 鸿蒙NEXT开发实战往期必看文章：**

一分钟了解”纯血版！鸿蒙HarmonyOS Next应用开发！

“非常详细的” 鸿蒙HarmonyOS Next应用开发学习路线！（从零基础入门到精通）

HarmonyOS NEXT应用开发案例实践总结合（持续更新......）

HarmonyOS NEXT应用开发性能优化实践总结（持续更新......）

使用粘贴控件

粘贴控件是一种特殊的系统安全控件，它允许应用在用户的授权下无提示地读取剪贴板数据。

在应用集成粘贴控件后，用户点击该控件，应用读取剪贴板数据时不会弹窗提示。可以用于任何应用需要读取剪贴板的场景，避免弹窗提示对用户造成干扰。

例如，用户在应用外（如短信）复制了验证码，要在应用内粘贴验证码。用户原来在进入应用后，还需要长按输入框、在弹出的选项中点击粘贴，才能完成输入。而使用粘贴控件，用户只需进入应用后直接点击粘贴按钮，即可一步到位。

粘贴控件效果如图所示。

约束与限制

• 临时授权会持续到灭屏、应用切后台、应用退出情况发生。
• 应用在授权期间没有调用次数限制。
• 为了保障用户的隐私不被恶意应用获取，应用需确保安全控件是可见的且用户能够识别的。开发者需要合理的配置控件的尺寸、颜色等属性，避免视觉混淆的情况，如果发生因控件的样式不合法导致授权失败的情况，请检查设备错误日志。

开发步骤

以简化用户填写验证码为例，参考以下步骤，实现效果：点击控件获取临时授权，粘贴内容到文本框，效果图请见上文。

1. 导入剪贴板依赖。import { pasteboard } from '@kit.BasicServicesKit';**ts**
2. 添加输入框和粘贴控件。粘贴控件是由图标、文本、背景组成的类似Button的按钮，其中图标、文本两者至少有其一，背景必选。图标和文本不支持自定义，仅支持在已有的选项中选择。应用申明安全控件的接口时，分为传参和不传参两种，不传参默认创建图标+文字+背景的按钮，传参根据传入的参数创建，不包含没有配置的元素。当前示例使用默认参数。具体请参见PasteButton控件。此外，所有安全控件都继承安全控件通用属性，可用于定制样式。import { pasteboard, BusinessError } from '@kit.BasicServicesKit';@Entry@Componentstruct Index { @State message: string = ''; build() { Row() { Column({ space: 10 }) { TextInput({ placeholder: '请输入验证码', text: this.message }) PasteButton() .padding({top: 12, bottom: 12, left: 24, right: 24}) .onClick((event: ClickEvent, result: PasteButtonOnClickResult) => { if (PasteButtonOnClickResult.SUCCESS === result) { pasteboard.getSystemPasteboard().getData((err: BusinessError, pasteData: pasteboard.PasteData) => { if (err) { console.error(`Failed to get paste data. Code is ${err.code}, message is ${err.message}`); return; } // 剪贴板内容为 '123456' this.message = pasteData.getPrimaryText(); }); } }) } .width('100%') } .height('100%') }}

使用保存控件

保存控件是一种特殊的安全控件，它允许用户通过点击按钮临时获取存储权限，而无需通过权限弹框进行授权确认。

集成保存控件后，当用户点击该控件时，应用会获得10秒内访问媒体库特权接口的授权。这适用于任何需要将文件保存到媒体库的应用场景，例如保存图片或视频等。

与需要触发系统应用并由用户选择具体保存路径的Picker不同，保存控件可以直接保存到指定的媒体库路径，使得操作更为便捷。

保存控件效果如图所示。

约束与限制

• 当用户首次点击应用中的保存控件，系统将弹窗请求用户授权。如果用户点击“取消”，弹窗消失，应用无授权，用户再次点击保存控件时，将会重新弹窗；如果用户点击“允许”，弹窗消失，应用将被授予临时保存权限，此后点击该应用的保存控件将不会弹窗。
• 应用在onClick()触发回调到调用媒体库特权接口的时间间隔不能大于10秒。
• 用户点击一次控件，仅获取一次授权调用。
• 为了保障用户的隐私不被恶意应用获取，应用需确保安全控件是可见的且用户能够识别的。开发者需要合理的配置控件的尺寸、颜色等属性，避免视觉混淆的情况，如果发生因控件的样式不合法导致授权失败的情况，请检查设备错误日志。

开发步骤

以保存对话中图片为例，应用仅需要在前台期间，短暂使用保存图片的特性，不需要长时间使用。此时，可以直接使用安全控件中的保存控件，免去权限申请和权限请求等环节，获得临时授权，保存对应图片。

1. 导入文件和媒体库依赖。import { photoAccessHelper } from '@kit.MediaLibraryKit';import { fileIo } from '@kit.CoreFileKit';**ts**
2. 设置图片资源，并添加保存控件。保存控件是一种类似于按钮的安全控件，由图标、文本和背景组成。其中，图标和文本至少需要有一个，背景是必选的。图标和文本不能自定义，只能从已有的选项中选择。在声明安全控件的接口时，有传参和不传参两种方式。不传参将默认创建一个包含图标、文字和背景的按钮，传参则根据参数创建，不包含未配置的元素。当前示例使用默认参数。具体请参见SaveButton控件。此外，所有安全控件都继承安全控件通用属性，可用于定制样式。import { photoAccessHelper } from '@kit.MediaLibraryKit';import { fileIo } from '@kit.CoreFileKit';import { common } from '@kit.AbilityKit';import { promptAction } from '@kit.ArkUI';import { BusinessError } from '@kit.BasicServicesKit';async function savePhotoToGallery(context: common.UIAbilityContext) { let helper = photoAccessHelper.getPhotoAccessHelper(context); try { // onClick触发后5秒内通过createAsset接口创建图片文件，5秒后createAsset权限收回。 let uri = await helper.createAsset(photoAccessHelper.PhotoType.IMAGE, 'jpg'); // 使用uri打开文件，可以持续写入内容，写入过程不受时间限制 let file = await fileIo.open(uri, fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE); // $r('app.media.startIcon')需要替换为开发者所需的图像资源文件 context.resourceManager.getMediaContent($r('app.media.startIcon').id, 0) .then(async value => { let media = value.buffer; // 写到媒体库文件中 await fileIo.write(file.fd, media); await fileIo.close(file.fd); promptAction.showToast({ message: '已保存至相册！' }); }); } catch (error) { const err: BusinessError = error as BusinessError; console.error(`Failed to save photo. Code is ${err.code}, message is ${err.message}`); }}@Entry@Componentstruct Index { build() { Row() { Column({ space: 10 }) { // $r('app.media.startIcon')需要替换为开发者所需的图像资源文件 Image($r('app.media.startIcon')) .height(400) .width('100%') SaveButton() .padding({top: 12, bottom: 12, left: 24, right: 24}) .onClick(async (event: ClickEvent, result: SaveButtonOnClickResult) => { if (result === SaveButtonOnClickResult.SUCCESS) { const context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext; // 免去权限申请和权限请求等环节，获得临时授权，保存对应图片 savePhotoToGallery(context); } else { promptAction.showToast({ message: '设置权限失败！' }) } }) } .width('100%') } .height('100%') .backgroundColor(0xF1F3F5) }}

使用位置控件

位置控件使用直观且易懂的通用标识，让用户明确地知道这是一个获取位置信息的按钮。这满足了授权场景需要匹配用户真实意图的需求。只有当用户主观愿意，并且明确了解使用场景后点击位置控件，应用才会获得临时的授权，获取位置信息并完成相应的服务功能。

一旦应用集成了位置控件，用户点击该控件后，无论应用是否已经申请过或被授予精准定位权限，都会在本次前台期间获得精准定位的授权，可以调用位置服务获取精准定位。

对于不是强位置关联应用（例如导航、运动健康等）的应用，只在部分前台场景需要使用位置信息（例如定位城市、打卡、分享位置等）。如果需要长时间使用或是在后台使用位置信息，建议申请位置权限。

位置控件效果如图所示。

约束与限制

• 当用户首次点击应用中的位置控件，系统将弹窗请求用户授权。如果用户点击“取消”，弹窗消失，应用无授权，用户再次点击位置控件时，将会重新弹窗；如果用户点击“允许”，弹窗消失，应用将被授予临时位置权限，此后点击该应用的位置控件将不会弹窗。
• 精准定位的临时授权会持续到灭屏、应用切后台、应用退出等任一情况发生，然后恢复到临时授权之前的授权状态（授予/未授予/未申请）
• 应用在授权期间没有调用次数限制。
• 为了保障用户的隐私不被恶意应用获取，应用需确保安全控件是可见的且用户能够识别的。开发者需要合理的配置控件的尺寸、颜色等属性，避免视觉混淆的情况，如果发生因控件的样式不合法导致授权失败的情况，请检查设备错误日志。

开发步骤

以在聊天界面发送实时定位信息为例。在当前场景下，应用仅需要在前台期间，短暂地访问当前位置，不需要长时间使用。此时，可以直接使用安全控件中的位置控件，免去权限申请和权限请求等环节，获得临时授权，满足权限最小化，提升用户的隐私体验。

参考以下步骤，实现效果：点击控件“当前位置”获取临时精准定位授权，获取授权后，弹窗提示具体位置信息，效果图请见上文。

1. 引入位置服务依赖。import { geoLocationManager } from '@kit.LocationKit';**ts**
2. 添加位置控件和获取当前位置信息。安全控件是由图标、文本、背景组成的类似Button的按钮，其中图标、文本两者至少有其一，背景是必选的。图标和文本不支持自定义，仅支持在已有的选项中选择。应用申明安全控件的接口时，分为传参和不传参两种，不传参默认创建图标+文字+背景的按钮，传参根据传入的参数创建，不包含没有配置的元素。当前示例使用默认参数，具体请参见LocationButton控件。此外，所有安全控件都继承安全控件通用属性，可用于定制样式。在LocationButton的onClick()回调中通过调用geoLocationManager模块提供的方法获取当前位置信息。import { geoLocationManager } from '@kit.LocationKit';import { promptAction } from '@kit.ArkUI';import { BusinessError } from '@kit.BasicServicesKit';// 获取当前位置信息function getCurrentLocationInfo() { const requestInfo: geoLocationManager.LocationRequest = { 'priority': geoLocationManager.LocationRequestPriority.FIRST_FIX, 'scenario': geoLocationManager.LocationRequestScenario.UNSET, 'timeInterval': 1, 'distanceInterval': 0, 'maxAccuracy': 0 }; try { geoLocationManager.getCurrentLocation(requestInfo) .then((location: geoLocationManager.Location) => { promptAction.showToast({ message: JSON.stringify(location) }); }) .catch((err: BusinessError) => { console.error(`Failed to get current location. Code is ${err.code}, message is ${err.message}`); }); } catch (err) { console.error(`Failed to get current location. Code is ${err.code}, message is ${err.message}`); }}@Entry@Componentstruct Index { build() { Row() { Column({ space: 10 }) { LocationButton({ icon: LocationIconStyle.LINES, text: LocationDescription.CURRENT_LOCATION, buttonType: ButtonType.Normal }) .padding({top: 12, bottom: 12, left: 24, right: 24}) .onClick((event: ClickEvent, result: LocationButtonOnClickResult) => { if (result === LocationButtonOnClickResult.SUCCESS) { // 免去权限申请和权限请求等环节，获得临时授权，获取位置信息授权 getCurrentLocationInfo(); } else { promptAction.showToast({ message: '获取位置信息失败！' }) } }) } .width('100%') } .height('100%') .backgroundColor(0xF1F3F5) }}

如果你是一名有经验的资深Android移动开发、Java开发、前端开发、对鸿蒙感兴趣以及转行人员

→ 鸿蒙HarmonyOS Next 全栈开发学习笔记 希望这一份鸿蒙学习文档能够给大家带来帮助~

→ Android VIP全套学习笔记

这份鸿蒙（HarmonyOS NEXT）包含了鸿蒙开发必掌握的核心知识要点，内容包含了（ArkTS、ArkUI开发组件、Stage模型、多端部署、分布式应用开发、音频、视频、WebGL、OpenHarmony多媒体技术、Napi组件、OpenHarmony内核、（南向驱动、嵌入式等）鸿蒙项目实战等等）鸿蒙（HarmonyOS NEXT）技术知识点。

鸿蒙（NEXT星河版）学习路线

该路线图包含基础技能、就业必备技能、多媒体技术、六大电商APP、进阶高级技能、实战就业级设备开发，不仅补充了华为官网未涉及的解决方案

2.视频学习教程+学习PDF文档

HarmonyOS Next 最新全套视频教程

**纯血版鸿蒙全套学习文档（面试、文档、全套视频等） **