更新记录

1.1.9（2026-10-28）

新增

• 【iOS / 安卓】图片预览「编辑」：在预览页底部左侧新增「编辑」，仅图片显示；视频/鸿蒙系统选择器不参与。
  • 工具：画笔、马赛克、文字、箭头、旋转/裁剪，支持撤销/重做。
  • 编辑结果替换当前选中项；未选中的图片编辑保存后自动选中（受 count 上限限制）。
  • 交互使用工作图，保存时按原图分辨率重新渲染；超大图自动降级到 4096 长边并提示。
  • GIF / 动态 WebP / Live Photo 允许编辑，但是会丢失动画，仅输出首帧静态图。
• 【三端】明水印 ChooseMediaOptions.watermark：
  • 仅图片，在「发送 / 确认」导出结果时合成；网格、预览、编辑画布不显示。
  • text: string[]（每项一行，项内 \n 也会拆行）；position 支持 topLeft / topRight / bottomLeft / bottomRight / center / tile（满屏平铺）；rotate 为顺时针角度。
  • 样式（字号 / 颜色 / 描边 / 边距 / 行高 / 最大宽度 / 平铺间距）见 MediaConfig.watermark*，按图片短边比例计算，不同分辨率视觉一致。
  • 开启水印后图片强制重编码：keepOriginalFormat 对图片失效、EXIF 丢失，HEIC / WebP → JPEG（PNG 源保留 PNG），返回 orientation=0。
  • 单行文字超出 watermarkMaxWidth 时按字符自动换行；平铺实例上限 1000，避免极端参数卡死。
  • 圆形裁剪（Android / iOS）：position 为四角时自动改为居中，避免水印落在圆形外的透明区域。
  • 平台：Android / iOS / 鸿蒙均已支持图片水印；鸿蒙走系统选择器，导出时重编码叠加水印（裁剪、主题等系统界面能力仍不支持）。视频不支持水印；设置 watermark 时视频视为失败项。

优化

• 【三端】优化：优化了三端的性能和内存问题，将耗时任务放在后台，避免主线程卡顿；优化了三端的稳定性；优化了三端的高、低版本的兼容性。
• 【鸿蒙】crop 语义：crop 在鸿蒙不再静默忽略，直接通过 fail(9010002) 明确告知不支持，避免返回未裁剪/视频结果。

修复

• 【iOS / 安卓】优化「裁剪」：修复裁剪模式重复打开问题。
• 【安卓】权限兜底：Android 13 及以下权限被拒时也会显示「当前照片访问受限」提示与授权入口，权限申请按系统版本自动选择。
• 【安卓】展示：视频时长角标支持小时（h:mm:ss）。
• 【三端】options 复用：complete 结束时恢复用户原始回调，避免复用同一个 options 对象导致下一次回调失效。
• 【安卓】首屏与系统栏：首屏不足一屏时自动继续加载；选择器/预览/裁剪统一处理底部 WindowInsets。
• 【安卓】视频缩略图方向：按 METADATA_KEY_VIDEO_ROTATION 旋转发送缩略图与网格缩略图；鸿蒙视频缩略图请求 600x600 目标尺寸。
• 【安卓 / iOS】裁剪参数：输出宽高限制为有限数、最大 8192；quality 钳制到 0-100。
• 【安卓】水印 emoji 断行：代理对检测改为只检查最后一个 UTF-16 code unit；鸿蒙同步修正。
• 【文档】：修正 readme 的 EXIF 描述、鸿蒙 close/crop 语义、demo 的 iOS config 旧提示、changelog 的 tile 与 iOS lineHeight 说明。
• 【三端】：修复了一些其他问题。

1.1.8（2026-10-19）

优化

• 【安卓】：优化缓存清理和高版本安卓（android 16）的兼容性
• 【HBuilderX 最低支持版本】：提高最低版本至4.11+

1.1.7（2026-10-07）

文档优化

平台兼容性

uni-app(4.11)

uni-app x(4.11)

其他

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

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

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

功能特性

• 图片选择器 — 支持多选（最多500张），网格视图展示相册内容
• 视频选择器 — 支持视频时长限制（maxDuration）、按媒体类型分别限制大小（maxSizeByType）
• UTS 原生实现 — 覆盖 Android / iOS / 鸿蒙，一套 API 三端统一
• 图片裁剪 — 支持宽高比裁剪、圆形裁剪、指定输出尺寸（仅 Android/iOS）
• 明水印（三端） — 四角 / 居中 / 满屏平铺，支持旋转角度与字号、颜色、描边、边距自定义（仅图片）
• 图片编辑 — 预览页底部「编辑」：画笔、马赛克、文字、箭头、旋转/裁剪、撤销/重做（仅 Android/iOS）
• 深色主题深度自定义 — 颜色/尺寸/圆角/动画全面可配
• 原图/压缩切换 — 支持原图转码正立（HEIC→JPEG；默认重编码不保留 EXIF，keepOriginalFormat=true 输出真原始文件才保留原 EXIF）
• 文件过滤 — 文件扩展名过滤、按媒体类型限制大小、视频时长限制
• 已选预览栏 — 支持删除与拖动重排（仅 Android/iOS）
• 隐私合规 — 鸿蒙使用系统选择器免权限；自定义权限声明

