Release v3.0.0 · leavesczy/Matisse

相对 2.3.2 的破坏性升级。公开 API、默认行为、主题资源和图片引擎接入都有变化；升级后需要改宿主代码，不能只更新版本号。

接入方式仍是 MatisseContract / MatisseCaptureContract。详见接入指南。

破坏性变更

Matisse

fastSelect → returnOnTap（点击缩略图立即返回；开启时 maxSelectable 必须为 1，选择器内拍照成功同样立即返回）
singleMediaType → allowMixedMedia。旧字段为 true 时只能选图片或只能选视频；新字段为 true 时允许一次结果里同时包含图片和视频。2.3.2 默认允许同时选择；3.0.0 默认不允许，需要时必须写 allowMixedMedia = true
gridColumns 默认由 4 改为 3。仍要 4 列需显式传入
MediaType.MultipleMimeType → MediaType.MimeTypes，且每项必须以 image/ 或 video/ 开头
includeImage / includeVideo → includesImage / includesVideo
删除 mediaFilter / MediaFilter / DefaultMediaFilter
mediaType 不含图片时，captureStrategy 必须为 null；MediaType.MimeTypes 启用拍照时必须包含 image/jpeg。不满足约束会在构造时抛出 IllegalArgumentException

MediaResource

ImageEngine

接口方法 Image() 更名为 Preview()。自定义引擎必须改方法名，并按新约定实现：
- Thumbnail：网格和相册列表。外层已是有界格子，应填满容器，允许裁切
- Preview：预览页。图片保持宽高比、不裁切，超出区域时自行提供查看完整内容的方式（例如纵向滚动）；视频只展示静态封面，播放由 Matisse 负责
CoilImageEngine：
- 2.3.2 只需 coil-compose，coil-video / coil-gif 按需添加
- 3.0.0 必须同时添加 coil-compose 和 coil-video
- 要在预览页播放 GIF 等动图，还需 coil-gif，并在 Application 中通过 SingletonImageLoader.setSafe 向宿主 ImageLoader 注册 Decoder
GlideImageEngine：依赖改为 com.github.bumptech.glide:compose（Glide 5.x）

CaptureStrategy

createImageUri → createCaptureUri
loadResource → loadCapturedMedia
onTakePictureCanceled → deleteCaptureUri（取消、失败、读不到结果、Uri 已创建但未交给相机时都会调用；实现须可重复执行）
删除 getCaptureExtra() 以及内置策略上的 extra Bundle
FileProviderCaptureStrategy 不再开放继承；要换存储目录请自行实现 CaptureStrategy

主题与资源

权限

库 Manifest 仍不声明媒体读取权限；宿主必须按 mediaType 自行声明 READ_MEDIA_IMAGES / READ_MEDIA_VIDEO 或 READ_EXTERNAL_STORAGE
CAMERA 仍为可选：宿主声明后 Matisse 会在需要时申请，未声明则直接启动系统相机

通过 Paging3 分页加载相册
Android 14 部分媒体访问：宿主声明 READ_MEDIA_VISUAL_USER_SELECTED 后，可接受部分授权；非完整访问时再次进入会重新打开系统授权页
视频在预览页内联播放，不再跳转独立页面
选择器内拍照成功后插入列表首位并继续选择；returnOnTap 开启时拍照成功立即返回
单选预览页可直接确认
无权限、无内容、加载失败的空状态
CoilImageEngine / GlideImageEngine：
- Android 10+ 的 MediaStore 媒体优先读取系统缩略图，失败或非 MediaStore Uri 时再回退为原图解码 / 视频抽帧
- 网格、相册封面与预览占位共用同一份缩略图内存缓存
- Preview 加载完成前先展示缩略图缓存；非视频大图按容器宽度等比展示并支持纵向滚动，超大图会降采样