更新记录

1.0.0（2026-01-24）

平台兼容性

uni-app(3.6.15)

uni-app x(3.6.15)

Vnxn Media Gallery 原生媒体库插件

vnxn-media-gallery 是一款基于 UTS 开发的 UniApp 原生插件（支持 Android）。它允许开发者高性能地访问设备系统相册、分页加载图片和视频、生成缩略图以及处理文件缓存。

📱 示例 App 下载 & 购买须知 (推荐)

为了确保插件功能满足您的具体需求，且兼容您的目标设备，强烈建议您在购买前下载示例 App 进行真机测试。

⬇️ 示例 App 下载地址: https://www.123865.com/s/SG4DVv-hweud

⚠️ 温馨提示: 请务必在真机上测试各项功能（如读取相册、生成缩略图等）确认无误后再下单。

✨ 核心特性

• 高性能: 直接调用 Android 原生 MediaStore API，毫秒级加载。
• Android 13+ 适配: 完美支持 Android 10/11/12/13+ 的分区存储机制。
• 功能丰富: 支持相册获取、媒体分页筛选、视频/图片缩略图生成、沙盒文件缓存。
• 类型安全: 提供 TypeScript 定义，开发体验更佳。

平台支持

⚙️ 权限配置 (重要)

在使用插件前，请务必在 manifest.json -> App模块权限配置 -> Android打包权限配置 中勾选以下权限：

基础权限:

• <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/> (Android 12 及以下)

Android 13+ 专用权限 (TargetSDK >= 33):

• <uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>
• <uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/>

⚠️ 注意: 插件内部会自动判断系统版本请求对应权限，但你必须在 manifest.json 中声明它们，否则会导致获取相册为空。

🚀 快速开始

import { 
    getAlbums, 
    getMedia, 
    makeThumbnail, 
    clearCache, 
    cacheFile 
} from "@/uni_modules/vnxn-media-gallery";

📚 API 文档

1. getAlbums(options)

获取设备中的相册（文件夹）列表。

参数说明 (Options):

⚠️ 注意是 images 复数 | | success | Function | 否 | - | 成功回调，返回 AlbumItem[] | | fail | Function | 否 | - | 失败回调 |

返回数据 (AlbumItem):

示例代码:

getAlbums({
    filter: "video",
    success: (res) => {
        // res.data: AlbumItem[]
        console.log("发现相册数量:", res.data.length);
        res.data.forEach(album => {
             console.log(`相册: ${album.bucketName}, ID: ${album.bucketId}, 数量: ${album.count}`);
        });
    }
});

2. getMedia(options)

分页获取媒体文件列表（支持按相册筛选）。

参数说明 (Options):

返回数据 (MediaItem):

示例代码:

getMedia({
    page: 1,
    pageSize: 20,
    bucketId: "540528482", 
    filter: "images", // 注意这里是 images
    success: (res) => {
        console.log("图片列表:", res.data);
    }
});

3. makeThumbnail(options)

生成或获取媒体文件的缩略图。

参数说明 (Options):

示例代码:

makeThumbnail({
    id: "10245", 
    path: "content://media/external/...", // path 必填
    type: "video",
    success: (res) => {
        // res.data 直接就是路径字符串
        console.log("缩略图路径:", res.data); 
    }
});

4. cacheFile(options)

将外部文件（如 content://）复制到 App 临时沙盒目录，转为 file:// 路径。

参数说明 (Options):

示例代码:

cacheFile({
    path: "content://media/external/images/media/1024",
    success: (res) => {
        // 注意：res.data 直接就是路径字符串，不是对象
        const sandboxPath = res.data; 
        console.log("沙盒路径:", sandboxPath);

        uni.uploadFile({
            url: '...',
            filePath: sandboxPath,
            name: 'file'
        });
    }
});

5. clearCache(options)

清理插件生成的临时缓存文件（缩略图、预览图）。

参数说明:

示例代码:

clearCache({
    success: (res) => console.log("清理了 " + res.data + " 个缓存文件")
});

常见问题 (FAQ)

Q: 为什么 getAlbums 返回空数组？ A: 请检查是否已获取 READ_EXTERNAL_STORAGE (Android < 13) 或 READ_MEDIA_IMAGES (Android 13+) 权限。部分手机系统需要在系统设置中手动“允许管理所有文件”或“允许访问媒体”。

Q: 缩略图路径是永久有效的吗？ A: 不是。makeThumbnail 生成的是临时文件，建议每次使用时检查或重新生成。调用 clearCache 会删除这些文件。

Q: 自定义基座调试报错？ A: 由于本插件包含原生代码，必须制作自定义基座后才能在手机上运行调试。标准基座无法运行原生插件。

如有任何疑问或遇到技术问题，欢迎在插件市场评论区留言。