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

发布时间：2026/11/3 10:18:58

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链式方法，按需拼装即可：

配置项	作用	常用值/说明
`choose()`	限定可选媒体类型	`MimeType.ofImage()`/`ofVideo()`/`ofAll()`/`of(MimeType.GIF)`
`maxSelectable()`	最大可选数量	默认 1，常用 9；传小于 1 会抛异常
`countable()`	选中时显示序号	`true`序号、`false`对勾（默认）
`theme()`	页面主题	默认`Matisse_Zhihu`，另一内置为`Matisse_Dracula`
`gridExpectedSize()`/`spanCount()`	网格期望边长（px）/ 固定列数	二者互斥：设了`gridExpectedSize`时`spanCount`被忽略
`thumbnailScale()`	缩略图相对格子的大小	取值 (0, 1]，默认 0.5
`imageEngine()`	图片加载引擎	`GlideEngine`/`PicassoEngine`/ 自定义`ImageEngine`实现
`addFilter()`	附加过滤规则	`Filter`子类，见下文「过滤规则」
`originalEnable()`+`maxOriginalSize()`	原图开关及上限（MB）	默认关闭、不限制大小
`showSingleMediaType()`	只显示单一媒体类型时隐藏切换	只选图片或只选视频时常用`true`
`setOnSelectedListener()`	选中状态实时回调	需要即时响应（如刷新底部栏）时使用

场景化进阶：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 的实际回传值：

现象	原因	解法
Android 6.0+ 相册页空白或闪退	未做运行时存储权限请求	`forResult()`前先`requestPermissions`（示例用 RxPermissions）
`onActivityResult`收不到结果	requestCode 不一致，或从 Fragment 启动却在 Activity 里覆写回调	保持一致的 requestCode；Fragment 中用`Matisse.from(fragment)`
缩略图不显示	未设置`imageEngine`	传入`new GlideEngine()`，或自行实现`ImageEngine`接口
开启拍照后崩溃	清单缺`FileProvider`，或 authority 与`CaptureStrategy`不一致	按示例清单声明`FileProvider`并配套 file_paths 资源
R8 报 Missing class	库内同时引用 Glide 与 Picasso，而你只依赖其一	用 Glide 时补`-dontwarn com.squareup.picasso.**`（README ProGuard 部分）