uniapp 安卓FTP上传下载操作原生插件

uniapp FTP Client 安卓原生插件介绍

经过对uniapp插件市场上多款FTP插件的调研和测试，发现它们在处理大文件传输时普遍存在性能瓶颈，尤其是上传和下载过程中容易造成UI界面卡顿。为了解决这些问题并满足项目实际需求，我开发了这款高性能FTP客户端插件。这是一个基于 Apache Commons Net 实现的 Android 平台 FTP 客户端插件，专为 UniApp 应用设计。该插件提供了完整的 FTP 功能集，包括连接管理、文件上传/下载、目录操作等核心功能，并具有以下特点：

主要特性

全面的 FTP 操作支持：
- 连接与断开 FTP 服务器
- 文件和目录的创建、删除操作
- 文件和目录的上传与下载
- 文件列表浏览与目录导航
高级传输功能：
- 支持大文件传输（最大可达 GB 级别）
- 实时进度监控与反馈
- 多线程异步处理，避免阻塞 UI
- 自动重连机制和超时控制
增强的兼容性：
- 中文编码支持（GBK 编码）
- Android 存储权限适配（特别是 Android 11+）
- 递归目录操作支持
稳定性保障：
- 完善的异常处理机制
- 资源自动回收管理
- 日志记录与调试支持

使用方法

1. 安装插件

将插件集成到您的 UniApp 项目中，确保在manifest.json 中正确配置了原生插件。

2. 引入插件

javascript 复制代码

const ftpClient = uni.requireNativePlugin('ftpClient')

3. 核心 API 接口说明

3.1 连接管理

连接 FTP 服务器

javascript 复制代码

const options = {
    host: 'your-ftp-server-host',
    port: 'your-ftp-server-port',
    username: 'your-username',
    password: 'your-password'
};

ftpClient.connect(options, (result) => {
    if (result.success) {
        console.log("连接成功");
    } else {
        console.error("连接失败: " + result.message);
    }
});

断开连接

javascript 复制代码

ftpClient.disconnect((result) => {
    if (result.success) {
        console.log("已断开连接");
    } else {
        console.error("断开连接失败: " + result.message);
    }
});

3.2 目录操作

创建目录

javascript 复制代码

const options = {
    path: '/new/directory/path'  // 支持多级目录创建
};

ftpClient.makeDirectory(options, (result) => {
    if (result.success) {
        console.log("目录创建成功");
    } else {
        console.error("目录创建失败: " + result.message);
    }
});

3.3 文件传输

上传文件/目录

javascript 复制代码

const options = {
    localPath: '/sdcard/local/file.txt',
    remotePath: '/remote/directory/',
    fileName: 'custom_name.txt'  // 可选，自定义远程文件名
};

ftpClient.uploadFile(
    options,
    (progress) => {
        // 进度回调
        console.log(`上传进度: ${progress.percentage}%`);
    },
    (result) => {
        // 完成回调
        if (result.success) {
            console.log("上传成功");
        } else {
            console.error("上传失败: " + result.message);
        }
    }
);

下载文件/目录

javascript 复制代码

const options = {
    remotePath: '/remote/file.txt',
    localPath: '/sdcard/download/'  // 可选，默认存储在应用私有目录
};

ftpClient.downloadFile(
    options,
    (progress) => {
        // 进度回调
        console.log(`下载进度: ${progress.percentage}%`);
    },
    (result) => {
        // 完成回调
        if (result.success) {
            console.log("下载成功，保存至: " + result.localPath);
        } else {
            console.error("下载失败: " + result.message);
        }
    }
);

3.4 文件管理

获取文件列表

javascript 复制代码

const options = {
    path: '/remote/directory/'
};

ftpClient.listFiles(options, (result) => {
    if (result.success) {
        result.files.forEach(file => {
            console.log(`${file.name} (${file.directory ? '目录' : '文件'})`);
        });
    } else {
        console.error("获取文件列表失败: " + result.message);
    }
});

删除文件或目录

javascript 复制代码

const options = {
    path: '/remote/file_or_directory'
};

ftpClient.deleteFile(options, (result) => {
    if (result.success) {
        console.log("删除成功");
    } else {
        console.error("删除失败: " + result.message);
    }
});

4. 注意事项

权限申请：
- Android 11 及以上版本需请求所有文件访问权限
- 使用 checkAllFilesAccessPermission 方法检查并引导用户授权
路径规范：
- 所有远程路径应以/ 开头
- 目录路径建议以 / 结尾以明确标识
性能优化：
- 插件内部采用固定大小线程池（6个线程）处理并发任务
- 传输过程中会自动控制进度更新频率（最小间隔100ms）
资源释放：
- 页面销毁前应当调用 disconnect() 断开连接
- 必要时可通过release() 方法彻底释放资源

示例界面演示

本插件配套提供了完整的 Vue 前端界面组件，涵盖了从连接管理到文件操作的所有功能。开发者可以直接复用该界面模板快速构建自己的 FTP 客户端应用，也可根据实际需求进行定制开发。

uniapp FTP Client 安卓原生插件介绍