平台支持

图片编辑（仅 Android / iOS）

在图片预览页底部左侧点「编辑」即可进入：

• 工具：画笔 / 马赛克 / 文字 / 箭头 / 旋转裁剪；撤销 / 重做包含旋转与裁剪（Android / iOS 裁剪模式内确认后整段可撤销）。
• 结果：替换当前选中项；未选中的图片保存后会自动选中（受 count 限制）。
• 质量：交互使用工作图，保存时按原分辨率渲染；超大图会降级到 4096 长边并提示。原图模式不二次压缩，压缩模式沿用既有压缩策略。
• 注意：GIF / 动态 WebP / Live Photo 允许编辑，但是会丢失动画，仅输出首帧静态图。

明水印（仅图片，三端支持）

chooseMedia 的 options.watermark 支持在导出结果时叠加文字水印（Android / iOS / 鸿蒙）：

const res = await chooseMedia(
  {
    count: 9,
    mediaType: ["image"],
    watermark: {
      text: ["内部资料", "2026-10-27"], // 每项一行
      position: "tile", // 四角 / center / tile 满屏
      rotate: -30, // 顺时针角度
    },
  },
  {
    watermarkTextSize: 0.04, // 相对短边比例
    watermarkTextColor: "#59FFFFFF", // #AARRGGBB，alpha 控制透明度
    watermarkTextStrokeColor: "#40000000", // 默认描边，浅色背景也能看清
    watermarkTextStrokeWidth: 0.06, // 描边宽度（相对字号）；0 = 关闭
    watermarkPadding: 0.04,
    watermarkLineHeight: 1.2,
    watermarkMaxWidth: 0.9,
    watermarkTileSpacing: 5,
  },
);

注意：

• 水印只在「发送 / 确认」导出结果时合成，网格、预览、编辑画布不显示；
• 开启水印后图片会强制重编码：keepOriginalFormat 对图片失效、EXIF 丢失，HEIC / WebP → JPEG（PNG 源保留 PNG），返回 orientation=0；
• 字号 / 边距按图片短边比例计算，不同分辨率视觉一致；单行超出 watermarkMaxWidth 时自动换行；默认带描边，浅色背景也能看清（watermarkTextStrokeWidth: 0 可关闭）；
• 圆形裁剪（Android / iOS）：position 为四角时会自动改为居中，避免水印落在圆形外的透明区域；

chooseMedia({
  watermark: { text: ["内部资料"], position: "tile" },
  success: (res) => {
    // res 只包含成功加水印的文件
  },
  fail: (err) => {
    // err.errCode === 9010005 时，err.errMsg 包含失败文件名
  },
  complete: (res) => {
    // 本次选择结束；部分成功时 res 为成功项
  },
});

• 视频不支持水印；设置 watermark 时视频会作为失败项处理（不会出现在 success 中）。鸿蒙使用系统选择器，导出的图片会在复制进沙箱后重编码叠加水印（裁剪、主题等系统界面能力仍不支持）。

⚠️ 五个务必注意的点

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) 写的是同一个全局配置（合并语义一致），两者混用时以调用顺序为准。

4. path / thumbTempFilePath 三端统一为 file:// 开头的路径。

• 三端 path 均可直接传给 plus.io / uni.previewImage / <image> / <video>，无需再调用 plus.io.convertAbsoluteFileSystem。

5. Android 14+的相册权限行为

• 为了兼容Android 14+的相册权限行为，需要在manifest.json -> app-plus -> distribute -> android 中添加 "targetSdkVersion" : 35

最简用法

import { chooseMedia, closeMediaChoose, clearMediaCache } 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);
  },
  complete: (res) => {
    // 成功 / 失败 / 取消都会触发
  },
});

// 主动关闭：鸿蒙系统选择器界面无法被程序关闭，但会立即结束 Promise（resolve(null)）；
// 之后用户对系统界面的操作不会再触发 success / fail
closeMediaChoose();

// 确认返回的 path 不再使用后，手动清空插件产生的媒体缓存
clearMediaCache();

权限

• 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