更新记录

1.0.0（2025-05-12）

版本：1.0.0 支持文件单选、多选 返回文件绝对路径和文件大小

平台兼容性

云端兼容性

uni-app

Android 文件选择器插件使用说明

简介

本插件是一个 uni-app 原生插件，用于在 Android 平台上调用系统的文件选择器。它支持用户选择单个或多个文件，并返回所选文件的本地绝对路径和文件大小。

主要功能

• 调用 Android 系统原生文件选择器。
• 支持选择单个文件。
• 支持选择多个文件。
• 返回选中文件的本地绝对路径。
• 返回选中文件的大小（单位：字节）。

集成步骤

1. 放置插件文件: 将 bc-file-explorer 组件文件夹（通常包含 bc-file-explorer.vue 文件）放置到您的 uni-app 项目的 components 目录下（或您选择的其他组件存放目录）。

2. 在页面中引入和注册组件: 在需要使用文件选择功能的页面的 <script> 部分引入并注册该组件。

   复制代码<script>
   // 假设您的插件放在 components/bc-file-explorer/bc-file-explorer.vue
   import BcFileExplorer from '@/components/bc-file-explorer/bc-file-explorer.vue';
   
   export default {
       components: {
           BcFileExplorer
       },
       // ... 其他代码
   }
   </script>

使用方法

1. 在模板中使用组件: 在页面的 <template> 部分，您可以将组件放置在页面中（它本身是不可见的，仅用于逻辑调用），并为其设置一个 ref 以便在脚本中调用其方法。同时，监听其 result 事件以获取选择结果。

   复制代码<template>
       <view>
           <button @click="selectFiles">选择文件</button>
           <bc-file-explorer ref="fileExplorerRef" @result="handleFileSelectionResult"></bc-file-explorer>
       </view>
   </template>

2. 触发文件选择: 通过调用组件实例的 open() 方法来打开文件选择器。

   复制代码// 在 <script> 的 methods 中
   methods: {
       selectFiles() {
           // 通过 $refs 调用组件的 open 方法
           if (this.$refs.fileExplorerRef) {
               this.$refs.fileExplorerRef.open();
           } else {
               console.error("bc-file-explorer 组件引用未找到!");
           }
       },
       handleFileSelectionResult(files) {
           // files 是一个数组，每个元素包含 { path: '...', size: '...' }
           if (files && files.length > 0) {
               console.log('选择的文件:', files);
               files.forEach(file => {
                   console.log(`文件路径: ${file.path}, 文件大小: ${file.size} 字节`);
               });
               // 在这里处理您的业务逻辑，例如文件上传、信息展示等
           } else {
               console.log('没有选择任何文件或选择被取消。');
           }
       }
   }

事件说明

• @result
  • 触发时机: 用户在文件选择器中完成文件选择（或取消选择）后触发。
  • 回调参数: files (Array)
    • 该参数是一个数组，数组中的每个元素都是一个对象，代表一个选中的文件。
    • 对象格式: { path: String, size: Number }
      • path: 文件的本地绝对路径 (例如: /storage/emulated/0/Download/document.pdf)。
      • size: 文件的大小，单位为字节。
    • 即使只选择了一个文件，回调参数也会是一个包含单个文件对象的数组。
    • 如果用户取消了文件选择，或者没有选择任何有效文件，将返回一个空数组 []。

所需权限

为了能够读取文件的路径和大小，本插件需要在 AndroidManifest.xml 中声明以下权限：

• android.permission.READ_EXTERNAL_STORAGE (读取外部存储权限)

配置方法: 在项目的 manifest.json 文件中，找到 app-plus -> permissions 模块进行配置。uni-app 通常会将此配置转换为 AndroidManifest 中的相应权限声明。