update wiki

Kururu-Q · Jun 4, 2016 · dbb85a8 · dbb85a8
1 parent a316229
commit dbb85a8
Show file tree

Hide file tree

Showing 18 changed files with 179 additions and 213 deletions.
diff --git a/docs/wiki/disk_cache.md b/docs/wiki/disk_cache.md
@@ -1,3 +1,5 @@
+#### 简介
+
 DiskCache用来在本地磁盘上缓存图片，默认实现是LruDiskCache，其核心是DiskLruCache
 
 #### 相关方法
@@ -17,6 +19,7 @@ Configuration configuration = Sketch.with(context).getConfiguration();
 configuration.setDiskCache(new LruDiskCache(context, 1, 50 * 1024 * 1024));
 ```
 
+#### 使用缓存时加锁
 如果你要通过edit(String)方法编辑磁盘缓存，那么你需要加同步锁，如下：
 ```java
 DiskCache diskCache = Sketch.with(context).getConfiguration().getDiskCache();

diff --git a/docs/wiki/display_gif_image.md b/docs/wiki/display_gif_image.md
@@ -3,9 +3,9 @@ Sketch集成了android-gif-drawable 1.1.7支持GIF图片，使用时只需像显
 关键点：
 >* Sketch会根据mimeType判断是否是GIF图，因此不用担心识别不了伪装成jpg的GIF图
 >* Sketch提供了decodeGifImage属性来可以控制是否使用GifDrawable解码GIF图，默认false，
-如果为false的话就会使用BitmapFactory只读取第一帧，属性配置请参考[配置各种属性](options.md)
+如果为false的话就会使用BitmapFactory只读取第一帧，属性配置请参考[配置各种属性.md](options.md)
 >* GifDrawable不能使用maxSize、resize、TransitionImageDisplayer
 >* Gif图还不能使用内存缓存，因为GifDrawable需要依赖Callback才能播放，
 如果缓存的话就会出现一个GifDrawable被显示在多个ImageView上的情况，这时候就只有最后一个能正常播放
 
-SketchImageView还支持当显示的图片是GIF图时在右下角显示一个图标，告诉用户这是一张GIF图，详情请参考[SketchImageView详细使用说明](sketch_image_view.md)
+SketchImageView还支持当显示的图片是GIF图时在右下角显示一个图标，告诉用户这是一张GIF图，详情请参考[SketchImageView详细使用说明.md](sketch_image_view.md)
diff --git a/docs/wiki/displayer.md b/docs/wiki/displayer.md
@@ -1,10 +1,13 @@
+#### 简介
+
 ImageDisplayer是最后用来显示图片的，目前Sketch内置了以下五种ImageDisplayer：
 >* DefaultImageDisplayer： 默认的图片显示器，没有任何动画效果；
 >* ZoomInImageDisplayer：由小到大的显示图片，缩放比例是从0.5f到1.0f；
 >* ZoomOutImageDisplayer：由大到小的显示图片，缩放比例是从1.5f到1.0f；
 >* TransitionImageDisplayer： 过渡效果显示器，如果SketchImageView当前显示的有图片，就会用已有的图片和新的图片生成一个TransitionDrawable，以过渡渐变的方式显示。如果当前没有显示图片的话就用一张透明的ColorDrawable作为旧图片和新的图片生成一个TransitionDrawable，以过渡渐变的方式显示。
 >* ColorTransitionImageDisplayer：颜色过渡显示器，你可以指定一种颜色作为过渡效果的起始色。
 
+#### TransitionImageDisplayer
 在使用TransitionDrawable的时候，当两张图片的比例不一致，TransitionDrawable会依照尺寸比较大的图片强行将另一张图片拉伸，这样最终显示出来的效果就是变形的。
 
 为了解决这个问题，在使用TransitionImageDisplayer的时候如果Sketch检测到SketchImageView的layout_width和layout_height是写死的，

