当前位置：首页 > news >正文

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

news 2025/9/30 10:46:59

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. 引入插件

const ftpClient = uni.requireNativePlugin('ftpClient')

3. 核心 API 接口说明

3.1 连接管理

连接 FTP 服务器

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);}
});

断开连接

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

3.2 目录操作

创建目录

const options = {path: '/new/directory/path'  // 支持多级目录创建
};ftpClient.makeDirectory(options, (result) => {if (result.success) {console.log("目录创建成功");} else {console.error("目录创建失败: " + result.message);}
});

3.3 文件传输

上传文件/目录

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);}}
);

下载文件/目录

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 文件管理

获取文件列表

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);}
});

删除文件或目录

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() 方法彻底释放资源