更新记录
4.1.0(2024-04-07)
1.变更:(安卓)API : gotoSetting 已废弃,不再支持 2.新增:(安卓,自定义文件选择器)自定义文件选择器终于支持了多选功能,支持长按开启多选模式 3.变更:(ios)为优化用户体验,ios打开文件选择器时会显示动画效果 4.新增:(安卓)API : gotoAllowReadAllFilesSetting 用于打开【所有文件读取权限】设置页面 5.新增:(安卓)安卓端也新增了用户取消选择文件的回调(状态码1006),便于实现特殊的业务逻辑,自定义选择器和原生选择器都支持
4.0.5(2024-02-23)
1.fix:修复安卓多应用冲突
4.0.4(2024-02-07)
1.fix:修复安卓多个应用冲突
查看更多平台兼容性
Android | Android CPU类型 | iOS |
---|---|---|
适用版本区间:5.0 - 14.0 | armeabi-v7a:支持,arm64-v8a:支持,x86:未测试 | 适用版本区间:11 - 17 |
原生插件通用使用流程:
- 购买插件,选择该插件绑定的项目。
- 在HBuilderX里找到项目,在manifest的app原生插件配置中勾选模块,如需要填写参数则参考插件作者的文档添加。
- 根据插件作者的提供的文档开发代码,在代码中引用插件,调用插件功能。
- 打包自定义基座,选择插件,得到自定义基座,然后运行时选择自定义基座,进行log输出测试。
- 开发完毕后正式云打包
付费原生插件目前不支持离线打包。
Android 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/android
iOS 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios
注意事项:使用HBuilderX2.7.14以下版本,如果同一插件且同一appid下购买并绑定了多个包名,提交云打包界面提示包名绑定不一致时,需要在HBuilderX项目中manifest.json->“App原生插件配置”->”云端插件“列表中删除该插件重新选择
lemonjk-FileSelect
!!!有疑问请不要点击咨询作者(因为我收不到),请直接在插件下方评论回复(或加q群讨论:466852060)
一、基本使用
使用前须知:
- 推荐优先使用【下载for离线打包】方式下载插件包,然后在项目中引入。此方式同样可以云打包,而插件包是存放在本地项目中的,所以不用开发者绑定账号,任何人复制你的项目都可以使用插件运行,更适合多人开发项目,交付项目。可以不受插件后续版本更新的影响。https://ask.dcloud.net.cn/article/35844
- 已适配安卓14.x( SdkVersion>=34) ,为满足上架谷歌商店的新应用需要targetSdkVersion>=33,本插件(>=3.1版)经测试可以在targetSdkVersion>=34条件下正常选取文件
- 已在部分真机(详情见:二、兼容性说明)测试通过,其他系统版本、机型未知,请自行测试。
- 特性(安卓):本插件已做自动权限检查,支持跳转到APP权限设置页。
- 特性:支持限制文件类型选取(安卓为mime类型,ios为utis类型),实现限制文件类型选取。
- 特性(安卓):支持访问指定目录,方便用户在指定目录快速选取。
- 特性:支持多选,同时选取多个文件。
新版本(4.0.0+)特别说明:
- 本插件4.0.0+已完全进行重构,与之前版本的使用方式不完全兼容,但大多数配置仍可使用,详见新版本说明。
- 为避免与之前版本插件可能存在的冲突,使用此版本(4.0.0+)前请移除本插件的其它版本。
- 新增:(安卓,自定义文件选择器)全新UI界面的自定义文件选择器,适配夜间模式,根据系统自动切换。
- 新增:(安卓,自定义文件选择器)新增API,可以获取当前手机连接的所有外接存储设备(sd卡、u盘、移动硬盘等),并可指定访问对应的外接存储设备
- 删除:(安卓,自定义文件选择器)移除之前版本中的/data目录访问相关API,如有需要请使用之前的版本。(重构中,后续重新支持)
- 修复:(安卓)修复了之前版本在进行大文件(>1G)选取时出现白屏、卡死。多线程处理大文件读取,选取更快,异步返回结果。
- 优化:(安卓)在文件读取时会有加载提示,更好的用户体验。
- 变更:(安卓)之前版本只能使用系统内置文件选择器,新版本有原生和自定义文件选择器可供选择(通过调用不同API选择)。
- 原生文件选择器和自定义文件选择器有何区别?
- 原生文件选择器是安卓系统内置的。不可定制界面,与应用风格不协调,可配置属性少,无法满足定制化需求,操作体验不好。但是可以不用申请各种权限,官方推荐,可以让用户放心隐私问题。
- 自定义文件选择器是开发者自行制作编写的。界面可任意定制,理论上可配置任何属性样式,满足定制化需求,但需要申请读写权限,高版本安卓(13.x)还需要MANAGE_EXTERNAL_STORAGE权限(此权限上架不了谷歌商店),同时用户可能并不会愿意授权。
- 我该如何选择?
- 变更:(安卓)API : gotoSetting 已废弃,不再支持
- 新增:(安卓,自定义文件选择器)自定义文件选择器终于支持了多选功能,支持长按开启多选模式
- 变更:(ios)为优化用户体验,ios打开文件选择器时会显示动画效果
1.在页面引入
不要忘了在 "manifest.json -> APP原生插件配置" 内添加本插件,否则云打包(离线打包)不会生效
注:版本4.0.4+开始,需要在manifest.json -> APP原生插件配置->本插件下的[appid_android]输入框中填入你的应用包名
const lemonjkFileSelect = uni.requireNativePlugin('lemonjk-FileSelect');
2.唤起文件选择
lemonjkFileSelect.showPicker({
//各属性配置见下方【showPicker可配置参数说明】
pathScope: "/Download",
mimeType: "*/*",
utisType:"public.data",
}, result => {
// 返回值说明见下方【showPicker返回值说明】
//(仅安卓,插件版本<4.0.0)当错误码为1001,即未授权文件读取权限,可以提示用户未打开读取文件权限,并跳转设置页
//插件版本4.0.0+当没有相关权限时会自动跳转到设置页面,无需判断,如需在跳转前执行
//用户提示等需求,请使用4.0.0+新增的API(isHaveSecurityScopeGrant)查询权限
if(result.code==1001){
uni.showModal({
title:"需要文件访问权限",
content:"您还未授权本应用读取文件。为保证您可以正常上传文件,请在权限设置页面打开文件访问权限(不同手机厂商表述可能略有差异)请根据自己手机品牌设置",
confirmText:"去授权",
cancelText:"算了",
success(e) {
if(e.confirm){
// 跳转到应用设置页
lemonjkFileSelect.gotoSetting();
}
}
})
}
})
二、插件方法和参数配置
1.showPicker
4.0.0安卓端变更为打开的是自定义文件选择器,如需打开原生文件选择器请调用: lemonjkFileSelect.showNativePicker
示例
lemonjkFileSelect.showPicker({
pathScope: "/Download",
mimeType: "*/*",
utisType:"public.data",
multi:'yes'
}, result => {})
//4.0.0+ 使用示例及高级筛选器配置示例
lemonjkFileSelect.showPicker({
// multi: "yes", //多选,待开发,后续支持
pathScope: "/Download",
navTitle:"文件选择",
navTextColor:'#55ff00',
navBarBgColor:'#00aaff',
theme:'light', //auto 跟随系统 light 亮色 dark 暗色
showHideFile:"yes", //是否显示隐藏的文件和文件夹
filterConfig:{ //对象里配置的属性要同时满足
// fileName:['base.apk','config.txt','配置文件.yaml'], //属性数组满足其中一项
fileSize:String(1*1024*1024), //byte 单位:字节
fileExtension:['apk','txt','jpg','mp3','yaml'], //属性数组满足其中一项
}
}, result => {
console.log(result);
})
可配置参数说明
属性 | 类型 | 说明 | 兼容性(4.0.0、4.0.1等指插件版本) |
---|---|---|---|
navTitle | string | 顶部导航栏标题 | 仅【4.0.0+】安卓自定义文件选择器 |
navTextColor | string | 顶部导航栏文字颜色 如: navTextColor:'#ffffff' |
仅【4.0.1+】安卓自定义文件选择器,此优先级高于theme主题对应的颜色 |
loadingToast | string | 是否在用户选择文件后显示文件加载弹窗提示 可选值: [不填] 显示(默认值) no 不显示 |
仅【4.1.0+】 |
pickerMode | string | 可选值: [不填] 会在左侧显示第三方APP(默认值) "OPEN_DOCUMENT" 隐藏第三方APP |
仅【4.0.2+】安卓 注:你不理解该属性作用的,请不要设置该属性,保持默认即可 |
navBarBgColor | string | 顶部导航栏背景颜色 如:navBarBgColor:'#ffffff' |
仅【4.0.1+】安卓自定义文件选择器,此优先级高于theme主题对应的颜色 |
theme | string | 选择器外观主题,默认值为:auto 可选值: auto 跟随系统 (默认值) light 亮色 dark 暗色 |
仅【4.0.1+】安卓自定义文件选择器 |
showHideFile | string | 是否显示隐藏的文件和文件夹 可选值: [不填] 不显示(默认值) yes 显示 |
仅【4.0.0+】安卓自定义文件选择器 |
pathScope | string | 【可选】访问指定目录,不需要则不要声明该属性,默认显示顶级目录 例: /DCIM/Camera 相机 /Download 下载 |
仅安卓,部分目录由于安全策略无法访问,如"Android/data" ,请自行测试,可以参考自己手机的目录进行设置原生文件选择器指定目录需在Android 8.0及以上系统支持(如需低版本支持请使用插件4.0.0+版的自定义文件选择器) |
externalStoragePath | string | 如果pathScope路径为外接存储设备路径(从getAllExternalStorage中获取),需设置externalStoragePath为yes | 仅【4.0.0+】安卓自定义文件选择器 |
filterConfig | object | 高级筛选器配置,用于可选文件过滤,更高级的文件筛选功能,满足更复杂的文件筛选要求。 filterConfig.fileName 文件名筛选(Array filterConfig.fileSize 文件大小筛选(String,单位:字节) filterConfig.fileExtension 文件类型筛选(Array 具体使用见上方使用示例 |
仅【4.0.1+】安卓自定义文件选择器 |
mimeType | string | 【必填】限制选取的文件类型,不限制需设为 "*/*" ,更多类型请参照Mime类型对照表,暂时仅支持设置单个类型例: image/* (图片) text/plain (文本) application/vnd.openxmlformats-officedocument.wordprocessingml.document (word) |
仅安卓,ios使用utisType属性代替 自定义文件选择器(4.0.0+),请使用filterConfig高级筛选器代替 |
utisType | string | 【必填】限制选取的文件类型,不限制需设为"public.data" ,更多类型请参照utis类型对照表,暂时仅支持设置单个类型utis对照表请点此前往 |
仅ios,安卓使用mimeType代替 |
multi | string | 【可选】是否开启多选,"yes"为开启,默认不填即为单选 | |
securityPackageName | string | 【可选】"Android/data" 下要访问的包名,可以参考自己手机目录"Android/data"下的包名进行设置如果需要选取 "Android/data" 安全目录下的文件,请设置该属性,不需要则不要声明该属性 |
仅【<4.0.0】安卓 |
securityScope | string | 【可选】安全访问的根目录,暂时只支持 "data" 如果需要选取 "Android/data" 安全目录下的文件,请设置该属性,不需要则不要声明该属性注:securityPackageName和securityScope需要同时设置才能访问 "Android/data" 下的目录 |
仅【<4.0.0】安卓 |
返回值说明
属性 | 类型 | 说明 | 兼容性 |
---|---|---|---|
code | string 【4.0.0】安卓返回的状态码由之前的字符串类型改为数字类型int |
状态码: 0 成功 -1 未知错误 1001 未授权文件读取权限(文件访问权限错误) 1002 文件不存在(仅安卓) 1004 用户取消了选择(仅ios) 1005 文件选取出错(仅ios) 1006 用户取消了选择(仅安卓) (仅安卓,插件版本<4.0.0)当错误码为1001,即未授权文件读取权限,可以提示用户未打开读取文件权限,并跳转设置页 (使用 gotoSetting 跳转) 插件版本4.0.0+当没有相关权限时会自动跳转到设置页面,无需判断,如需在跳转前进行用户提示等需求,请使用4.0.0+新增的API(isHaveSecurityScopeGrant)查询权限 |
危险变更,更新4.0.0安卓端,部分状态码的值发生了变更,请根据实际调试返回的状态码进行判断 【4.1.0+】安卓端也新增了用户取消选择文件的回调(状态码1006),便于实现特殊的业务逻辑,自定义选择器和原生选择器都支持 |
filePath | string | 选取的文件的绝对路径,可以直接提供给uniapp的上传、下载等api使用,需要二进制上传请使用plus5+API进行转换 | 请参考files |
fileName | string | 选取的文件的名称 | 请参考files,危险变更,为避免歧义,在【4.0.0】安卓端(【4.0.2】ios端也更新了),fileRealName为实际在文件夹中的显示的名称,而fileName则为逻辑上的展示名称 |
fileRealName | string | 选取的文件的真实名称 | 请参考files, 危险变更,为避免歧义,在【4.0.0】安卓端(【4.0.2】ios端也更新了),fileRealName为实际在文件夹中的显示的名称,而fileName则为逻辑上的展示名称 |
fileSize | string | 选取的文件的大小(单位:字节) | 请参考files |
fileExtension | string | 选取的文件的后缀名 | 请参考files |
fileMime | string | 选取的文件的Mime类型 | 请参考files,仅【4.0.0】安卓原生文件选择器,本属性不保证返回,请勿以此作为唯一判断业务逻辑的属性 |
files | array |
无论设置了单选还是多选,都以数组形式返回所选文件列表。如果单选,则数组长度为1,使用files[0]即可。 3.0版本ios新增的文件列表属性.单选和多选统一以数组形式返回,废弃了 result.fileName、result.fileSize、result.fileExtension、result.filePath、result.fileRealName 3.1版本安卓新增的文件列表属性.单选和多选统一以数组形式返回,废弃了 result.fileName、result.fileSize、result.fileExtension、result.filePath、result.fileRealName、result.fileMime 4.0.0版本安卓完全使用了files数组作为文件选择结果返回,无论设置单选还是多选。 files结构如下: [{filePath,fileName,fileExtension,fileSize},...] |
危险变更,更新3.0,请注意适配(仅ios) 危险变更,更新3.1,请注意适配(仅安卓) 危险变更,更新4.0.0,请注意适配(仅安卓) |
errMsg | string | 选择完成后的状态信息 | |
detail | string | 具体的文字说明 |
2.【已废弃】gotoSetting(仅安卓)
跳转到应用设置页面 由于uniapp官方已提供该功能的API,所以插件4.1.0+开始,此API不再支持 详见:https://uniapp.dcloud.net.cn/api/system/openappauthorizesetting.html
可配置参数说明
返回值说明
示例
// lemonjkFileSelect.gotoSetting();
// 使用官方的API代替即可
uni.openAppAuthorizeSetting({
success (res) {
console.log(res)
}
})
3.grantSecurityScope(仅安卓<4.0.0)
打开安全目录授权页面
//1.选取 "Android/data" 目录文件之前,需要调用此方法。
//2.用户同意授权后,才可使用lemonjkFileSelect.showPicker选取 "Android/data"目录下的文件,否则直接调用将不会。
//3.仅需用户首次授权即可,永久有效,除非应用被卸载。
lemonjkFileSelect.grantSecurityScope({
securityScope:"data",
securityPackageName: "com.android.egg"
}, result => {
console.log(result);
// result.code 状态码【1005 用户授权成功】
// result.errMsg 选择完成后的状态信息
// result.detail 具体的文字说明
})
//提示:
//用户授权成功后,请自行保存维护该包名对应文件夹的授权记录
//如storage持久化:[{PackageName:"com.android.egg",isGrant:true}],
//以后无需调用lemonjkFileSelect.grantSecurityScope授权该包名下的文件夹,可直接调用lemonjkFileSelect.showPicker进行选取
可配置参数说明
属性 | 类型 | 说明 | 兼容性 |
---|---|---|---|
securityPackageName | string | 【可选】"Android/data" 下要访问的包名,可以参考自己手机目录"Android/data" 下的包名进行设置如果需要选取 "Android/data" 安全目录下的文件,请设置该属性,不需要则不要声明该属性 |
仅安卓 |
securityScope | string | 【可选】安全访问的根目录,暂时只支持 "data" 如果需要选取 "Android/data" 安全目录下的文件,请设置该属性,不需要则不要声明该属性注:securityPackageName和securityScope需要同时设置才能访问 "Android/data" 下的目录 |
仅安卓 |
返回值说明
属性 | 类型 | 说明 | 兼容性 |
---|---|---|---|
code | string | 状态码: 1005 用户授权成功(仅安卓) |
|
errMsg | string | 选择完成后的状态信息 | |
detail | string | 具体的文字说明 |
4.showNativePicker(仅4.0.0+插件安卓)
打开安卓原生的文件选择器,
参考说明1.showPicker(showPicker的大部分配置参数都可以生效,具体查看兼容性说明)
5.getAllExternalStorage(仅4.0.0+插件安卓)
获取外接存储设备列表,如sd卡、u盘、移动硬盘等,仅高版本安卓系统支持,低版本系统在适配中。。。。
可配置参数说明
返回值说明
返回当前手机所有已连接的外接存储设备路径列表,可使用该列表中的路径传给showPicker使用,实现打开对应外接设备文件选取
lemonjkFileSelect.getAllExternalStorage({}, result => {
this.pathScope=result.storages[1];
// 拿到路径地址后可以调用showPicker访问
})
6.isHaveSecurityScopeGrant(仅4.0.1+插件,安卓端)
查询手机是否拥有文件相关权限,插件本身在唤起文件选择时会自动检查权限,当没有权限时会自动请求相关权限。 一种特殊情况: 当上架应用商店可能会有如下要求:在申请权限之前,应用需要先弹出提示告知用户,并对要申请的权限进行说明,才能申请权限,否则无法审核通过上架。 你可以使用该API先检查是否有权限,如果没有权限先提示用户,用户确认后,再调用文件选择器。
可配置参数说明
返回值说明
属性 | 类型 | 说明 | 兼容性 |
---|---|---|---|
code | string | 状态码: 0 权限状态查询成功 |
4.0.1+ |
type | string | 固定值:"FILE_PERMISSON" | 4.0.1+ |
result | string | "yes" 已拥有文件相关权限,可以正常选择文件 "no" 没有权限,请先提示用户同意授权 |
4.0.1+ |
errMsg | string | 调用完成后的状态信息 | 4.0.1+ |
detail | string | 具体的文字说明 | 4.0.1+ |
示例
lemonjkFileSelect.isHaveSecurityScopeGrant({}, result => {
console.log(result);
})
7.gotoAllowReadAllFilesSetting(仅4.1.0+插件,安卓端)
打开【所有文件读取权限】设置页面
可配置参数说明
返回值说明
示例
lemonjkFileSelect.gotoAllowReadAllFilesSetting({}, result => {
console.log(result);
})
8.shareFile(仅4.0.2+插件,安卓端。ios暂不支持)
唤起系统分享,分享指定文件给第三方应用
可配置参数说明
属性 | 类型 | 说明 | 兼容性 |
---|---|---|---|
fileAbsPath | string | 必填,需要分享的文件的绝对路径,支持来自于本文件选择器或unipp相关Api返回的路径 | 4.0.2+ |
targetApp | string | 第三方应用包名,用于分享给指定的第三方应用,不填则由用户自行选择 | 4.0.2+ |
返回值说明
二、兼容性说明
目前仅测试了部分系统版本,其他系统版本兼容性未知,请自行测试,测试可用可以反馈,帮助更多人。
三、问题反馈与收集
感谢使用,如需使用[UTS]版文件选取,请使用此插件:https://ext.dcloud.net.cn/plugin?id=12988
目前收集的问题(Q&A):
1.(ios)控制台报错:自定义基座不包含本插件:请不要使用ios模拟器运行,使用真机运行即可
2.(安卓)选择大文件时短暂黑屏:4.0.0已解决