更新记录

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:修复安卓多个应用冲突

平台兼容性

原生插件通用使用流程：

1. 购买插件，选择该插件绑定的项目。
2. 在HBuilderX里找到项目，在manifest的app原生插件配置中勾选模块，如需要填写参数则参考插件作者的文档添加。
3. 根据插件作者的提供的文档开发代码，在代码中引用插件，调用插件功能。
4. 打包自定义基座，选择插件，得到自定义基座，然后运行时选择自定义基座，进行log输出测试。
5. 开发完毕后正式云打包

付费原生插件目前不支持离线打包。
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权限（此权限上架不了谷歌商店），同时用户可能并不会愿意授权。
  • 我该如何选择？
    • 第一要考虑的就是是否需要上架谷歌商店，若无此方面考虑则可放心使用自定义文件选择器，但仍然建议使用原生文件选择器。
    • 看老板怎么说？原生文件选择器界面太丑？改！
    • 当原生文件选择器没办法满足特定的需求，如：指定只能选择特定的几个文件类型（其实可以在用户选择后对后缀名作判断，让用户重新选择），建议使用自定义文件选择器
    • 只是简单选择个文件？建议使用原生文件选择器

      新版本（4.1.0+）特别说明：

• 变更：（安卓）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);
                })

可配置参数说明

返回值说明

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进行选取

可配置参数说明

返回值说明

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先检查是否有权限，如果没有权限先提示用户，用户确认后，再调用文件选择器。

可配置参数说明

无

返回值说明

示例

lemonjkFileSelect.isHaveSecurityScopeGrant({}, result => {
                    console.log(result);  
})

7.gotoAllowReadAllFilesSetting(仅4.1.0+插件，安卓端)

打开【所有文件读取权限】设置页面

可配置参数说明

无

返回值说明

无

示例

lemonjkFileSelect.gotoAllowReadAllFilesSetting({}, result => {
                    console.log(result);  
})

8.shareFile(仅4.0.2+插件，安卓端。ios暂不支持)

唤起系统分享，分享指定文件给第三方应用

可配置参数说明

返回值说明

无

二、兼容性说明

目前仅测试了部分系统版本,其他系统版本兼容性未知，请自行测试，测试可用可以反馈，帮助更多人。

三、问题反馈与收集

感谢使用，如需使用[UTS]版文件选取，请使用此插件：https://ext.dcloud.net.cn/plugin?id=12988

目前收集的问题（Q&A）：
1.(ios)控制台报错:自定义基座不包含本插件:请不要使用ios模拟器运行,使用真机运行即可
2.(安卓)选择大文件时短暂黑屏：4.0.0已解决