更新记录

1.0.0（2026-01-12）

初版

平台兼容性

uni-app(4.75)

uni-app x(4.75)

f-album-read

自定义媒体相册能力使用说明（queryMedia / getFilePath）

1. 概述

1.1 queryMedia：分页查询媒体列表

用于从系统相册/媒体库中按类型分页查询媒体（图片、视频或全部），返回包含缩略图路径等信息的媒体列表。

1.2 getFilePath：将媒体标识转换为可访问路径

用于把 queryMedia 返回的媒体 identifier 转换为应用可访问的真实文件路径（用于读取原图/播放视频/上传等）。

2. 类型定义速览

2.1 MediaType

export type MediaType = 'image' | 'video' | 'all'

* `image`：仅图片
* `video`：仅视频
* `all`：图片+视频

### 2.2 MediaItem（单个媒体项）

```ts
export type MediaItem = {
  path: string          // 图片/视频首帧缩略图路径
  displayName: string   // 文件名
  mimeType: string      // MIME 类型，如 image/jpeg、video/mp4
  dateAdded: number     // 秒级时间戳
  duration?: number     // 视频时长（秒）；图片为 0 或不返回
  identifier: string    // 媒体文件标识，用于获取原图/原视频
}

3. queryMedia

3.1 函数签名

export type QueryMedia = (options: QueryMediaOptions) => void
export let queryMedia: QueryMedia

回调风格异步接口：通过 success / fail / complete 获取结果。

3.2 参数 QueryMediaOptions

export type QueryMediaOptions = {
  type?: MediaType
  limit?: number
  offset?: number

  success?: (res: QueryMediaResult) => void
  fail?: (err: QueryMediaFail) => void
  complete?: (res: any) => void
}

字段说明

• type（可选）：查询类型

  • 默认值：建议实现侧默认为 'all'（若实现不是如此，请以实现为准）

• limit（可选）：本次返回的最大条数

  • 正整数，如 20 / 50

• offset（可选）：偏移量（用于分页）

  • offset = 0 表示从第一条开始
  • 下一页为 offset + limit
• success（可选）：成功回调，参数为 QueryMediaResult
• fail（可选）：失败回调，参数为 QueryMediaFail
• complete（可选）：无论成功失败都会回调，便于收尾逻辑（隐藏 loading 等）

3.3 返回值 QueryMediaResult

export type QueryMediaResult = {
  list: MediaItem[]
}

• list：媒体项数组，按实现可能是按 dateAdded 倒序或其他排序。

3.4 使用示例

示例 1：查询最近 20 张图片

import { queryMedia } from '@/uni_modules/f-album-read'

queryMedia({
  type: 'image',
  limit: 20,
  offset: 0,
  success: (res) => {
    console.log('图片列表条数:', res.list.length)
    res.list.forEach(item => {
      console.log(item.displayName, item.mimeType, item.path, item.identifier)
    })
  },
  fail: (err) => {
    console.error('查询失败:', err.errCode, err.errMsg)
  },
  complete: () => {
    console.log('queryMedia complete')
  }
})

示例 2：分页加载（加载下一页）

let offset = 0
const limit = 30

function loadNextPage() {
  queryMedia({
    type: 'all',
    limit,
    offset,
    success: (res) => {
      // 追加到你的列表 UI
      const list = res.list
      console.log('本页返回:', list.length)

      // 更新 offset，准备下一页
      offset += limit

      // 如果 list.length < limit，通常表示没有更多数据（具体以实现为准）
      if (list.length < limit) {
        console.log('可能已加载完全部媒体')
      }
    },
    fail: (err) => {
      console.error('分页查询失败:', err.errCode, err.errMsg)
    }
  })
}

loadNextPage()

4. getFilePath

4.1 函数签名

export type GetFilePath = (options: GetFilePathOptions) => void
export let getFilePath: GetFilePath

4.2 参数 GetFilePathOptions

export type GetFilePathOptions = {
  identifier: string
  success?: (res: GetFilePathResult) => void
  fail?: (err: AlbumReadFail) => void
  complete?: (res: any) => void
}

字段说明

• identifier（必填）：媒体标识

  • 来源：queryMedia 返回的 MediaItem.identifier
• success：成功回调，返回 GetFilePathResult
• fail：失败回调，返回 AlbumReadFail
• complete：完成回调

4.3 返回值 GetFilePathResult

export type GetFilePathResult = {
  filePath: string
}

• filePath：可访问的真实文件路径（用于读取原图、上传、视频播放等）

4.4 使用示例

示例 1：通过 identifier 获取原始文件路径

import { queryMedia, getFilePath } from '@/uni_modules/f-album-read'

// 先查一条媒体
queryMedia({
  type: 'video',
  limit: 1,
  offset: 0,
  success: (res) => {
    const item = res.list[0]
    if (!item) return

    // 再把 identifier 转为可访问路径
    getFilePath({
      identifier: item.identifier,
      success: (r) => {
        console.log('原始文件路径:', r.filePath)
      },
      fail: (err) => {
        console.error('getFilePath 失败:', err.errCode, err.errMsg)
      }
    })
  },
  fail: (err) => {
    console.error('queryMedia 失败:', err.errCode, err.errMsg)
  }
})

示例 2：批量获取路径（串行）

function getFilePathsSequential(items: { identifier: string }[], done: (paths: string[]) => void) {
  const paths: string[] = []
  let i = 0

  const next = () => {
    if (i >= items.length) return done(paths)

    getFilePath({
      identifier: items[i].identifier,
      success: (res) => {
        paths.push(res.filePath)
        i++
        next()
      },
      fail: (err) => {
        console.error('某一项转换失败:', err.errCode, err.errMsg)
        // 失败策略：跳过或终止，按业务决定。这里选择跳过继续。
        i++
        next()
      }
    })
  }

  next()
}

5. 推荐调用流程

1. 使用 queryMedia 按需分页获取媒体列表（展示缩略图：item.path）。
2. 用户点击某一项后，使用该项的 identifier 调用 getFilePath 获取原始文件路径。
3. 使用返回的 filePath 执行读取/上传/播放等操作。

6. 错误处理建议

6.1 统一错误结构

queryMedia.fail 与 getFilePath.fail 都返回：

• errCode：错误码（数值）
• errMsg：错误描述（字符串）

6.2 常见处理策略（建议）

• errCode 表示权限相关：提示用户开启相册/媒体库权限后重试
• 读取失败/文件不存在：提示资源不可用，刷新列表或重试
• 分页查询空列表：视为无更多数据

7. 注意事项

• MediaItem.path 通常用于展示缩略图或首帧，不保证是原始文件路径。
• 获取原图/原视频请使用 getFilePath 转换 identifier。
• dateAdded 为秒级时间戳，如需毫秒请自行 * 1000。
• duration 仅对视频有意义；图片可能为 0 或不返回，使用时请判空。