Repository navigation
Releases: leavesczy/Matisse
Releases · leavesczy/Matisse
Release list
v3.0.0
相对 2.3.2 的破坏性升级。公开 API、默认行为、主题资源和图片引擎接入都有变化；升级后需要改宿主代码，不能只更新版本号。
接入方式仍是 MatisseContract / MatisseCaptureContract。详见 接入指南。
破坏性变更
Matisse
fastSelect→returnOnTap（点击缩略图立即返回；开启时maxSelectable必须为 1，选择器内拍照成功同样立即返回）singleMediaType→allowMixedMedia。旧字段为true时只能选图片或只能选视频；新字段为true时允许一次结果里同时包含图片和视频。2.3.2 默认允许同时选择；3.0.0 默认不允许，需要时必须写allowMixedMedia = truegridColumns默认由 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
- 只保留
uri、mimeType - 删除
path、name、size；需要文件路径或大小时，用uri自行查询
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
- 2.3.2 只需
GlideImageEngine：依赖改为com.github.bumptech.glide:compose（Glide 5.x）
CaptureStrategy
createImageUri→createCaptureUriloadResource→loadCapturedMediaonTakePictureCanceled→deleteCaptureUri（取消、失败、读不到结果、Uri 已创建但未交给相机时都会调用；实现须可重复执行）- 删除
getCaptureExtra()以及内置策略上的 extraBundle FileProviderCaptureStrategy不再开放继承；要换存储目录请自行实现CaptureStrategy
主题与资源
- 删除独立视频页及主题
Matisse.Theme.VideoView - color / string / bool 全部换名，默认配色已更换；默认文案为英文，中文在
values-zh - 图标改为 XML 矢量（
ic_matisse_*），覆盖同名 drawable 即可自定义
权限
- 库 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加载完成前先展示缩略图缓存；非视频大图按容器宽度等比展示并支持纵向滚动，超大图会降采样
改进
MediaStoreCaptureStrategy不再设置IS_PENDING，兼容更多系统相机写入- 相机返回后加长等待，减少文件尚未写完就当作失败的情况
- 相册加载改为页内指示，不再使用独立 Loading Dialog
- 选择器进入 / 退出不再使用自定义 Activity 转场动画
CoilImageEngine/GlideImageEngine所用依赖仍为compileOnly，由宿主按所选引擎引入
依赖
- Compose Bom：2026.04.01 → 2026.09.00
- AndroidX AppCompat：1.7.1 → 1.8.0
- AndroidX Lifecycle：2.10.0 → 2.11.0
- 新增 androidx.paging:paging-compose:3.5.1
- 移除 material-icons-extended，图标改为 XML 矢量图
- Kotlin：2.3.21 → 2.4.20
- Android Gradle Plugin：9.2.0 → 9.4.1
2.3.2
- 升级依赖库：kotlin 升级到 2.3.21、compose-bom 升级到 2026.04.01
- 优化实现逻辑
Full Changelog: 2.3.1...2.3.2
2.3.1
- 升级依赖库：compose-bom 升级到 2026.03.01、androidx-activity-compose 升级到 1.13.0
- kotlin 降级到 2.0.0，减少版本兼容性问题
Full Changelog: 2.3.0...2.3.1
2.3.0
- 升级依赖库：kotlin 升级到 2.3.0、compose-bom 升级到 2025.12.01、androidx-activity-compose 升级到 1.12.2
- 查询媒体资源时不再对文件大小进行过滤
- MediaResource 新增 size 属性值，对应查询到的文件大小
- MediaFilter 接口内部均改为 suspend 方法
Full Changelog: 2.2.3...2.3.0
2.2.3
- 升级依赖库：kotlin 升级到 2.2.21、compose-bom 升级到 2025.12.00、androidx-activity-compose 升级到 1.12.1
- minSdk 提升到 23
Full Changelog: 2.2.2...2.2.3
2.2.2
- 升级依赖库：kotlin 升级到 2.2.20、compose-bom 升级到 2025.09.00、androidx-activity-compose 升级到 1.11.0
- 适配 glide-compose 的 1.0.0-beta07 版本
- compileSdk 提升到 36
Full Changelog: 2.2.1...2.2.2
2.2.1
2.2.0
- 升级依赖库：kotlin 升级到 2.1.21、compose-bom 升级到 2025.05.00
- 允许外部继承 FileProviderCaptureStrategy，以便自定义图片存储目录
- 将 FileProviderCaptureStrategy 直接作为 SmartCaptureStrategy 的构造参数，并移除 SmartCaptureStrategy 的 extra 构造参数
- 删除 matisse_image_span_count，改为通过 gridColumns 参数来动态传值
- 删除 Coil2 版本的 CoilImageEngine，并将 Coil3 版本的 Coil3ImageEngine 重命名为 CoilImageEngine
- 为 CoilImageEngine 设置 memoryCacheKey 和 placeholderMemoryCacheKey，并为列表页的图片设置淡入淡出动效
- 细化当数量达到 maxSelectable 限制后的 Toast 提示语
- 修复当切换相册后图片列表没有滑动到顶部的问题