Matisse 图片选择器完整集成指南：从依赖配置到主题定制的实操清单

【免费下载链接】Matisse:fireworks: A well-designed local image and video selector for Android项目地址: https://gitcode.com/gh_mirrors/mati/Matisse

Matisse 是知乎开源的 Android 本地图片与视频选择库，把「从相册选图」从自己写界面变成一段建造者调用。本文按 Matisse 图片选择器集成的实操流程组织：依赖与权限配置、三步跑通、配置速查表、场景化进阶与常见坑，每一步都可以直接对照执行。

一句话定位：Matisse 图片选择解决什么问题

Matisse 是一个开箱即用的媒体选择器：你传入媒体类型和数量上限，它提供带相册分组、多选、放大预览、拍照入口的完整选择页，结果通过onActivityResult回传，无需自绘任何列表与勾选 UI。

适用场景：什么时候选 Matisse 而不是系统选择器

需要让用户从本地相册挑选 1~9 张图片或短视频（头像、发布页、群聊发图）时，优先用 Matisse 这类专用选择器：它内置分组、主题、过滤规则，体验对齐主流 App；它不做跨应用媒体共享，也不替你处理 Android 13 的READ_MEDIA_IMAGES新权限，这部分需按目标 SDK 自行适配。

快速上手：四步跑通 Matisse 媒体选择器

第 1 步：添加 Gradle 依赖（应用模块build.gradle）

repositories { jcenter() } dependencies { implementation 'com.zhihu.android:matisse:$latest_version' }

第 2 步：声明存储权限（AndroidManifest.xml，库自身清单已声明，应用侧同样需要）

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

Android 6.0+ 还需在启动前做运行时授权，示例工程用 RxPermissions 处理，见 SampleActivity.java。

第 3 步：启动选择页（Matisse.from()同时支持 Activity 与 Fragment）

Matisse.from(this) .choose(MimeType.ofImage()) .countable(true) .maxSelectable(9) .gridExpectedSize(getResources().getDimensionPixelSize(R.dimen.grid_expected_size)) .thumbnailScale(0.85f) .imageEngine(new GlideEngine()) .forResult(REQUEST_CODE_CHOOSE);

第 4 步：取回选择结果

@Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { super.onActivityResult(requestCode, resultCode, data); if (requestCode == REQUEST_CODE_CHOOSE && resultCode == RESULT_OK) { List<Uri> uris = Matisse.obtainResult(data); List<String> paths = Matisse.obtainPathResult(data); } }

✅ 需要「原图」勾选状态时，额外调用Matisse.obtainOriginalState(data)。

核心配置速查表：Matisse 常用参数一览

以下均为choose()返回的SelectionCreator链式方法，按需拼装即可：

场景化进阶：Matisse 主题定制、过滤规则与拍照集成

需求：把 Matisse 换成品牌色

做法：两个内置主题定义在 styles.xml，可覆写的属性名（如bottomToolbar.bg、item.checkCircle.backgroundColor）都在 attrs.xml 中声明。继承Matisse.Zhihu，只重写想改的项：

<style name="Matisse.Brand" parent="Matisse.Zhihu"> <item name="bottomToolbar.bg">@color/brand_toolbar_bg</item> <item name="item.checkCircle.backgroundColor">@color/brand_check_bg</item> </style>

启动时传入.theme(R.style.Matisse_Brand)即生效。

需求：限制 GIF 尺寸或体积

做法：实现Filter子类，覆写两个方法——constraintTypes()声明该规则作用于哪些MimeType，filter()对每一项判断，可选返回null，不可选返回IncapableCause（可带弹窗提示文案）。示例工程已给出完整的 GifSizeFilter.java，接入时只需.addFilter(new GifSizeFilter(320, 320, 5 * Filter.K * Filter.K))，即可拦截 320x320 以下或 5MB 以上的 GIF。

需求：在网格里加一个拍照入口

做法：capture(true)开启后，还必须提供CaptureStrategy（是否存公共目录、FileProvider 的 authority、子目录），并在清单中声明与之匹配的FileProvider（示例中指向@xml/file_paths_public）：

Matisse.from(this) .choose(MimeType.ofImage()) .capture(true) .captureStrategy(new CaptureStrategy(true, "com.yourapp.fileprovider", "test")) .imageEngine(new GlideEngine()) .forResult(REQUEST_CODE_CHOOSE);

常见坑与排查：Matisse 集成五个高频问题

⚠️ 排查时先看 logcat 里的权限报错，再核对 requestCode 的实际回传值：

延伸阅读

Matisse 的价值在于把选择器的复杂状态（多选、预览、分组、过滤）收敛进一个建造者配置，业务侧只关心取回 Uri 与路径。深入细节可看这三处源码：

• 核心入口类 Matisse.java
• 主题定义文件 styles.xml
• 完整示例 SampleActivity.java

【免费下载链接】Matisse:fireworks: A well-designed local image and video selector for Android项目地址: https://gitcode.com/gh_mirrors/mati/Matisse