更新记录

1.0.0（2026-05-08）

自定义媒体选择器 (UTS)（图片、视频）

基于 UTS 实现的Android端图片/视频选择器，提供相册列表、网格视图、多选、预览、原图 / 压缩切换等功能。支持自定义主题色、布局、文字、控件尺寸等细节。

平台支持

现阶段仅支持安卓

注意事项

• 使用前请确保已申请存储读取权限（例如 WRITE_EXTERNAL_STORAGE 或 Android 13 后的媒体权限），插件本身不负责权限申请。
• 大图列表或视频预览时注意内存压力，插件已做 LRU 缓存和 Bitmap 回收，但仍建议在页面销毁时调用closeMediaChoose()或等待用户手动关闭。
• 兼容不同屏幕比例，但是在平板等宽屏设备上，建议通过config参数调大gridColumnCount，以获得更佳的浏览体验。
• 插件​本身没有内置自动跟随系统的暗黑模式切换功能​，但完全可以通过config 参数实现日间/暗黑模式的切换。
• • 所有视觉元素（背景色、文字色、蒙层、按钮等）在代码中都通过 config 来控制，没有任何颜色值是硬编码写死的。所以在调用 chooseMedia 前准备好两套配置，就能实现主题切换。
• • 切换主题配置后，需要重新调用 chooseMedia 才能生效。已经打开的选择器不会热更新。如果你需要在用户未关闭选择器的情况下实时切换，目前做不到
• ios暂未实现，敬请期待

快速开始

引入模块

import { chooseMedia, closeMediaChoose, MediaFilesResult, MediaConfig, ChooseMediaOptions } from "@/uni_modules/l-media";

最简调用（Promise / async-await）

const res = await chooseMedia({ count: 9 });
if (res) {
  console.log('已选择文件：', res);
} else {
  console.log('用户取消选择');
}

回调式调用

chooseMedia({
  count: 9,
  success: (res) => { console.log(res); },
  fail: (err) => { console.error(err); },
  complete: (res) => { console.log('完成'); }
});

自定义配置

// 默认配置
const mediaConfig : MediaConfig = {
  // 主题色
  primary: "#F94258",

  // 主界面背景
  bgColor: "#181818",
  navBarBgColor: "#222222",
  bottomBarBgColor: "#222222",

  // 文字颜色
  textColor: "#FFFFFF",
  textColorSecondary: "#999999",
  textColorDisabled: "#555555",

  // 蒙层 / 占位
  selectedMaskColor: "#80000000",
  imagePlaceholderColor: "#000000",
  videoTagBgColor: "#40000000",

  // 复选框颜色
  checkboxBgColor: "#33000000",
  checkboxStrokeColor: "#FFFFFF",

  // 按钮
  buttonInactiveColor: "#666666",

  // 相册菜单
  albumMenuDividerColor: "#333333",
  albumMenuBgColor: "#000000",

  // 预览界面
  previewNavBarBgColor: "#c0000000",
  previewBottomBarBgColor: "#c0000000",
  previewBgColor: "#000000",

  // 复选框尺寸 / 触摸区域
  checkboxSize: 50,
  checkboxTouchAreaSize: 40,
  checkboxTouchPaddingV: 20,
  checkboxTouchPaddingH: 20,

  // 网格布局
  gridColumnCount: 4,

  // 字号
  textSizeTitle: 17.0,
  textSizeBody: 15.0,
  textSizeTiny: 10.0,

  // 分页加载
  pageSize: 60,
  preloadThreshold: 50,

  // 图片压缩
  compressionQuality: 70
}

const customConfig: MediaConfig = {
  primary: '#007AFF',
  bgColor: '#F2F2F7',
  gridColumnCount: 3,
  pageSize: 40,
};
const files = await chooseMedia({ count: 5 }, customConfig);

强制关闭选择器

当需要从外部关闭弹出的选择器（例如页面返回时）

closeMediaChoose();

API 说明

chooseMedia(options, config?)

打开媒体选择器。

参数

• options: ChooseMediaOptions：— 选择行为配置（必填）
• config?: MediaConfig：— UI 及功能配置（可选，不传则使用默认深色主题）

返回值

• Android：— Promise<MediaFilesResult | null>

closeMediaChoose()

主动关闭选择器（带动画）。可用于外部监听到页面返回时关闭 UI。

选项说明

ChooseMediaOptions

MediaFile(返回的文件对象)

错误码

默认配置 mediaConfig

插件内置一套深色主题，可通过config参数覆盖任意属性。以下是默认值及说明：

export const mediaConfig: MediaConfig = {
  // 主题
  primary: "#F94258",                // 主色（按钮高亮、选中指示器）
  // 背景
  bgColor: "#181818",               // 网格列表背景
  navBarBgColor: "#222222",         // 顶部导航栏背景
  bottomBarBgColor: "#222222",      // 底部操作栏背景
  // 文字颜色
  textColor: "#FFFFFF",             // 主文字
  textColorSecondary: "#999999",    // 次级文字
  textColorDisabled: "#555555",     // 禁用态文字
  // 蒙层/占位
  selectedMaskColor: "#80000000",   // 已选蒙层底色
  imagePlaceholderColor: "#000000", // 缩略图加载占位色
  videoTagBgColor: "#40000000",     // 视频时长角标底色
  // 复选框样式
  checkboxBgColor: "#33000000",     // 未选中填充色
  checkboxStrokeColor: "#FFFFFF",   // 未选中描边色
  // 按钮
  buttonInactiveColor: "#666666",   // 发送按钮未激活底色
  // 相册菜单
  albumMenuDividerColor: "#333333", // 菜单分割线
  albumMenuBgColor: "#000000",      // 菜单背景
  // 预览界面
  previewNavBarBgColor: "#c0000000",    // 预览导航栏背景
  previewBottomBarBgColor: "#c0000000", // 预览底部条背景
  previewBgColor: "#000000",            // 预览页底色
  // 复选框尺寸/触摸区域（单位 px）
  checkboxSize: 50,
  checkboxTouchAreaSize: 40,
  checkboxTouchPaddingV: 20,
  checkboxTouchPaddingH: 20,
  // 网格
  gridColumnCount: 4,               // 每行图片数
  // 字号（sp）
  textSizeTitle: 17.0,
  textSizeBody: 15.0,
  textSizeTiny: 10.0,
  // 分页
  pageSize: 60,                     // 每页加载数量
  preloadThreshold: 50,             // 距底部多少px触发预加载
  // 压缩
  compressionQuality: 70,           // JPEG 压缩质量（0-100）
};

示例：仅选择视频，限制大小，自定义主题

const res = await chooseMedia({
  count: 3,
  mediaType: ['video'],
  maxSize: 50 * 1024 * 1024, // 50MB
  extension: ['mp4', 'mov'],
}, {
  ...mediaConfig,
  primary: '#34C759',
  previewBottomBarBgColor: '#50000000',
});

if (res) {
  res.forEach(file => {
    console.log(`视频: ${file.name}, 大小: ${file.size}, 时长: ${file.duration}s, 缩略图: ${file.thumbTempFilePath}`);
  });
}

平台兼容性

uni-app(3.99)

uni-app x(3.99)

其他

l-media

开发文档

UTS 语法 UTS API插件 UTS uni-app兼容模式组件 UTS 标准模式组件 Hello UTS