📝 Add OptionsFilter Documentation

Kururu-Q · Sep 13, 2017 · 5518f69 · 5518f69
1 parent 9ee31d5
commit 5518f69
Show file tree

Hide file tree

Showing 5 changed files with 70 additions and 11 deletions.
diff --git a/README.md b/README.md
@@ -149,6 +149,7 @@ sketchImageView.displayImage("http://t.cn/RShdS1f");
 
 更多：
 * [自定义 UriModel 让 Sketch 支持新的 Uri 类型][uri_model]
+* [统一修改 Options][options_filter]
 * [显示视频缩略图][display_video_thumbnail]
 * [管理多个 Options][options_manage]
 * [只加载或下载图片][load_and_download]
@@ -256,6 +257,7 @@ sketchImageView.displayImage("http://t.cn/RShdS1f");
 [initializer]: docs/wiki/initializer.md
 [proguard_config]: docs/wiki/proguard_config.md
 [other]: docs/wiki/other.md
+[options_filter]: docs/wiki/options_filter.md
 
 [koral--]: https://github.com/koral--
 [android-gif-drawable]: https://github.com/koral--/android-gif-drawable

diff --git a/README_EN.md b/README_EN.md
@@ -149,6 +149,7 @@ To further enhance the user experience:
 
 More:
 * [Customize UriModel Let Sketch support new Uri types][uri_model]
+* [Unified Change Options][options_filter]
 * [Show video thumbnails][display_video_thumbnail]
 * [Manage Multiple Options][options_manage]
 * [Only load or download images][load_and_download]
@@ -256,6 +257,7 @@ More:
 [initializer]: docs/wiki/initializer.md
 [proguard_config]: docs/wiki/proguard_config.md
 [other]: docs/wiki/other.md
+[options_filter]: docs/wiki/options_filter.md
 
 [koral--]: https://github.com/koral--
 [android-gif-drawable]: https://github.com/koral--/android-gif-drawable

diff --git a/docs/wiki/options_filter.md b/docs/wiki/options_filter.md
@@ -0,0 +1,48 @@
+# 统一修改 Options
+
+有时候我们需要对所有请求的 Options 进行检查并修改，例如列表滑动中暂停加载功能就需要检查所有的 DisplayOptions 并修改 requestLevel 属性
+
+### 使用
+
+Sketch 提供了 [OptionsFilter] 接口来实现此功能
+
+1.首先你需要实现 [OptionsFilter] 接口，定义你的过滤器，如下：
+
+```java
+public class TestOptionsFilter implements OptionsFilter {
+
+    @Override
+    public void filter(DownloadOptions options) {
+        // 在这里检查并修改 options
+    }
+}
+```
+
+2.然后通过 [OptionsFilterRegistry] 注册 TestOptionsFilter 即可，如下：
+
+```java
+OptinsFilterRegistry optinsFilterRegistry = Sketch.with(context).getConfiguration().getOptinsFilterRegistry(); 
+optinsFilterRegistry.add(new OptionsFilterRegistry());
+```
+
+### 内置的 OptionsFilter
+
+Sketch 内置了四种 [OptionsFilter]，如下：
+* [LowQualityOptionsFilter]：用来控制全局开启低质量模式
+* [InPreferQualityOverSpeedOptionsFilter]：用来控制全局开启质量优先模式
+* [PauseDownloadOptionsFilter]：用来控制暂停下载，配合 [MobileNetworkPauseDownloadController] 可实现移动网络下暂停下载，另参见 [移动网络下暂停下载图片，节省流量][pause_download] 
+* [PauseLoadOptionsFilter]：用来控制暂停加载，配合 [ScrollingPauseLoadManager] 可实现列表滑动中暂停加载，另参见 [列表滑动时暂停加载图片，提升列表滑动流畅度][pause_load]
+
+上述四个 [OptionsFilter], [Configuration] 和 [OptionsFilterRegistry] 都提供了开关控制，详情参见源码即可
+
+[OptionsFilter]: ../../sketch/src/main/java/me/xiaopan/sketch/optionsfilter/OptionsFilter.java
+[OptionsFilterRegistry]: ../../sketch/src/main/java/me/xiaopan/sketch/optionsfilter/OptionsFilterRegistry.java
+[LowQualityOptionsFilter]: ../../sketch/src/main/java/me/xiaopan/sketch/optionsfilter/LowQualityOptionsFilter.java
+[InPreferQualityOverSpeedOptionsFilter]: ../../sketch/src/main/java/me/xiaopan/sketch/optionsfilter/InPreferQualityOverSpeedOptionsFilter.java
+[PauseDownloadOptionsFilter]: ../../sketch/src/main/java/me/xiaopan/sketch/optionsfilter/PauseDownloadOptionsFilter.java
+[PauseLoadOptionsFilter]: ../../sketch/src/main/java/me/xiaopan/sketch/optionsfilter/PauseLoadOptionsFilter.java
+[MobileNetworkPauseDownloadController]: ../../sketch/src/main/java/me/xiaopan/sketch/optionsfilter/MobileNetworkPauseDownloadController.java
+[ScrollingPauseLoadManager]: ../../sample/src/main/java/me/xiaopan/sketchsample/util/ScrollingPauseLoadManager.java
+[pause_download]: pause_download.md
+[pause_load]: pause_load.md
+[Configuration]: ../../sketch/src/main/java/me/xiaopan/sketch/Configuration.java
diff --git a/docs/wiki/pause_download.md b/docs/wiki/pause_download.md
@@ -1,10 +1,11 @@
 # 移动网络下暂停下载图片，节省流量
 