diff --git a/docs/wiki/error_callback.md b/docs/wiki/error_callback.md
@@ -0,0 +1,19 @@
+#### 简介
+
+Sketch在运行的过程中会有各种各样的异常，你可以通过ErrorCallback收到这些异常，然后将这些异常记录下来帮助解决问题
+
+### 使用
+
+ErrorCallback默认实现只是将收到的异常打印在了logcat中，而你需要继承ErrorCallback然后去记录异常
+
+ErrorCallback包含以下方法：
+>* onInstallDiskCacheFailed(Exception, File)：安装DiskLruCache失败，但Sketch还是可以正常运行的。
+    一旦失败了这个方法就会被频繁回调，这是因为每一次需要用到DiskCache的时候都会尝试恢复，再次失败就会再次回调。
+    因此你在记录日志的时候不必每次失败都记，可以每隔一个小时记一次
+>* onDecodeGifImageFailed(Throwable, LoadRequest, BitmapFactory.Options)：解码GIF图片失败。你需要过滤一下Throwable，
+    如果是UnsatisfiedLinkError或ExceptionInInitializerError就是找到libpl_droidsonroids_gif.so，
+    这个时候你就要记录一下当前设备的abi类型，Sketch中包含的libpl_droidsonroids_gif.so已经覆盖了全平台了，如果还找不到就说明有其他的问题了。
+    另外这里的Options是只含有outWidth、outHeight、outMimeType信息的
+>* onDecodeNormalImageFailed(Throwable, LoadRequest, BitmapFactory.Options)：解码普通图片失败。这里的Options是只含有outWidth、outHeight、outMimeType、inSampleSize信息的
+
+最后调用Sketch.with(context).getConfiguration().setErrorCallback(ErrorCallback)使用你的ErrorCallback
diff --git a/docs/wiki/http_stack.md b/docs/wiki/http_stack.md
@@ -1,4 +1,8 @@
-HttpStack用来发起网络请求，并且返回响应，默认的实现是HurlStack
+#### 简介
+
+HttpStack用来发起网络请求，并且返回响应
+
+默认的实现是API9及以上使用HurlStack以下使用HttpClientStack
 
 #### 相关配置：
 >* setMaxRetryCount(int maxRetryCount)：设置连接超时后重试次数，默认1

