更新记录

2.0.0（2026-06-04） 下载此版本

• 重要升级 媒体库整体 UI 升级为侧边栏工作台布局，统一媒体资源、上传、免费素材库、标签管理等入口
• 新增 扩展存储支持，目前支持七牛云扩展存储，上传、删除、预览等流程会根据存储来源处理资源 文档
• 新增 标签管理能力，支持创建标签、按标签筛选媒体、上传时关联标签、为单个或批量媒体设置标签
• 新增 独立上传页，支持选择存储位置、按图片/视频类型上传，并支持点击选择、拖拽、粘贴上传
• 新增 图片裁剪功能，可在媒体详情中对图片进行裁剪并上传保存裁剪结果
• 优化 从免费素材库选择资源后加入上传列表，可再选择存储位置和标签后保存到媒体库
• 优化 媒体信息面板，支持资源信息展示、标签维护、图片裁剪上传等能力
• 优化 媒体列表、免费素材库列表和筛选操作的交互体验

1.1.1（2024-11-19） 下载此版本

• 修复 vue2 下无法运行的问题

1.1.0（2024-11-08） 下载此版本

• 新增 免费素材库功能，内置pexels、unsplash、giphy素材库，支持在线搜索、自定义素材库等 查看文档
• 优化 删除媒体资源时允许不删除源文件
• 修复 在图片或视频tab下无法搜索的问题
• 修复 图片数量过多时，无法显示图片的问题
• 修复 裁剪规则无效的问题

平台兼容性

云端兼容性

uni-app(4.87)

uni-app x(4.87)

其他

uni-admin插件通用教程：

uni-admin是一套基于uniCloud的开源应用管理端系统。详见：uni-admin 基础框架
本插件是uni-admin系统的扩展插件，为开发者的admin系统添加功能。
需先确保本机有uni-admin项目，然后将此插件导入到uni-admin项目下。
如本机没有uni-admin项目，需要先在HBuilderX中新建项目 -> uni-app项目 -> 选择uni-admin模板。
如本机的uni-admin项目版本过老，可能无法使用新插件，需及时升级本机的uni-admin项目。详见uni-admin项目更新日志

媒体库

管理上传的云存储图片、视频等媒体资源，支持对资源上传、删除、查看等操作。

功能点

• 支持支付宝云、阿里云、腾讯云云存储。
• 支持扩展存储，目前支持七牛云扩展存储。
• 对媒体资源管理，支持上传、删除、查看等操作。
• 支持媒体资源的标签管理，方便对媒体资源进行分类和查询。
• 支持对媒体库中的图片资源进行裁剪优化。
• 可作为图片选择器使用，支持插入图片到编辑器中。
• 集成免费素材库，快速获取图片、gif等素材。

如何使用

从插件市场中导入媒体库 插件至uni-admin中。

如果还未使用过uni-admin，请先在HBuilderX新建项目时选择uni-admin项目。并需要了解uni-admin 的相关知识。

导入uni-media-library后，运行启动uni-admin，在web管理后台，点击左侧菜单栏的菜单管理，添加“媒体库”菜单。

如下图所示：

导入后刷新页面，在uni-admin左侧菜单，可看到媒体库的菜单项，点击即可进入。

前端组件使用

媒体库可做为独立的组件使用，例如文章封面可以通过媒体库组件来选择图片，不需要每次都重新上传图片。

基本用法

uni-media-library 组件符合 easycom 组件规范，可以直接在页面中使用 uni-media-library 标签，以使用媒体库组件。

<template>
    <uni-media-library></uni-media-library>
</template>

API

UniMediaLibrary Props

UniMediaLibrary Events

SelectedMediaItems 说明

云对象 (uni-media-library-co)

在 uni-media-library-co 云对象中实现了对媒体资源的上报与删除功能。

配置@co-config

uni-media-library的云端配置文件统一使用uni-config-center管理。

初次使用时，新建配置文件， 路径为 uni_modules/uni-config-center/uniCloud/cloudfunctions/common/uni-config-center/uni-media-library/config.json ，用于配置uni-media-library相关信息，完整配置如下:

注意：以下注释仅用于对字段进行描述，复制时请删除注释。

