更新记录

1.1.1（2025-07-22） 下载此版本

【重要】新增 `getInPath` 方法，用于获取指定路径下所有一级目录列表。具体定义如下：

*** 说明：获取指定路径下的所有一级目录列表，`v1.1.1` 及以上版本可用。
*** 类型：`get***InPath(path?: string, ***?: boolean, ***?: boolean): ***[]`
*** 参数说明：
  *** `path`：指定路径，默认为空，表示获取所有路径下的目录列表
  *** `***`：是否统计音频文件数量，默认`true`
  *** `***`：是否显示隐藏目录，默认`false`
*** 返回值说明：
  *** `***[]`：一级目录列表，每个目录包含`name`、`path`、`count` 等属性。
*** 示例：

  ```ts
  const *** = ref(false);
  const *** = ref<***[]>([]);
  const load*** = () => {
      ***.value = true;
      // 为了避免卡UI，需要在IO线程中执行
      UTSAndroid.getDispatcher('io').async((_action) => {
          const data = mediaManager.get***InPath(null, true, true);
          // 更新UI响应式数据需要回到主线程
          UTSAndroid.getDispatcher('main').sync((_) => {
              ***.value = data;
              ***.value = false;
        }, null);
      }, null)
  }
  load***();
  ```

1.1.0（2025-07-18） 下载此版本

• 【重要】调整 KuxMediaFileInfo 类型为 KuxLocalMedia，相关的参数类型同步修改。
• 【重要】调整 getMediaFileInfo 回调方法返回参数类型为 completion: (fileInfo: KuxLocalMedia | null) => void。
• 【重要】调整 getMediaFileInfoSync 方法返回类型为 Promise<KuxLocalMedia | null>。
• 【重要】新增 getExifInfo 方法，用于获取图片的 EXIF 信息。
• 【重要】getLocalVideos getLocalMusicList loadAlbums 方法新增参数 filter?: MediaFilterParams 用于筛选媒体。

1.0.0（2024-12-25） 下载此版本

• 初始版本发布。

平台兼容性

uni-app x(4.71)

kux-media-manager

一个获取相册媒体的媒体管理器插件，通过简洁的API即可快速获取相册媒体数据，方便灵活的对接任何UI展示相册文件。

插件特色

• 简介的API设计
• 支持获取视频，音频，最近照片视频。本地音乐等
• 支持获取媒体文件元数据信息
• 支持生成缩略图

基本用法

import { useMediaManager, MediaFilterParams } from '@/uni_modules/kux-media-manager';

const mediaManager = useMediaManager();

// 获取所有相册媒体
console.log(mediaManager.loadAlbums({} as MediaFilterParams));
// 获取相册分类名列表
console.log(mediaManager.getAlbumCategories());
// 获取指定分类的媒体数量
console.log(mediaManager.getMediaFileCountForAlbum('weixin'));
// 获取最近媒体数据
console.log(mediaManager.getRecentMedia());
// 获取指定分类下的媒体数据
console.log(mediaManager.getMediaFilesByAlbumName('Camera'));
// 获取本地视频
console.log(mediaManager.getLocalVideos({} as MediaFilterParams));
// 获取本地音乐列表
console.log(mediaManager.getLocalMusicList({
    minDuration: 60, // 最小时长
    minSize: 100 // 最小文件大小
} as MediaFilterParams));

注意

需要自定义基座才能正常使用该插件

API

isLoading

• 说明：是否正在获取媒体资源
• 类型：isLoading(): boolean

getAlbumCategories

• 说明：获取相册分类名列表
• 类型：getAlbumCategories(): string[]

getRecentMedia

• 说明：获取最近媒体数据
• 类型：getRecentMedia(): KuxLocalMedia[]

loadAlbums

• 说明：获取相册所有媒体
• 类型：loadAlbums(filter?: MediaFilterParams): KuxAlbum[]

getMediaFilesByAlbumName

• 说明：获取指定分类下的媒体数据
• 类型：getMediaFilesByAlbumName(name: string): KuxLocalMedia[]

getLocalVideos

• 说明：获取本地视频
• 类型：getLocalVideos(filter?: MediaFilterParams): KuxLocalMedia[]

generateVideoThumbnail

• 说明：生成视频缩略图
• 类型：generateVideoThumbnail(videoPath: string, completion: (thumbPath: string | null) => void): void

generateVideoThumbnailSync

• 说明：生成视频缩略图【同步版本】
• 类型：generateVideoThumbnailSync(videoPath: string): Promise<string | null>

getVideoDuration

• 说明：获取视频时长
• 类型：getVideoDuration(videoPath: string, completion: (duration: number | null) => void): void

getVideoDurationSync

• 说明：获取视频时长【同步版本】
• 类型：getVideoDurationSync(videoPath: string): Promise<number | null>

getLocalMusicList

• 说明：获取本地音乐列表
• 类型：getLocalMusicList(filter?: MediaFilterParams): KuxLocalMedia[]

getMediaFileInfo

• 说明：获取指定路径的媒体文件信息
• 类型：getMediaFileInfo(fileId: number, completion: (fileInfo: KuxMediaFileInfo | null) => void): void

getMediaFileInfoSync

• 说明：获取指定路径的媒体文件信息【同步版本】
• 类型：getMediaFileInfoSync(fileId: number): Promise<KuxMediaFileInfo | null>

getExifInfo

• 说明：获取媒体文件的EXIF信息，v1.1.1 及以上版本可用。
• 类型：getExifInfo(filePath: string): ExifInfo

getAudioDirectoriesInPath

