问题：如何在UniApp中使用plus.io写入文件？

Question

在使用 UniApp 进行本地文件操作时，开发者常遇到“如何在 UniApp 中使用 plus.io 写入文件？”这一问题。由于 UniApp 默认运行在 WebView 环境中，无法直接操作本地文件系统，需依赖 5+ App 运行环境并调用 plus.io 模块实现文件写入。常见问题包括：如何申请文件系统权限？如何创建或写入指定路径的文件？如何处理异步写入操作？此外，路径格式、编码设置、文件覆盖与追加方式等也容易引发错误。本文将围绕这些问题，深入讲解在 UniApp 中使用 plus.io 写入文件的完整流程与注意事项。

Answer 1

在 UniApp 中使用 plus.io 写入文件的完整指南

在 UniApp 开发过程中，本地文件操作是一个常见的需求。由于 UniApp 默认运行在 WebView 环境中，无法直接访问本地文件系统。要实现文件的写入操作，必须依赖 5+ App 运行环境，并调用 plus.io 模块。

1. 理解运行环境与权限申请

UniApp 的 plus.io 模块只能在 5+ App 环境中使用。在进行文件操作前，必须确保应用运行在支持 5+ 的环境中，并申请必要的文件系统权限。

在 manifest.json 文件中，需要添加如下权限：

[
    {
      "plus": {
        "distribute": {
          "android": {
            "permissions": [
              "android.permission.WRITE_EXTERNAL_STORAGE"
            ]
          }
        }
      }
    }
  

同时，在运行时也可以动态申请权限：

plus.android.requestPermissions(['android.permission.WRITE_EXTERNAL_STORAGE'], function (result) {
    if (result.denied.length > 0) {
      console.log('权限被拒绝');
    } else {
      console.log('权限已获取');
    }
  });

2. 文件写入的基本流程

使用 plus.io 写入文件的流程包括以下几个步骤：

1. 获取文件系统对象（plus.io.resolveLocalFileSystemURL）
2. 创建或打开文件（fileEntry.createWriter）
3. 写入内容（fileWriter.write）
4. 关闭文件流（fileWriter.close）

以下是一个完整的文件写入示例：

const filePath = '_doc/test.txt'; // 保存在应用文档目录中

plus.io.resolveLocalFileSystemURL(filePath, function (entry) {
  entry.createWriter(function (writer) {
    writer.onwriteend = function () {
      console.log('写入完成');
      writer.close();
    };
    writer.onerror = function (e) {
      console.error('写入失败：', e);
    };
    writer.write('这是写入的内容'); // 默认使用 UTF-8 编码
  }, function (e) {
    console.error('创建写入器失败：', e);
  });
}, function (e) {
  console.error('获取文件失败：', e);
});

3. 路径格式与编码设置

在 UniApp 中，文件路径通常使用 5+ App 支持的 URL 格式，例如：

• _doc/：应用文档目录
• _downloads/：下载目录
• _documents/：用户文档目录

路径格式错误是常见的问题之一。例如，路径中不能包含非法字符，也不能使用绝对路径（如 /storage/emulated/0/...）。

编码方面，FileWriter.write() 方法默认使用 UTF-8 编码。若需指定其他编码格式，需手动处理字符串编码转换。

4. 文件写入模式：覆盖与追加

默认情况下，写入文件会覆盖原有内容。若需追加内容，可在写入前将文件内容读取出来，再拼接新内容。

示例代码如下：

plus.io.resolveLocalFileSystemURL(filePath, function (entry) {
  entry.file(function (file) {
    const reader = new FileReader();
    reader.onloadend = function () {
      const existingContent = reader.result || '';
      entry.createWriter(function (writer) {
        writer.seek(writer.length); // 移动到文件末尾
        writer.write(existingContent + '\n新增内容');
        writer.close();
      });
    };
    reader.readAsText(file);
  });
});

5. 异步写入与错误处理

plus.io 的文件操作均为异步执行，因此必须通过回调函数或 Promise 封装来处理。

建议封装为 Promise 以提高可维护性：

function writeFileAsync(path, content) {
  return new Promise((resolve, reject) => {
    plus.io.resolveLocalFileSystemURL(path, function (entry) {
      entry.createWriter(function (writer) {
        writer.onwriteend = () => {
          writer.close();
          resolve();
        };
        writer.onerror = (e) => reject(e);
        writer.write(content);
      }, reject);
    }, reject);
  });
}

使用方式：

writeFileAsync('_doc/log.txt', '日志内容')
  .then(() => console.log('写入成功'))
  .catch(err => console.error('写入失败：', err));

6. 常见问题与解决方案

问题	原因	解决方案
无法写入文件	权限未申请或路径无效	检查权限配置，确认路径格式正确
写入内容乱码	编码格式不一致	统一使用 UTF-8 编码或手动处理编码转换
异步操作未等待	未使用 Promise 或 async/await	封装为 Promise 并使用 await 等待结果

7. 流程图：文件写入全过程

graph TD
A[开始] --> B{运行在 5+ App 环境?}
B -- 是 --> C[申请文件权限]
C --> D[获取文件系统入口]
D --> E[创建文件写入器]
E --> F[写入内容]
F --> G{是否追加内容?}
G -- 是 --> H[读取已有内容 + 拼接]
G -- 否 --> I[直接写入]
H --> J[写入拼接后的内容]
I --> K[关闭文件流]
J --> K
K --> L[结束]