{
  // 加载媒体库列表时是否启用缩略图规则
  "cropMediaAssets": false,
  // 扩展存储配置；不配置时仅使用内置存储
  "extStorage": {
    // 扩展存储服务商，目前仅支持 qiniu
    "provider": "qiniu",
    // 七牛云绑定的访问域名，如 example.com
    "domain": "your-cdn-domain.com",
    // 可选，七牛云存储空间名称；不填时由扩展库从绑定空间中获取
    "bucketName": "your_bucket_name",
    // 可选，七牛云存储空间密钥；不填时由扩展库从绑定空间中获取
    "bucketSecret": "your_bucket_secret"
  },
  // 内置图片素材库
  "imageLibraryProviders": {
    // 是否开启unsplash图片库
    "unsplash": {
      "appId": "your_app_id",
      "accessKey": "your_access_key",
      "secretKey": "your_secret_key"
    },
    // 是否开启giphy图片库
    "giphy": {
      "apiKey": "your_api_key"
    },
    // 是否开启pexels图片库
    "pexels": {
      "apiKey": "your_api_key"
    },
    // 自定义素材库
    "others": [
      {
        "provider": "custom_provider",
        "name": "custom_name",
        "website": "custom_website",
        "options": {}
      }
    ]
  }
}

完整配置字段说明

扩展存储配置@ext-storage

媒体库默认使用 uniCloud 内置存储。配置扩展存储后，上传资源时可选择“扩展存储”。

启用步骤：

1. 在 uni-media-library-co 云对象中关联 uni-cloud-ext-storage 扩展库。
2. 在 uni-media-library/config.json 中配置 extStorage.provider 为 qiniu。
3. 配置 extStorage.domain 为扩展存储绑定的域名，如 example.com。
4. 如果扩展库无法自动从绑定空间中获取存储空间信息，可继续配置 bucketName、bucketSecret。
5. 上传并运行云对象后，媒体库上传页会显示“扩展存储”选项。

配置示例：

{
  "extStorage": {
    "provider": "qiniu",
    "domain": "your-cdn-domain.com"
  }
}

使用扩展存储上传的媒体资源，storageProvider 会记录为 ext-qiniu。删除媒体资源时，媒体库会根据 storageProvider 区分内置存储和扩展存储，并删除对应的源文件及视频封面。

媒体资源上报接口

接口名：report

接口形式

await uniMediaLibrary.report({
  src,
  cover,
  type,
  originalName,
  fileType,
  size,
  resolution,
  duration,
  uploadUser,
  storageProvider,
  tags
})

参数说明

Resolution说明

返回值

删除媒体资源

接口名：deleteMedia

接口形式

await uniMediaLibrary.deleteMedia({
  mediaIds
})

参数说明

返回值

注意

• 删除媒体资源时将会同时删除云存储文件，删除后将无法恢复，请谨慎操作。

uni-media-library Schema 扩展

负责处理与媒体库资源创建时的逻辑

主要功能有：

在读取（afterRead）媒体库资源后，根据uni-media-library配置文件中的cropMediaAssets字段，为图片和视频封面追加缩略图处理规则。

优化媒体库图片加载速度

默认媒体库列表会加载原图展示，图片较大时会影响加载速度，也会造成不必要的 CDN 流量消耗。可以通过 uni-media-library 云对象配置文件开启 cropMediaAssets，让媒体库在读取数据时为图片和视频封面追加缩略图处理规则。

具体配置参考uni-media-library-co配置

开启方式：

{
  "cropMediaAssets": true
}

开启后：

• 媒体库列表图会使用约 150x150 的缩略图规则。
• 媒体详情预览会使用约 300x180 的缩略图规则。
• 图片资源使用 src 生成缩略图规则；视频资源使用 cover 生成缩略图规则。
• 该配置只在读取媒体库数据时追加展示用的缩略图规则，不会修改数据库中保存的原始 src、cover 地址，也不会主动生成新的媒体文件。
• 如果资源来自扩展存储七牛云，会使用七牛的图片处理规则；如果资源来自 uniCloud 内置存储，会根据文件地址匹配阿里云或腾讯云的图片处理规则。

注意

根据您开通的服务空间不同，图片裁剪的功能也不同，具体如下：

• 阿里云图片裁剪目前可免费使用，无需担心费用问题。
• 腾讯云图片裁剪为付费服务，如使用腾讯云，建议您在使用前先了解腾讯云的计费规则，避免造成不必要的费用。
• 七牛云扩展存储的图片处理能力和费用以七牛云当前规则为准，建议在正式开启前确认对应空间的图片处理配置和计费方式。

关于云存储数据处理，内置存储请参考数据处理， 扩展存储请参考图片处理。

免费素材库@image-library

为了方便快速获取图片素材，媒体库提供了免费素材库功能，目前内置了unsplash、giphy、pexels三个免费素材库。

同时支持自定义素材库，可通过配置文件添加自定义素材库。

内置素材库

默认情况下，内置的素材库是关闭的，需要在配置文件中开启。

在配置文件中配置imageLibraryProviders字段，如下：

{
  "imageLibraryProviders": {}
}

根据实际需求，配置对应的素材库。

注意

使用素材库时，需遵守素材库的使用协议，防止侵权行为发生， 以下是三个素材库的使用协议：

