Matisse 图片选择器完整集成指南从依赖配置到主题定制的实操清单【免费下载链接】Matisse:fireworks: A well-designed local image and video selector for Android项目地址: https://gitcode.com/gh_mirrors/mati/MatisseMatisse 是知乎开源的 Android 本地图片与视频选择库把「从相册选图」从自己写界面变成一段建造者调用。本文按 Matisse 图片选择器集成的实操流程组织依赖与权限配置、三步跑通、配置速查表、场景化进阶与常见坑每一步都可以直接对照执行。一句话定位Matisse 图片选择解决什么问题Matisse 是一个开箱即用的媒体选择器你传入媒体类型和数量上限它提供带相册分组、多选、放大预览、拍照入口的完整选择页结果通过onActivityResult回传无需自绘任何列表与勾选 UI。适用场景什么时候选 Matisse 而不是系统选择器需要让用户从本地相册挑选 1~9 张图片或短视频头像、发布页、群聊发图时优先用 Matisse 这类专用选择器它内置分组、主题、过滤规则体验对齐主流 App它不做跨应用媒体共享也不替你处理 Android 13 的READ_MEDIA_IMAGES新权限这部分需按目标 SDK 自行适配。快速上手四步跑通 Matisse 媒体选择器第 1 步添加 Gradle 依赖应用模块build.gradlerepositories { jcenter() } dependencies { implementation com.zhihu.android:matisse:$latest_version }第 2 步声明存储权限AndroidManifest.xml库自身清单已声明应用侧同样需要uses-permission android:nameandroid.permission.READ_EXTERNAL_STORAGE/ uses-permission android:nameandroid.permission.WRITE_EXTERNAL_STORAGE/Android 6.0 还需在启动前做运行时授权示例工程用 RxPermissions 处理见 SampleActivity.java。第 3 步启动选择页Matisse.from()同时支持 Activity 与 FragmentMatisse.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) { ListUri uris Matisse.obtainResult(data); ListString 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_DraculagridExpectedSize()/spanCount()网格期望边长px/ 固定列数二者互斥设了gridExpectedSize时spanCount被忽略thumbnailScale()缩略图相对格子的大小取值 (0, 1]默认 0.5imageEngine()图片加载引擎GlideEngine/PicassoEngine/ 自定义ImageEngine实现addFilter()附加过滤规则Filter子类见下文「过滤规则」originalEnable()maxOriginalSize()原图开关及上限MB默认关闭、不限制大小showSingleMediaType()只显示单一媒体类型时隐藏切换只选图片或只选视频时常用truesetOnSelectedListener()选中状态实时回调需要即时响应如刷新底部栏时使用场景化进阶Matisse 主题定制、过滤规则与拍照集成需求把 Matisse 换成品牌色做法两个内置主题定义在 styles.xml可覆写的属性名如bottomToolbar.bg、item.checkCircle.backgroundColor都在 attrs.xml 中声明。继承Matisse.Zhihu只重写想改的项style nameMatisse.Brand parentMatisse.Zhihu item namebottomToolbar.bgcolor/brand_toolbar_bg/item item nameitem.checkCircle.backgroundColorcolor/brand_check_bg/item /style启动时传入.theme(R.style.Matisse_Brand)即生效。需求限制 GIF 尺寸或体积做法实现Filter子类覆写两个方法——constraintTypes()声明该规则作用于哪些MimeTypefilter()对每一项判断可选返回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_publicMatisse.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示例用 RxPermissionsonActivityResult收不到结果requestCode 不一致或从 Fragment 启动却在 Activity 里覆写回调保持一致的 requestCodeFragment 中用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 部分延伸阅读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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/11/3 10:19:24 · 阅读 1.2k Matisse 图片选择器完整集成指南：从依赖配置到主题定制的实操清单
Matisse 图片选择器完整集成指南从依赖配置到主题定制的实操清单【免费下载链接】Matisse:fireworks: A well-designed local image and video selector for Android项目地址: https://gitcode.com/gh_mirrors/mati/MatisseMatisse 是知乎开源的 Android 本地图片与视频选择库把「从相册选图」从自己写界面变成一段建造者调用。本文按 Matisse 图片选择器集成的实操流程组织依赖与权限配置、三步跑通、配置速查表、场景化进阶与常见坑每一步都可以直接对照执行。一句话定位Matisse 图片选择解决什么问题Matisse 是一个开箱即用的媒体选择器你传入媒体类型和数量上限它提供带相册分组、多选、放大预览、拍照入口的完整选择页结果通过onActivityResult回传无需自绘任何列表与勾选 UI。适用场景什么时候选 Matisse 而不是系统选择器需要让用户从本地相册挑选 1~9 张图片或短视频头像、发布页、群聊发图时优先用 Matisse 这类专用选择器它内置分组、主题、过滤规则体验对齐主流 App它不做跨应用媒体共享也不替你处理 Android 13 的READ_MEDIA_IMAGES新权限这部分需按目标 SDK 自行适配。快速上手四步跑通 Matisse 媒体选择器第 1 步添加 Gradle 依赖应用模块build.gradlerepositories { jcenter() } dependencies { implementation com.zhihu.android:matisse:$latest_version }第 2 步声明存储权限AndroidManifest.xml库自身清单已声明应用侧同样需要uses-permission android:nameandroid.permission.READ_EXTERNAL_STORAGE/ uses-permission android:nameandroid.permission.WRITE_EXTERNAL_STORAGE/Android 6.0 还需在启动前做运行时授权示例工程用 RxPermissions 处理见 SampleActivity.java。第 3 步启动选择页Matisse.from()同时支持 Activity 与 FragmentMatisse.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) { ListUri uris Matisse.obtainResult(data); ListString 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_DraculagridExpectedSize()/spanCount()网格期望边长px/ 固定列数二者互斥设了gridExpectedSize时spanCount被忽略thumbnailScale()缩略图相对格子的大小取值 (0, 1]默认 0.5imageEngine()图片加载引擎GlideEngine/PicassoEngine/ 自定义ImageEngine实现addFilter()附加过滤规则Filter子类见下文「过滤规则」originalEnable()maxOriginalSize()原图开关及上限MB默认关闭、不限制大小showSingleMediaType()只显示单一媒体类型时隐藏切换只选图片或只选视频时常用truesetOnSelectedListener()选中状态实时回调需要即时响应如刷新底部栏时使用场景化进阶Matisse 主题定制、过滤规则与拍照集成需求把 Matisse 换成品牌色做法两个内置主题定义在 styles.xml可覆写的属性名如bottomToolbar.bg、item.checkCircle.backgroundColor都在 attrs.xml 中声明。继承Matisse.Zhihu只重写想改的项style nameMatisse.Brand parentMatisse.Zhihu item namebottomToolbar.bgcolor/brand_toolbar_bg/item item nameitem.checkCircle.backgroundColorcolor/brand_check_bg/item /style启动时传入.theme(R.style.Matisse_Brand)即生效。需求限制 GIF 尺寸或体积做法实现Filter子类覆写两个方法——constraintTypes()声明该规则作用于哪些MimeTypefilter()对每一项判断可选返回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_publicMatisse.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示例用 RxPermissionsonActivityResult收不到结果requestCode 不一致或从 Fragment 启动却在 Activity 里覆写回调保持一致的 requestCodeFragment 中用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 部分延伸阅读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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考