前言

HarmonyOS对文件访问有严格的安全控制，应用需要通过权限持久化来保持对特定目录的访问权限。@pura/harmony-utils 的 FileUtil 封装了文件权限持久化方法。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、FileUtil权限核心API

FileUtil 提供了以下文件权限持久化方法：

方法	说明	返回类型	使用场景
persistPermission(uri)	持久化权限	void	长期文件访问
revokePermission(uri)	撤销权限	void	释放文件访问

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 权限安全：支持权限的授予和撤销

1.2 权限持久化场景

场景	操作	说明
首次访问	persistPermission	获取持久访问权限
不再需要	revokePermission	释放权限
应用重启	自动恢复	持久化后重启仍有效

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 持久化文件权限

import { FileUtil } from '@pura/harmony-utils';

Button('持久化权限')
  .width('100%')
  .onClick(async () => {
    try {
      let uri = 'file://docs/storage/test.txt';
      await FileUtil.persistPermission(uri);
      this.result = '权限持久化成功 ✅\n应用重启后仍可访问';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 撤销文件权限

Button('撤销权限')
  .width('100%')
  .onClick(async () => {
    try {
      let uri = 'file://docs/storage/test.txt';
      await FileUtil.revokePermission(uri);
      this.result = '权限已撤销 🔓';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

import { FileUtil } from '@pura/harmony-utils';

@Entry
@Component
struct FilePermDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('持久化权限').width('100%').onClick(async () => {
        try {
          this.result = '权限持久化成功';
        } catch (e) { this.result = '异常: ' + e; }
      });
      Button('撤销权限').width('100%').onClick(async () => {
        try {
          this.result = '权限已撤销';
        } catch (e) { this.result = '异常: ' + e; }
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 批量权限管理

import { FileUtil } from '@pura/harmony-utils';

async function persistMultiplePermissions(uris: string[]): Promise<void> {
  for (let uri of uris) {
    await FileUtil.persistPermission(uri);
  }
}

async function revokeMultiplePermissions(uris: string[]): Promise<void> {
  for (let uri of uris) {
    await FileUtil.revokePermission(uri);
  }
}

4.2 权限检查封装

async function ensurePermission(uri: string): Promise<boolean> {
  try {
    await FileUtil.persistPermission(uri);
    return true;
  } catch (e) {
    return false;
  }
}

五、注意事项

1. URI格式：权限操作需要使用URI格式路径
2. 异步操作：权限操作为异步方法，需使用await
3. 权限范围：持久化权限仅对指定URI有效
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 用户授权：首次访问需用户授权

六、常见问题

Q1: persistPermission()失败怎么办？

检查URI格式是否正确，以及用户是否已授权文件访问权限。

Q2: 权限持久化后应用卸载重装还有效吗？

应用卸载后权限会被清除，重装后需要重新获取权限。

Q3: 可以持久化目录权限吗？

可以持久化目录权限，持久化后可以访问目录下的所有文件。

Q4: 撤销权限后还能访问文件吗？

撤销权限后无法访问对应文件，需要重新获取权限。

总结

FileUtil 的文件权限持久化方法为跨会话文件访问提供了安全机制。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。合理使用权限持久化，可以确保应用在重启后仍能访问所需文件。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。