• 说明：获取指定路径下的所有一级目录列表，v1.1.1 及以上版本可用。
• 类型：getAudioDirectoriesInPath(path?: string, isCountAudioFiles?: boolean, showHiddenDirs?: boolean): KuxAudioDirectory[]
• 参数说明：
  • path：指定路径，默认为空，表示获取所有路径下的目录列表
  • isCountAudioFiles：是否统计音频文件数量，默认true
  • showHiddenDirs：是否显示隐藏目录，默认false
• 返回值说明：
  • KuxAudioDirectory[]：一级目录列表，每个目录包含name、path、count 等属性。

• 示例：

  const isLoading = ref(false);
  const audioDirectories = ref<KuxAudioDirectory[]>([]);
  const loadAudioDirectories = () => {
    isLoading.value = true;
    // 为了避免卡UI，需要在IO线程中执行
    UTSAndroid.getDispatcher('io').async((_action) => {
        const data = mediaManager.getAudioDirectoriesInPath(null, true, true);
        // 更新UI响应式数据需要回到主线程
        UTSAndroid.getDispatcher('main').async((_) => {
            audioDirectories.value = data;
            isLoading.value = false;
      }, null);
    }, null)
  }
  loadAudioDirectories();

onError

• 说明：捕获全局错误
• 类型：onError(callback: (error: IUniError) => void): void

KuxAlbum 说明

KuxLocalMedia 说明

MediaFilterParams 说明

媒体过滤参数

ExifInfo 说明

图片文件的EXIF信息

export type ExifInfo = {
    // 基础信息
    orientation?: number; // 图像方向
    dateTime?: string; // 拍摄日期和时间
    dateTimeOriginal?: string; // 原始拍摄日期和时间
    dateTimeDigitized?: string; // 数字化日期和时间
    make?: string; // 设备制造商
    model?: string; // 设备型号
    software?: string; // 创建图像的软件
    // 拍摄参数
    exposureTime?: string; // 曝光时间
    fNumber?: number; // 光圈值
    isoSpeedRatings?: number; // ISO感光度
    focalLength?: number; // 焦距
    exposureBiasValue?: number; // 曝光补偿值
    meteringMode?: number; // 测光模式
    whiteBalance?: number; // 白平衡模式
    flash?: number; // 闪光灯状态
    sceneCaptureType?: number; // 场景捕捉类型（如人像、风景）
    sensingMethod?: number; // 感光方法（如单芯片彩色区域传感器）
    // 图像属性
    imageWidth?: number; // 图像宽度
    imageLength?: number; // 图像长度
    xResolution?: number; // 像素分辨率（水平）
    yResolution?: number; // 像素分辨率（垂直）
    resolutionUnit?: number; // 分辨率单位
    colorSpace?: number; // 色彩空间
    compression?: number; // 压缩类型
    // GPS信息
    gpsLatitude?: number; // 纬度
    gpsLongitude?: number; // 经度
    gpsAltitude?: number; // 海拔高度
    gpsAltitudeRef?: number; // 海拔高度参考
    gpsSpeed?: number; // 速度
    gpsSpeedRef?: string; // 速度参考
    gpsImgDirection?: number; // 方向
    gpsImgDirectionRef?: string; // 方向参考
    gpsDateStamp?: string; // GPS日期
    gpsTimeStamp?: string; // GPS时间
    // 其他信息
    artist?: string; // 艺术家
    copyright?: string; // 版权信息
    userComment?: string; // 用户评论
    subsecTime?: string; // 毫秒部分
    subsecTimeOriginal?: string; // 原始日期时间的毫秒部分
    subsecTimeDigitized?: string; // 数字化日期时间的毫秒部分
}

KuxAudioDirectory 说明

音频目录信息

export type KuxAudioDirectory = {
    id: string; // 目录ID
    name: string; // 目录名称
    path: string; // 目录路径
    depth: number; // 目录深度
    parentPath?: string; // 父路径
    fileCount: number; // 音频文件数量
    isScanned: boolean; // 是否已扫描
    children?: KuxAudioDirectory[]; // 子目录列表
    coverPath?: string; // 封面路径
    lastModified?: number; // 最后修改时间
    isHidden?: boolean; // 是否是隐藏目录，即点开头的目录名字
}

结语

kux 不生产代码，只做代码的搬运工，致力于提供uts 的 js 生态轮子实现，欢迎各位大佬在插件市场搜索使用 kux 生态插件：https://ext.dcloud.net.cn/search?q=kux

友情推荐

• TMUI4.0：包含了核心的uts插件基类.和uvue组件库
• UxFrame 低代码高性能UI框架：低代码高性能UI框架
• GVIM即时通讯模版：GVIM即时通讯模版，基于uni-app x开发的一款即时通讯模版
• t-uvue-ui：T-UVUE-UI是基于UNI-APP X开发的前端UI框架
• uXui: graceUI作者的免费开源组件库
• wx-ui 基于uni-app x开发的高性能混合UI库：基于uni-app x开发的高性能混合UI库，集成 uts api 和 uts component，提供了一套完整、高效且易于使用的UI组件和API，让您以更少的时间成本，轻松完成高性能应用开发。
• firstui-uvue：FirstUI（unix）组件库，一款适配 uni-app x 的轻量、简洁、高效、全面的移动端组件库。
• easyXUI 不仅仅是UI 更是为UniApp X设计的电商模板库：easyX 不仅仅是UI库，更是一个轻量、可定制的UniAPP X电商业务模板库，可作为官方组件库的补充,始终坚持简单好用、易上手