HarmonyOS|第十九天 HarmonyOS的文件操作和本地存储

一、前言：为什么需要掌握文件操作与本地存储？

在移动应用开发中，文件操作和本地存储是每个开发者都必须掌握的核心技能。无论是保存用户配置、缓存网络数据，还是处理图片/视频等多媒体文件，都需要通过文件系统进行操作。在HarmonyOS开发中，系统提供了完善的API体系和沙箱安全机制，帮助开发者实现安全高效的本地存储。

二、HarmonyOS文件系统基础

2.1 沙箱机制解析

HarmonyOS为每个应用分配独立的存储空间，采用沙箱机制隔离不同应用的数据。通过实际路径对比理解这个机制：

// 应用私有目录路径示例
context.getFilesDir() → /data/app/el2/100/base/com.example.demo/haps/entry/files

2.2 存储区域划分

存储类型	访问权限	清除策略
应用私有目录	仅本应用可读写	卸载自动清除
公共目录	需申请权限	持久保存
缓存目录	自动管理	空间不足时清除

三、四大本地存储方案实战

3.1 应用私有文件操作（基础版）

完整文件读写示例：

// 获取文件目录
File filesDir = getContext().getFilesDir();

// 写入文件
try (FileOutputStream fos = new FileOutputStream(new File(filesDir, "config.txt"))) {
    fos.write("Hello HarmonyOS".getBytes());
} catch (IOException e) {
    HiLog.error(LABEL, "文件写入失败: " + e.getMessage());
}

// 读取文件
StringBuilder content = new StringBuilder();
try (BufferedReader br = new BufferedReader(new FileReader(new File(filesDir, "config.txt")))) {
    String line;
    while ((line = br.readLine()) != null) {
        content.append(line);
    }
} catch (IOException e) {
    HiLog.error(LABEL, "文件读取失败: " + e.getMessage());
}

3.2 Preferences轻量存储

键值对存储最佳实践：

// 初始化Preferences实例
Preferences preferences = Preferences.getGlobalPreferences(context);

// 存储数据
preferences.putString("userName", "Harmony开发者")
          .putInt("loginCount", 5)
          .flush(); // 立即提交

// 读取数据
String name = preferences.getString("userName", "默认值");
int count = preferences.getInt("loginCount", 0);

// 监听数据变化
preferences.registerObserver((key) -> {
    if ("themeMode".equals(key)) {
        updateTheme(preferences.getString(key, "light"));
    }
});

3.3 关系型数据库（RelationalStore）

数据库操作四部曲：

步骤1：定义实体类

@Entity
public class User {
    @PrimaryKey
    private Integer id;
    
    @ColumnInfo(name = "user_name")
    private String name;
    
    // Getter/Setter省略...
}

步骤2：创建数据库

@Database(entities = {User.class}, version = 1)
public abstract class AppDatabase extends HarmonyOSOpenHelper {
    private static final String DB_NAME = "user_db";
    
    public AppDatabase(Context context) {
        super(context, DB_NAME, null);
    }
}

步骤3：实现DAO接口

@Dao
public interface UserDao {
    @Insert
    void insertUser(User user);
    
    @Query("SELECT * FROM User WHERE id = :userId")
    User getUserById(int userId);
}

步骤4：业务层调用

UserDao userDao = DatabaseHolder.getDatabase().userDao();
userDao.insertUser(new User(1, "张三"));

User user = userDao.getUserById(1);
HiLog.info(LABEL, "查询结果：" + user.getName());

3.4 对象存储（ObjectStore）

复杂对象存储方案：

// 创建对象存储
ObjectStore objectStore = ObjectStore.create(context, "MyObjectStore");

// 存储自定义对象
User user = new User("李四", 25);
objectStore.put("current_user", user);

// 读取对象
User cachedUser = objectStore.get("current_user", User.class);

四、综合实战：备忘录应用开发

4.1 项目结构设计

src/main/java/
├── entry
│   ├── MainAbility.java       # 主界面
│   ├── Note.java             # 笔记实体类
│   ├── NoteDatabase.java     # 数据库类
│   └── NoteDao.java          # 数据操作接口
resources/
└── config.json               # 配置文件

4.2 核心功能实现

笔记保存功能：

public void saveNote(String title, String content) {
    Note newNote = new Note();
    newNote.setTitle(title);
    newNote.setContent(content);
    newNote.setCreateTime(new Date());
    
    // 同时保存到数据库和本地文件
    noteDao.insert(newNote);
    saveToFile(title + ".txt", content);
}

private void saveToFile(String fileName, String content) {
    File targetFile = new File(getExternalFilesDir("notes"), fileName);
    try (FileWriter writer = new FileWriter(targetFile)) {
        writer.write(content);
    } catch (IOException e) {
        HiLog.error(LABEL, "文件保存失败：" + e.getMessage());
    }
}

笔记列表展示：

ListContainer listContainer = (ListContainer) findComponentById(ResourceTable.Id_note_list);
List<Note> notes = noteDao.getAllNotes();

SampleItemProvider provider = new SampleItemProvider(notes, this);
listContainer.setItemProvider(provider);

五、高级技巧与优化策略

5.1 大文件分块传输

private static final int BUFFER_SIZE = 1024 * 1024; // 1MB缓冲区

void copyLargeFile(File source, File target) throws IOException {
    try (InputStream is = new FileInputStream(source);
         OutputStream os = new FileOutputStream(target)) {
         
        byte[] buffer = new byte[BUFFER_SIZE];
        int bytesRead;
        while ((bytesRead = is.read(buffer)) != -1) {
            os.write(buffer, 0, bytesRead);
            updateProgress(bytesRead); // 更新进度条
        }
    }
}

5.2 数据库事务优化

noteDatabase.beginTransaction();
try {
    for (int i = 0; i < 1000; i++) {
        Note note = generateTestNote(i);
        noteDao.insert(note);
    }
    noteDatabase.setTransactionSuccessful();
} finally {
    noteDatabase.endTransaction();
}

六、常见问题排查指南

6.1 权限问题处理方案


"reqPermissions": [
    {
        "name": "ohos.permission.READ_USER_STORAGE",
        "reason": "需要读取用户文件"
    },
    {
        "name": "ohos.permission.WRITE_USER_STORAGE",
        "reason": "需要写入用户文件"
    }
]

6.2 存储空间监控

FileStat stat = new FileStat();
FileStat.getStat(path, stat);
long freeSpace = stat.blockSize * stat.blocksFree;

if (freeSpace < 1024 * 1024 * 100) { // 剩余空间小于100MB
    showCleanStorageDialog();
}

七、总结与学习建议

通过本文的学习，你应该已经掌握：

✔️ 文件系统的沙箱机制与路径获取
✔️ Preferences键值对存储的灵活应用
✔️ RelationalStore数据库的CRUD操作
✔️ 对象存储的使用场景
✔️ 综合项目的开发实践