安全控件

安全控件是系统提供的一组系统实现的ArkUI组件，其中保存控件在用户首次使用时，会弹出通知弹窗，在用户点击允许后自动授权，后续使用无需弹窗授权；粘贴控件在用户点击后自动授权，无需弹窗授权。它们可以作为一种“特殊的按钮”融入应用页面，实现用户点击即许可的设计思路。

相较于动态申请权限的方式，安全控件可基于场景化授权，简化开发者和用户的操作，主要优点有：

用户可掌握授权时机，授权范围最小化。

授权场景可匹配用户真实意图。

减少弹窗打扰。

开发者不必向应用市场申请权限，简化操作。

安全控件坚持仅采集实现业务功能所必须的个人数据，以服务于用户的需求，帮助开发透明、可选、可控的隐私合规应用。

1. 粘贴控件

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

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

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

1.1 约束与限制

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

1.2 开发步骤

1. 导入剪贴板依赖

   import { pasteboard } from '@kit.BasicServicesKit';
   

2. 添加输入框和粘贴控件

粘贴控件是由图标、文本、背景组成地类似Button的按钮，其中图标、文本两者至少有其一，背景必选。图标和文本不支持自定义，仅支持在已有的选项中选择。

应用声明安全控件的接口时，分为传参和不传参两种，不传参默认创建图标+文字+背景的按钮，传参根据传入的参数创建，不包含没有配置的元素。

import { pasteboard, BusinessError } from '@kit.BasicServicesKit';@Entry
@Component
struct 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%')}
}

2. 保存控件

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

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

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

2.1 约束与限制

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

2.2 开发步骤

1. 导入文件和媒体库依赖

   import { photoAccessHelper } from '@kit.MediaLibraryKit';
   import { fileIo } from '@kit.CoreFileKit';
   

2. 设置图片资源，并添加保存控件。

   保存控件是一种类似于按钮的安全控件，由图标、文本和背景组成。其中，图标和文本至少需要有一个，背景是必选的。图标和文本不能自定义，只能从已有的选项中选择。在声明安全控件的接口时，有传参和不传参两种方式。不传参将默认创建一个包含图标、文字和背景的按钮，传参根据参数创建，不包含配置的元素。

   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触发后10秒内通过createAsset接口创建图片文件，10秒后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
   @Component
   struct 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)}
   }
   

3. 位置控件

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

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

对于不是请位置关联应用的应用，只在部分前台场景需要使用位置信息。如果需要长时间使用或是在后台使用位置信息，建议申请位置权限。

3.1 约束与限制

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

3.2 开发步骤

1. 引入位置服务依赖

   import { geoLocationManager } from '@kit.LocationKit';
   

2. 添加位置依赖和获取当前位置信息

   安全控件是由图标、文本、背景组成的类似Button的按钮，其中图标、文本两者至少有其一，背景是必选的。图标和文本不支持自定义，仅支持在已有的选项中选择。应用申明安全控件的接口时，分为传参和不传参两种，不传参默认创建图标+文字+背景的按钮，传参根据传入的参数创建，不包含没有配置的元素。

   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
   @Component
   struct 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)}
   }