-Sketch支持全局暂停下载新图片，暂停后如果磁盘中没有缓存就不下载了
+Sketch 支持全局暂停下载新图片，暂停后如果磁盘中没有缓存就不下载了
 
-``暂停下载功能只对display和load请求有效``
+``暂停下载功能只对 display 和 load 请求有效``
 
 你只需执行如下代码设置即可：
+
 ```java
 // 全局暂停下载图片
 Sketch.with(context).getConfiguration().setGlobalPauseDownload(true);
@@ -14,15 +15,17 @@ Sketch.with(context).getConfiguration().setGlobalPauseDownload(false);
 ```
 
 #### 移动网络下暂停下载
-结合此功能Sketch还提供了切换到移动网络的时候自动暂停下载图片的功能，如下：
+
+结合此功能 Sketch 还提供了切换到移动网络的时候自动暂停下载图片的功能，如下：
+
 ```java
 // 开启移动网络下自动暂停下载图片功能
-Sketch.with(getBaseContext()).getConfiguration().setMobileNetworkGlobalPauseDownload(true);
+Sketch.with(getBaseContext()).getConfiguration().setGlobalMobileNetworkPauseDownload(true);
 
 // 关闭移动网络下自动暂停下载图片功能
-Sketch.with(getBaseContext()).getConfiguration().setMobileNetworkGlobalPauseDownload(false);
+Sketch.with(getBaseContext()).getConfiguration().setGlobalMobileNetworkPauseDownload(false);
 ```
 
-Sketch还提供了pauseDownloadImage，通过DisplayOptions和DisplayHelper可以设置，当暂停下载的时候会自动显示pauseDownloadImage
+Sketch 还提供了 pauseDownloadImage，通过 DisplayOptions 和 DisplayHelper 可以设置，当暂停下载的时候会自动显示 pauseDownloadImage
 
-另外SketchImageView还提供了当暂停下载的时候点击强制下载并显示的功能，你只需调用其setClickRetryOnPauseDownloadEnabled(true)开启即可
+另外 SketchImageView 还提供了当暂停下载的时候点击强制下载并显示的功能，你只需调用其 setClickRetryOnPauseDownloadEnabled(true) 开启即可
diff --git a/docs/wiki/pause_load.md b/docs/wiki/pause_load.md
@@ -1,10 +1,11 @@
 # 列表滑动时暂停加载图片，提升列表滑动流畅度
 
-Sketch支持全局暂停从本地加载图片，暂停后Sketch将只会从内存中去找图片
+Sketch 支持全局暂停从本地加载图片，暂停后 Sketch 将只会从内存中去找图片
 
 ``暂停加载功能只对display请求有效``
 
 你只需执行如下代码设置即可：
+
 ```java
 // 全局暂停从本地加载载图片
 Sketch.with(context).getConfiguration().setGlobalPauseLoad(true);
@@ -13,10 +14,12 @@ Sketch.with(context).getConfiguration().setGlobalPauseLoad(true);
 Sketch.with(context).getConfiguration().setGlobalPauseLoad(false);
 ```
 
-#### 滑动时停止加载
+#### 列表滑动时停止加载
+
 你可以利用这个功能实现列表滑动中不加载图片，进一步提升列表的滑动流畅度
 
-首先你需要添加ScrollingPauseLoadManager.java到你的项目中，支持RecyclerView和AbsListView
+首先你需要添加 ScrollingPauseLoadManager.java 到你的项目中，支持 RecyclerView 和 AbsListView
+
 ```java
 /**
  * 滚动中暂停暂停加载新图片管理器支持RecyclerView和AbsListView
@@ -104,6 +107,7 @@ public class ScrollingPauseLoadManager extends RecyclerView.OnScrollListener imp
 ```
 
 然后应用即可
+
 ```java
 RecyclerView recyclerView = ...;
 recyclerView.setOnScrollListener(new ScrollingPauseLoadManager(context));
@@ -114,4 +118,4 @@ listView.setOnScrollListener(new ScrollingPauseLoadManager(context));
 
 注意：
 >* 在配置较高的设备上不建议使用此功能，因为实时显示图片的体验要远高于滑动时暂停加载新图片的体验。特别是在列表页点击进入一个新页面又返回的时候，由于新页面加载了新的图片把列表页中图片的缓存挤掉了，回到列表后就会刷新一下重新加载图片
->* 那么此功能我是做着玩的嘛？当然不是，在一些比较老性能很差劲的设备上，开启此功能还是很有必要的。你可以通过Android版本号进行判断并开启此功能。
+>* 那么此功能是做着玩的嘛？当然不是，在一些比较老性能很差劲的设备上，开启此功能还是很有必要的。你可以通过 Android 版本号进行判断并开启此功能。