• unsplash
• giphy
• pexels

unsplash

unsplash是一个免费的图片素材库，提供了大量高质量的图片素材。

unsplash素材库以摄影作品居多，风景、人物等。

开启unsplash素材库，配置如下：

{
  "imageLibraryProviders": {
    "unsplash": {
      "appId": "your_app_id",
      "accessKey": "your_access_key",
      "secretKey": "your_secret_key"
    }
  }
}

获取unsplash的appId、accessKey、secretKey

1. 注册unsplash账号，登录后进入unsplash开发者页面。
2. 创建应用，获取appId(applicationId)、accessKey、secretKey。
3. 将appId(applicationId)、accessKey、secretKey填入配置文件中。
4. 保存配置文件。
5. 刷新页面，即可使用unsplash素材库。

giphy

giphy是一个免费的gif素材库，提供了大量高质量的gif素材。

giphy素材库以gif动画作品居多，表情包、动态图等。

giphy仅适用于个人和非商业用途，具体协议内容请查看giphy用户协议。

开启giphy素材库，配置如下：

{
  "imageLibraryProviders": {
    "giphy": {
      "apiKey": "your_api_key"
    }
  }
}

获取giphy的apiKey

1. 注册giphy账号，登录后进入giphy开发者页面。
2. 在dashboard中创建apiKey。
3. 将apiKey填入配置文件中。
4. 保存配置文件。
5. 刷新页面，即可使用giphy素材库。

pexels

pexels是一个免费的图片素材库，提供了大量高质量的图片素材。

开启pexels素材库，配置如下：

{
  "imageLibraryProviders": {
    "pexels": {
      "apiKey": "your_api_key"
    }
  }
}

获取pexels的apiKey

1. 注册pexels账号，登录后进入pexels API页面。
2. 创建apiKey。
3. 将apiKey填入配置文件中。
4. 保存配置文件。
5. 刷新页面，即可使用pexels素材库。

自定义素材库

除了内置的素材库外，还支持自定义素材库。

可以通过配置文件添加常用的素材库使用。

配置

在配置文件中配置imageLibraryProviders.others字段，如下：

{
  "imageLibraryProviders": {
    "others": [
      {
        "provider": "custom_provider", // 自定义素材的provider，切勿与内置素材库重复
        "name": "custom_name", // 自定义素材的名称，用于在媒体库中展示
        "website": "custom_website", // 自定义素材的网站地址（可选）
        "options": {} // 自定义素材的配置, 用于请求素材库的参数
      }
    ]
  }
}

实现自定义素材库逻辑

添加完自定义素材库配置后，需要自行实现素材搜索和查询素材详情的逻辑。

在配置文件同级目录中创建image-library/{provider}/index.js文件，用于存放自定义素材库的逻辑。

需要导出search、detail两个方法，具体实现如下：

自定义素材库逻辑示例

exports.search = async function (query, options) {
  const {keyword, page, pageSize} = query // query为搜索条件
  // options为请求参数(即配置文件中配置的options字段)

  // ::TODO:: 实现自定义素材库的搜索逻辑

  // 返回素材库的搜索结果
  return [
    {
      id: '', // 素材id，用于查询素材详情
      url: '', // 素材图片地址（原图）
      thumbUrl: '', // 素材缩略图地址
      width: 0, // 素材宽度
      height: 0, // 素材高度
      description: '', // 素材描述
      alt: '', // 用于图片加载失败时的替代文字
      originalName: '', // 原始文件名
    }
  ]
}

exports.detail = async function (id, options) {
  // id为素材id
  // options为请求参数(即配置文件中配置的options字段)

  // ::TODO:: 实现自定义素材库的查询素材详情逻辑

  // 返回素材详情
  return {
    id: '', // 素材id，用于查询素材详情
    url: '', // 素材图片地址（原图）
    thumbUrl: '', // 素材缩略图地址
    width: 0, // 素材宽度
    height: 0, // 素材高度
    description: '', // 素材描述
    alt: '', // 用于图片加载失败时的替代文字
    originalName: '', // 原始文件名
    fileType: '', // 文件类型
    size: 0, // 文件大小
  }
}

设置自定义素材库图标

到目前为止你打开媒体库，应该可以在左侧看到你添加的自定义素材库了，但是图标是默认的。

如果你想要为自定义素材库设置一个图标，可以修改uni_modules/uni-meidia-library/components/image-library-logos/index.vue文件。

在该文件添加你的自定义素材库图标，推荐使用svg图片作为图标使用(图片大小24像素)，示例如下：

<template v-else-if="provider === 'custom'">
    <svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"></svg>
</template>

添加后，刷新页面，即可看到自定义素材库的图标。