diff --git a/docs/wiki/in_sample_size.md b/docs/wiki/in_sample_size.md
@@ -0,0 +1,46 @@
+#### 简介
+
+inSampleSize是用来减小读到内存中的图片的尺寸，非常重要，默认的实现是ImageSizeCalculator.calculateInSampleSize(int, int, int, int)方法
+```java
+@Override
+public int calculateInSampleSize(int outWidth, int outHeight, int targetWidth, int targetHeight) {
+    // 如果目标尺寸都小于等于0，那就别计算了没意义
+    if(targetWidth <= 0 && targetHeight <= 0){
+        return 1;
+    }
+
+    // 如果目标尺寸都大于等于原始尺寸，也别计算了没意义
+    if(targetWidth >= outWidth && targetHeight >= outHeight){
+        return 1;
+    }
+
+    // 首先根据缩放后只要有任何一边小于等于目标即可的规则计算一遍inSampleSize
+    int inSampleSize = 1;
+    do{
+        inSampleSize *= 2;
+    }while ((outWidth/inSampleSize) > targetWidth && (outHeight/inSampleSize) > targetHeight);
+
+    // 然后根据比较像素总数的原则过滤掉那些比较极端的一边特别小，一边特别大的图片
+    // 比如目标尺寸是400x400，图片的尺寸是6000*600，缩放后是3000*300
+    // 这样看来的确是满足了第一个条件了，但是图片的尺寸依然很大
+    // 因此这一步我们根据像素总数来过滤，规则是总像素数不得大于目标尺寸像素数的两倍
+    long totalPixels = (outWidth/inSampleSize) * (outHeight/inSampleSize);
+    final long totalReqPixelsCap = targetWidth * targetHeight * 2;
+    while (totalPixels > totalReqPixelsCap) {
+        inSampleSize *= 2;
+        totalPixels /= 2;
+    }
+
+    return inSampleSize;
+}
+```
+
+其实现规则是：
+>* 如果目标尺寸的宽高都小于0，就不计算了直接返回1
+>* 如果目标尺寸的宽高都大于原图的宽高，就不计算了直接返回1
+>* 然后开始每次乘以2计算inSampleSize，直到应用inSampleSize后原图的宽或高小于目标尺寸的宽或高即可
+>* 接下来开始按照总像素数进行就算inSampleSize，直到应用inSampleSize后原图的总像素数小于目标尺寸总像素数的2倍即可
+
+#### 自定义inSampleSize计算规则
+如果你想自定义inSampleSize的话，你只需继承ImageSizeCalculator，并重写calculateInSampleSize(int, int, int, int)方法，
+然后调用Sketch.with(context).getConfiguration().setImageSizeCalculator(ImageSizeCalculator)方法应用即可
diff --git a/docs/wiki/load_download.md b/docs/wiki/load_download.md
diff --git a/docs/wiki/max_size.md b/docs/wiki/max_size.md
@@ -0,0 +1,28 @@
+#### 简介
+maxSize用来防止加载过大的图片到内存中，已达到节省内存的目的
+
+#### 背景
+我们在移动端显示图片的时候都需要面对加载大尺寸图片的问题
+目前主流的Android旗舰机内存一般在2G左右，而APP最多可用内存为200M左右
+现在手机都是800万像素的，随便拍一张照片都是3264x1840的，那么加载到内存中就需要3264x1840x4/1024/1024=22M，照这么看加载9张3264x1840的图片内存就耗完了，显然我们不能这样搞
+
+#### 何时使用
+ImageDecoder会在读取图片的时候根据maxSize计算出合适的inSampleSize，然后再读取图片
+
+#### 关于inSampleSize
+BitmapFactory提供了一个Options来配置读取图片的相关选项，其中一个参数就是inSampleSize，其作用是设置缩放倍数。
+
+例如：
+    原图尺寸3264x1840
+    inSampleSize=2
+那么最终读到内存的图片的尺寸就是1632x920，宽高都缩小了2倍，其所占内存从23M缩小到1632x920x4/1024/1024=5.7M，缩小了4倍。
+
+#### 缺省值
+>* 在使用load()方法加载图片的时候maxSize的缺省值是当前设备屏幕的0.75倍
+>* 在使用SketchImageView的时候如果layout_width和layout_height是固定的那么就会用layout_width和layout_height来作为maxSize，否则就使用当前屏幕宽高的0.75倍来作为maxSize
+
+因此在大多数情况下你不需要主动设置maxSize，Sketch会自动帮你搞定
+
+#### 自定义maxSize计算规则
+如果你对现有的maxSize计算规则不满意，那么你可以继承ImageSizeCalculator类重写calculateImageMaxSize()方法实现你自己的计算规则
+然后调用Sketch.with(context).getConfiguration().setImageSizeCalculator(ImageSizeCalculator)方法来使用你自定义的ImageSizeCalculator
diff --git a/docs/wiki/maxsize_resize_in_sample_size.md b/docs/wiki/maxsize_resize_in_sample_size.md
diff --git a/docs/wiki/memory_cache.md b/docs/wiki/memory_cache.md
@@ -1,3 +1,5 @@
+#### 简介
+
 MemoryCache用来在内存中缓存图片，默认的实现是LruMemoryCache，自动根据最少使用原则释放旧的图片
 
 #### 相关方法：
@@ -8,7 +10,7 @@ MemoryCache用来在内存中缓存图片，默认的实现是LruMemoryCache，
 >* get(String)：获取缓存中指定的keu的图片
 >* put(String, Drawable)：将图片放到缓存中，注意Drawable必须实现RecycleDrawableInterface接口
 
-自定义内存缓存最大容量
+#### 自定义内存缓存最大容量
 ```java
 // 最大容量为APP最大可用内存的十分之一
 int newMemoryCacheMaxSize = (int) (Runtime.getRuntime().maxMemory() / 10);

diff --git a/docs/wiki/options.md b/docs/wiki/options.md
@@ -1,4 +1,6 @@
-Sketch有display()、load()、download()三大方法，我们可以通过其专属的Options或Helper（[显示（display()）、加载（load()）和下载（download()））](load_download.md)）来配置各种属性
+#### 简介
+
+Sketch有display()、load()、download()三大方法，我们可以通过其专属的Options或Helper来配置各种属性
 
 三大方法支持属性如下（'-'代表不支持，非'-'代表支持并且默认值是什么）：
 

diff --git a/docs/wiki/pause_download.md b/docs/wiki/pause_download.md
@@ -11,6 +11,7 @@ Sketch.with(context).getConfiguration().setGlobalPauseDownload(true);
 Sketch.with(context).getConfiguration().setGlobalPauseDownload(false);
 ```
 
+#### 移动网络下暂停下载
 结合此功能Sketch还提供了切换到移动网络的时候自动暂停下载图片的功能，如下：
 ```java
 // 开启移动网络下自动暂停下载图片功能