更新记录

4.1.1（2024-07-29） 下载此版本

1.修复安卓端原生选择器选择第三方应用内文件时无效的问题

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

平台兼容性

原生插件通用使用流程：

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[文件选择]

一、基本使用

使用前须知：

• 推荐优先使用【下载for离线打包】方式下载插件包，然后在项目中引入。此方式同样可以云打包，且插件包是存放在本地项目中的，所以不用开发者绑定账号，任何人复制你的项目都可以直接使用插件打包，更适合多人开发\交付项目。可以不受插件后续版本更新的影响。 详见: https://ask.dcloud.net.cn/article/35844
• 已适配安卓14.x( SdkVersion>=34)版本 ,满足上架谷歌商店的新应用需要targetSdkVersion>=33的规定，本插件(>=3.1版)经测试可以在targetSdkVersion>=34条件下正常选取文件。
• 已在部分真机(详情见：二、兼容性说明)测试通过,其他系统版本、机型未知，请自行测试。

本插件特色:

• 多端支持: 支持安卓和苹果双平台使用
• 可以获取当前手机连接的所有外接存储设备(sd卡、u盘、移动硬盘等)，并可访问对应的外接存储设备
• 支持大文件选取。多线程处理大文件读取，选取更快，异步返回结果。
• 文件读取时可配置加载提示，更好的用户体验。
• 多种文件选择方式: 安卓端支持自定义文件选择器和原生文件选择器,苹果端支持原生文件选择器。其中自定义文件选择器支持个性化UI界面，适配夜间模式，可以根据系统自动切换。（通过调用不同API选择）
  • 原生文件选择器和自定义文件选择器有何区别？
    • 原生文件选择器是安卓系统内置的。不可定制界面，与应用风格不协调，可配置属性少，无法满足定制化需求，操作体验不好。但是可以不用申请各种权限，官方推荐，可以让用户放心隐私问题。
    • 自定义文件选择器是开发者自行制作编写的。界面可任意定制，理论上可配置任何属性样式，满足定制化需求，但需要申请读写权限，高版本安卓（13.x）还需要MANAGE_EXTERNAL_STORAGE权限（此权限上架不了谷歌商店），同时用户可能并不会愿意授权。
  • 我该如何选择？
    • 第一要考虑的就是是否需要上架谷歌商店，若无此方面考虑则可放心使用自定义文件选择器，但仍然建议使用原生文件选择器。
    • 看老板怎么说？原生文件选择器界面太丑？改！
    • 当原生文件选择器没办法满足特定的需求，如：指定只能选择特定的几个文件类型（其实可以在用户选择后对后缀名作判断，让用户重新选择），建议使用自定义文件选择器
    • 只是简单选择个文件？建议使用原生文件选择器
• 支持多选，同时选取多个文件。
• 插件支持权限检查，支持申请权限,跳转到APP权限设置页。
• 支持限制文件类型选取（安卓为mime类型,ios为utis类型），实现限制文件类型选取。
• （安卓）支持访问指定目录，方便用户在指定目录快速选取。

  新版本特别说明：

• 本插件(4.0.0+)已完全进行重构，与之前版本的使用方式不完全兼容，但大多数配置仍可使用,推荐使用最新版本。
• 为避免与之前旧版本(4.0.0以下)插件可能存在的冲突，使用新版本（4.0.0+）前请移除本插件的旧版本。
• 版本4.0.4+开始，需要在manifest.json -> APP原生插件配置->本插件下的[appid_android]输入框中填入你的应用包名，自行离线打包见本文档最后的‘问题反馈与收集’

1.在页面引入

不要忘了在 "manifest.json -> APP原生插件配置" 内添加本插件，否则云打包（离线打包）不会生效

const lemonjkFileSelect = uni.requireNativePlugin('lemonjk-FileSelect');

2.唤起文件选择

lemonjkFileSelect.showPicker({
    //各属性配置见下方【showPicker可配置参数说明】
    pathScope: "/Download",  
    mimeType: "*/*",
    utisType:["public.data"],
    }, result => {
    // 返回值说明见下方【showPicker返回值说明】
            console.log(result);
    })
//showPicker在苹果端唤起的是原生文件选择器
//showPicker在安卓端唤起的是自定义文件选择器,如需唤起原生选择器请调用showNativePicker

二、插件方法和参数配置

1.showPicker

4.0.0+安卓端变更为唤起的是自定义文件选择器，如需打开原生文件选择器请调用： lemonjkFileSelect.showNativePicker

示例

lemonjkFileSelect.showPicker({
    pathScope: "/Download",  
    mimeType: "*/*",
    utisType:["public.data"],
    multi:'yes'
}, result => {})

//4.0.0+ 安卓自定义文件选择器使用及高级筛选器配置示例
lemonjkFileSelect.showPicker({
    mimeType: "*/*",
    utisType:["public.data"],
    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.1.1+插件，安卓端)

查询手机是否拥有文件相关权限(仅自定义文件选择器需要,原生选择器无需任何权限) 一种特殊情况： 当上架应用商店可能会有如下要求：在申请权限之前，应用需要先弹出提示告知用户，并对要申请的权限进行说明，才能申请权限，否则无法审核通过上架。 你可以使用该API先检查是否有权限，如果没有权限先提示用户，用户确认后，再开始申请权限,有权限后再调用文件选择器。

可配置参数说明

无

返回值说明

示例

const _this=this;
lemonjkFileSelect.isHaveSecurityScopeGrant({
                    type:"FILE_PERMISSION"   //不填默认为"FILE_PERMISSION"，可选值："FILE_PERMISSION"（用于自定义文件选择器相关权限查询）
                }, result => {
                    console.log(result);
                    if(result.result=="yes"){
                        //有权限,可以直接唤起自定义文件选择器
            //lemonjkFileSelect.showPicker()
                    }else{
            //无权限,询问用户是否同意申请权限
                        uni.showModal({
                            content:"需要申请文件访问权限，是否同意",
                            success(e) {
                                if(e.confirm){
                                    // lemonjkFileSelect.reqCustomPickerPermission()
                                }else{

                                }
                            }
                        })
                    }
})

7.reqCustomPickerPermission(仅4.1.1+插件，安卓端)

申请自定义文件选择器所需的权限

可配置参数说明

无

返回值说明

无

示例

lemonjkFileSelect.reqCustomPickerPermission({}, result => {
                    if(result.code==3002){
            //用户同意了权限,可以唤起自定义文件选择器
                        //lemonjkFileSelect.showPicker()
                    }else{
            //用户拒绝了权限
                        uni.showToast({
                            title:"你拒绝了授权"})
                    }
                    console.log(result);
})

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

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

可配置参数说明

返回值说明

无

二、兼容性说明

目前仅测试了部分系统版本,其他系统版本兼容性未知，请自行测试。

三、问题反馈与收集

目前收集的问题（Q&A）：
1.(ios)控制台报错:自定义基座不包含本插件:请不要使用ios模拟器运行,使用真机运行即可
2.(ios)唤起文件选择器闪退,utisType 属性为必填项,请确认是否填写了该属性
3.(安卓)需要自己离线打包的，可能会报未设置LEMONJK_APPID，解决办法如下：
      打开 build.gradle(Module:app) 配置文件，在相应节点填加对应配置项： 
      android {
          ...
          defaultConfig {
             ...
              //在该节点填加以下配置，并填入你的应用包名
              manifestPlaceholders = [LEMONJK_APPID: "此处填入你的包名"]
          }
      }