更新记录

1.1.4（2026-08-05）

新增

• 【三端】setChooseMediaConfig(config)：独立设置全局默认配置（持久生效），适合在应用启动 / 设置页直接调用；与 chooseMedia(options, config) 的合并语义一致。

修复

• 【安卓】原图转码正立（keepOriginalFormat=false）时，无 EXIF 旋转的 HEIC/HEIF/WebP 也会重编码为 JPEG，与文档说明一致（此前仅旋转图片会转码，直立 HEIC 会原样返回）。
• 【iOS】移除私有 API 读取：规避 App Store 审核风险，iCloud 未下载项显示「部分未下载」，超过 50 张只累计已缓存项），与安卓体积口径对齐；maxSize（含 maxSizeByType）在纯原图模式下不再做网格预筛，统一在导出后兜底校验（行为与压缩模式 / 鸿蒙一致）。
• 【iOS】视频方向烘焙的帧时长跟随源视频，修复 60fps 源被压帧的问题。
• 【iOS】修复选择图片/视频后上传失败：移除返回路径前的 file:// ，现在返回的绝对路径与 uni.chooseMedia 一致，plus.io.convertAbsoluteFileSystem 可以正常转换，plus.uploader 可以正常上传。

优化

• 性能优化
• 更新 README 说明。

1.1.3（2026-07-24）

修复

• 【安卓】移除不必要的 WRITE_EXTERNAL_STORAGE 权限声明：该权限此前带 maxSdkVersion="28"，manifest 合并时会覆盖宿主应用同名权限的限制，导致 uni.saveImageToPhotosAlbum / uni.saveVideoToPhotosAlbum 在 Android 10-12（API 29-32）上报"没有权限"。
• 修复了一些已知的问题

优化

• 【安卓】导出 mediaConfig：安卓端现在也导出默认配置 mediaConfig（与 iOS/鸿蒙一致），便于调用方基于默认配置展开覆盖：chooseMedia(options, { ...mediaConfig, primary: "#FF0000" })。
• 优化文档信息

1.1.2（2026-07-09）

更新文档

平台兼容性

uni-app(3.99)

uni-app x(3.99)

其他

l-media · UTS 原生媒体选择器（图片/视频/相册选择器）

一款基于 UTS 的跨平台 图片选择器 和 视频选择器（相册选择器），一套 API 覆盖 Android / iOS / 鸿蒙 三端原生相册访问。支持 图片多选（最多500张）、视频选择、图片裁剪（宽高比/圆形/指定尺寸）、HEIC→JPEG 转码、深色主题自定义、原图/压缩模式切换等完整功能。

完整 API、配置项、默认值、更新记录见 changelog.md（含完整使用文档）。

功能特性

• 图片选择器 — 支持多选（最多500张），网格视图展示相册内容
• 视频选择器 — 支持视频时长限制（maxDuration）、按媒体类型分别限制大小（maxSizeByType）
• UTS 原生实现 — 覆盖 Android / iOS / 鸿蒙，一套 API 三端统一
• 图片裁剪 — 支持宽高比裁剪、圆形裁剪、指定输出尺寸（仅 Android/iOS）
• 深色主题深度自定义 — 颜色/尺寸/圆角/动画全面可配
• 原图/压缩切换 — 支持原图转码正立（HEIC→JPEG，保留EXIF）
• 文件过滤 — 文件扩展名过滤、按媒体类型限制大小、视频时长限制
• 已选预览栏 — 支持删除与拖动重排（仅 Android/iOS）
• 隐私合规 — 鸿蒙使用系统选择器免权限；自定义权限声明

平台支持

⚠️ 三个务必注意的点

1. 返回值跨端类型不同。 Android / 鸿蒙返回 MediaFile[]；iOS 返回结果数组的 JSON 字符串（uni-app(vue) 下 UTS 对象数组无法可靠跨桥）。消费侧统一处理：

const raw = await chooseMedia({ count: 9 });
if (raw) {
  const files = typeof raw === "string" ? JSON.parse(raw as string) : raw;
  // files 即 MediaFile[]
}

2. config 覆盖会写入全局默认、并持久生效。 传入 chooseMedia(options, config) 的字段会就地覆盖内置全局默认，并在后续所有调用中持续生效（即使后续不传 config）。三端一致。因此：

• 不要依赖「不传 config 就恢复默认」——改过即被改写；
• 不同场景用不同配置，每次都显式传完整的目标 config；
• 想恢复默认需手动再传一次默认值；
• 如需在启动 / 设置页等场景主动持久化配置，推荐使用下面的 setChooseMediaConfig。

3. 可独立设置全局默认配置 setChooseMediaConfig(config)。 三端通用：在应用启动 / 设置页等任意时机调用，配置会持久合并进全局 mediaConfig，之后 chooseMedia 不传 config 也会使用该配置(ios必传，{} 或者 null)：

import { setChooseMediaConfig } from "@/uni_modules/l-media";

// 应用启动时设置一次，全局持久生效
setChooseMediaConfig({ primary: "#07C160", gridColumnCount: 3 });

它与 chooseMedia(options, config) 写的是同一个全局配置（合并语义一致），两者混用时以调用顺序为准。

最简用法

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

// Promise / async-await（取消时返回 null）
const raw = await chooseMedia({ count: 9 });

// 回调式
chooseMedia({
  count: 9,
  success: (res) => {
    /* res：iOS 为 JSON 字符串，其余为 MediaFile[] */
  },
  fail: (err) => {
    console.error(err);
  },
});

// 主动关闭（鸿蒙系统选择器不支持，会被忽略）
closeMediaChoose();

权限

• Android：Android 13 及以上需 READ_MEDIA_IMAGES、READ_MEDIA_VIDEO；Android 12L 及以下需 READ_EXTERNAL_STORAGE。插件已在清单文件中声明以上权限，但不自动申请。高版本系统要求申请时提供详细用途描述，为保证与 App 的权限描述统一，请在使用前自行调用权限申请。
• iOS：需在 manifest.json 配置「相册」用途描述（NSPhotoLibraryUsageDescription），否则申请权限时会崩溃。插件内会自动申请相册权限。
• 鸿蒙：使用系统选择器，免相册权限。

开发文档

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