更新记录

1.0.0（2025-08-29） 下载此版本

实现：检测是否分享文件、获取分享文件路径

平台兼容性

云端兼容性

uni-app(4.76)

uni-app x(4.76)

piao-share

一个功能强大的uni-app分享文件处理插件，支持Android平台的文件分享检测、云文件下载和本地路径获取。

功能特性

✅ 自动检测分享文件 - 应用启动时自动检测分享Intent
✅ 支持多种文件来源 - 本地文件、WPS云文件、其他云存储文件
✅ 云文件自动下载 - 自动将云文件下载到本地临时目录
✅ Intent状态管理 - 智能清理Intent，支持连续分享
✅ 完整错误处理 - 详细的错误信息和用户反馈
✅ 类型安全 - 使用UTS编写，性能优异

安装配置

1. 安装插件

将 piao-share 文件夹复制到项目的 uni_modules 目录下。

2. 配置权限

在 manifest.json 中确保有以下权限：

{
  "app-plus": {
    "permissions": {
      "android.permission.READ_EXTERNAL_STORAGE": {},
      "android.permission.WRITE_EXTERNAL_STORAGE": {},
      "android.permission.INTERNET": {}
    }
  }
}

3. 导入插件

在需要使用的页面或组件中导入：

// #ifdef APP-PLUS
import { hasSharedFiles, getSharedFilePath } from '@/uni_modules/piao-share';
// #endif

API 文档

hasSharedFiles()

检测当前是否有分享文件。

返回值: boolean

• true: 检测到分享文件
• false: 没有检测到分享文件

使用示例:

const hasFiles = hasSharedFiles();
if (hasFiles) {
  console.log('检测到分享文件');
}

getSharedFilePath(options)

获取分享文件的详细信息。

参数: GetSharedFilePathOptions

interface GetSharedFilePathOptions {
  success?: (result: GetSharedFilePathResult) => void;
  fail?: (error: any) => void;
  complete?: (result: GetSharedFilePathResult | any) => void;
}

返回值: GetSharedFilePathResult

interface GetSharedFilePathResult {
  files: FileInfo[];
  count: number;
}

interface FileInfo {
  path: string;           // 文件路径（本地文件为file://，云文件会被下载到本地）
  originalUri: string;    // 原始URI
  name: string;           // 文件名
  size: number;           // 文件大小（字节）
  sizeString: string;     // 格式化的文件大小
  exists: boolean;        // 文件是否存在
}

使用示例:

getSharedFilePath({
  success: (result) => {
    console.log('获取到文件:', result.files[0]);
    // 处理文件上传等操作
  },
  fail: (error) => {
    console.error('获取文件失败:', error);
  },
  complete: (result) => {
    console.log('操作完成');
  }
});

完整使用示例

1. 基础使用

<template>
  <view>
    <button @click="checkShare">检查分享文件</button>
    <view v-if="fileInfo">
      <text>文件名: {{ fileInfo.name }}</text>
      <text>大小: {{ fileInfo.sizeString }}</text>
      <text>路径: {{ fileInfo.path }}</text>
    </view>
  </view>
</template>

<script setup>
import { ref } from 'vue';
// #ifdef APP-PLUS
import { hasSharedFiles, getSharedFilePath } from '@/uni_modules/piao-share';
// #endif

const fileInfo = ref(null);

const checkShare = () => {
  // #ifdef APP-PLUS
  if (hasSharedFiles()) {
    getSharedFilePath({
      success: (result) => {
        if (result.files.length > 0) {
          fileInfo.value = result.files[0];
        }
      },
      fail: (error) => {
        console.error('获取分享文件失败:', error);
      }
    });
  } else {
    uni.showToast({
      title: '没有检测到分享文件',
      icon: 'none'
    });
  }
  // #endif
};
</script>

2. 自动检测（推荐）

在 App.vue 中添加自动检测逻辑：

// App.vue
export default {
  onLaunch: function() {
    // #ifdef APP-PLUS
    setTimeout(() => {
      this.checkAndHandleSharedFiles();
    }, 300);
    // #endif
  },

  onShow: function() {
    // #ifdef APP-PLUS
    setTimeout(() => {
      this.checkAndHandleSharedFiles();
    }, 300);
    // #endif
  },

  methods: {
    // #ifdef APP-PLUS
    checkAndHandleSharedFiles() {
      try {
        const hasFiles = hasSharedFiles();
        if (hasFiles) {
          // 跳转到分享处理页面
          uni.navigateTo({
            url: '/pages/share-handler'
          });
        }
      } catch (error) {
        console.error('检查分享文件失败:', error);
      }
    }
    // #endif
  }
};

3. 文件上传集成

const handleSharedFile = async (fileInfo) => {
  try {
    // 使用获取到的本地路径进行上传
    const uploadResult = await uploadFile(fileInfo.name, fileInfo.path);
    console.log('上传成功:', uploadResult);
  } catch (error) {
    console.error('上传失败:', error);
  }
};

支持的文件类型

本地文件

• 文件路径: file:///storage/emulated/0/...
• 直接支持，无需额外处理

云文件（自动下载）

• WPS云文件: content://cn.wps.moffice_eng.fileprovider/...
• 其他云存储: 包含 cloud、external_storage_root、Android/data 等标识的URI
• 插件会自动下载到本地临时目录，返回本地路径

其他Content URI

• 标准Android Content Provider URI
• 支持查询文件信息

注意事项

1. 平台限制: 仅支持Android平台（APP-PLUS）
2. 临时文件: 云文件会被下载到应用缓存目录，应用重启后自动清理
3. 权限要求: 需要存储和网络权限
4. 文件大小: 大文件下载可能需要较长时间
5. Intent清理: 插件会自动清理Intent状态，支持连续分享

错误处理

插件提供完整的错误处理机制：

getSharedFilePath({
  success: (result) => {
    // 成功处理
  },
  fail: (error) => {
    // 错误处理
    console.error('错误代码:', error.errCode);
    console.error('错误信息:', error.message);
  },
  complete: (result) => {
    // 完成回调（无论成功失败）
  }
});

常见错误代码

• 9010001: 无法获取Activity或Intent
• 9010002: 处理过程中发生异常

性能优化建议

1. 延迟检测: 在应用启动后延迟300-800ms再检测分享文件
2. 缓存管理: 定期清理临时下载文件
3. 错误重试: 对于网络异常，可以实现重试机制

更新日志

v1.0.0

• ✅ 基础分享文件检测
• ✅ 云文件自动下载
• ✅ Intent状态管理
• ✅ 完整错误处理
• ✅ 类型安全支持

技术支持

• UTS 语法: UTS 语法文档
• UTS API插件: UTS API插件文档
• UTS 组件: UTS 组件文档
• Hello UTS: Hello UTS 示例

注意: 本插件仅支持Android平台，在H5、小程序等平台下会自动忽略相关代码。