第 2 章 DRAWEE 指南 · Fresco 中文版

[TOC] ### 在XML中使用Drawees Drawees 具有极大的可定制性。下面的例子给出了可以配置的各种选项： ~~~xml <com.facebook.drawee.view.SimpleDraweeView android:id="@+id/my_image_view" android:layout_width="20dp" android:layout_height="20dp" fresco:fadeDuration="300" fresco:actualImageScaleType="focusCrop" fresco:placeholderImage="@color/wait_color" fresco:placeholderImageScaleType="fitCenter" fresco:failureImage="@drawable/error" fresco:failureImageScaleType="centerInside" fresco:retryImage="@drawable/retrying" fresco:retryImageScaleType="centerCrop" fresco:progressBarImage="@drawable/progress_bar" fresco:progressBarImageScaleType="centerInside" fresco:progressBarAutoRotateInterval="1000" fresco:backgroundImage="@color/blue" fresco:overlayImage="@drawable/watermark" fresco:pressedStateOverlayImage="@color/red" fresco:roundAsCircle="false" fresco:roundedCornerRadius="1dp" fresco:roundTopLeft="true" fresco:roundTopRight="false" fresco:roundBottomLeft="false" fresco:roundBottomRight="true" fresco:roundWithOverlayColor="@color/corner_color" fresco:roundingBorderWidth="2dp" fresco:roundingBorderColor="@color/border_color" /> ~~~ ##### 必须设置layout_width和layout_height 如果没有在XML中声明这两个属性，将无法正确加载图像。 ##### wrap_content *Drawees 不支持 `wrap_content` 属性。* 所下载的图像可能和占位图尺寸不一致，如果设置出错图或者重试图的话，这些图的尺寸也可能和所下载的图尺寸不一致。如果大小不一致，图像下载完之后，假设如果是`wrap_content`，View将会重新layout，改变大小和位置。这将会导致界面跳跃。 ##### 固定宽高比只有希望显示的固定宽高比时，可以使用`wrap_content`。如果希望显示的图片保持一定宽高比例，如果 4:3，则在XML中: ~~~xml <com.facebook.drawee.view.SimpleDraweeView android:id="@+id/my_image_view" android:layout_width="20dp" android:layout_height="wrap_content"  ~~~ 然后在代码中指定显示比例： ~~~java mSimpleDraweeView.setAspectRatio(1.33f); ~~~ ### 在JAVA代码中使用Drawees #### 设置或更改要显示的图片 ~~~ mSimpleDraweeView.setImageURI(uri); ~~~ 如果要更加复杂的配置，可使用[ControllerBuilder](#); #### 自定义显示图一般情况下，在[XML设置显示效果即可](#), 如果想更多定制化，可以这样: 创建一个 builder 然后设置给 DraweeView: ~~~java List<Drawable> backgroundsList; List<Drawable> overlaysList; GenericDraweeHierarchyBuilder builder = new GenericDraweeHierarchyBuilder(getResources()); GenericDraweeHierarchy hierarchy = builder .setFadeDuration(300) .setPlaceholderImage(new MyCustomDrawable()) .setBackgrounds(backgroundList) .setOverlays(overlaysList) .build(); mSimpleDraweeView.setHierarchy(hierarchy); ~~~ 对于同一个View，请不要多次调用`setHierarchy`，即使这个View是可回收的。创建 DraweeHierarchy 的较为耗时的一个过程，应该多次利用。如果要改变所要显示的图片可使用`setController` 或者 `setImageURI`。 #### 修改 DraweeHierarchy DraweeHierarchy 的一些属性可以在运行时改变。要改变这些属性，首先获取一个引用: ~~~java GenericDraweeHierarchy hierarchy = mSimpleDraweeView.getHierarchy(); ~~~ ##### 修改占位图修改占位图为资源id: ~~~java hierarchy.setPlaceholderImage(R.drawable.placeholderId); ~~~ 或者修改为一个 [Drawable](http://developer.android.com/reference/android/graphics/drawable/Drawable.html): ~~~java Drawable drawable; // 创建一个drawable hierarchy.setPlaceholderImage(drawable); ~~~ ##### 修改显示的图像修改[缩放类型](#): ~~~java hierarchy.setActualImageScaleType(ScalingUtils.ScaleType.CENTER_INSIDE); ~~~ 当然，如果修改为 `focusCrop,` 需要指定一个居中点: ~~~java hierarchy.setActualImageFocusPoint(point); ~~~ 或者设置一个color filter: ~~~java ColorFilter filter; // 创建filter hierarchy.setActualImageColorFilter(filter); ~~~ ##### 圆角 All of the [rounding related params](#), except the rounding method, can be modified. You get a `RoundingParams` object from the hierarchy, modify it, and set it back again: 除了圆角显示方式（原来为圆角的不能修改为圆圈，反之亦然），其他圆角相关的呈现参数, [具体参见这里](#) 是可以动态修改的。如下: 获取DraweeHierarchy的圆角显示参数，修改圆角半径为10。 ~~~java RoundingParams roundingParams = hierarchy.getRoundingParams(); roundingParams.setCornersRadius(10); hierarchy.setRoundingParams(roundingParams); ~~~ ### Drawee的各种效果配置 ### 内容导航 - [定义](#) - [设置要加载的图片](#) - [占位图](#) - [加载失败时的占位图](#) - [点击重新加载](#) - [显示一个进度条](#) - [Backgrounds](#) - [Overlays](#) - [Pressed State Overlay](#) ### 定义本页说明如何设置实现不同的图片呈现效果。除了要加载的图片，其他各个设置都可以在xml中指定。在xml中指定的时候，可以是 `drawable/`下的资源，也可以颜色。在Java 代码中也可以指定。如果需要 [通过程序设定](#) 的话会接触到这个类: GenericDraweeHierarchyBuilder 通过代码设置是，设置的值可以是资源id，也可以是 Drawable 的子类。创建完 GenericDraweeHierarchy 之后，也可以通过该类的相关方法，重新设置一些效果。大多数的用户呈现不同效果的drawables都是可以[缩放的](#). ### 设置要加载的图除了需要加载的图片是真正必须的，其他的都是可选的。如前所述，图片可以来自多个地方。所需加载的图片实际是DraweeController的一个属性，而不是 DraweeHierarchy 的属性。可使用`setImageURI`方法或者通过设置 DraweeController 来进行设置。对于要加载的图片，除了可以设置缩放类型外，DraweeHierarchy 还公开出一些其他方法用来控制显示效果: - focus point (居中焦点, 用于 focusCrop 缩放模式) - color filter 默认的缩放类型是: `centerCrop` ### 占位图(Placeholder) 在调用`setController` 或者 `setImageURI` 之后，占位图开始显示，直到图片加载完成。对于渐进式格式的JPEG图片，占位图会显示直到满足已加载的图片解析度到达设定值。 XML 中属性值: `placeholderImage` Hierarchy builder中的方法: `setPlaceholderImage` Hierarchy method: `setPlaceholderImage` 默认值: a transparent [ColorDrawable](http://developer.android.com/reference/android/graphics/drawable/ColorDrawable.html) 默认缩放类型: `centerInside` ### 设置加载失败占位图如果URI是无效的，或者下载过程中网络不可用，将会导致加载失败。当加载图片出错时，你可以设置一个出错提示图片。 XML 中属性值: `failureImage` Hierarchy builder中的方法: `setFailureImage` 默认值: The placeholder image 默认缩放类型: `centerInside` ### 点击重新加载图在加载失败时，可以设置点击重新加载。这时提供一个图片，加载失败时，会显示这个图片（而不是失败提示图片），提示用户点击重试。在[ControllerBuilder](#) 中如下设置: ~~~ .setTapToRetryEnabled(true) ~~~ 加载失败时，image pipeline 会重试四次；如果还是加载失败，则显示加载失败提示图片。 XML 中属性值: `retryImage` Hierarchy builder中的方法: `setRetryImage` 默认值: The placeholder image 默认缩放类型: `centerInside` ### 显示一个进度条设置一个进度条图片，提示用户正在加载。目前，进度条仅仅是提示正在loading，和加载进度无关。 XML 中属性值: `progressBarImage` Hierarchy builder中的方法: `setProgressBarImage` 默认值: None 默认缩放类型: `centerInside` ### 背景背景图会最先绘制，在XML中只可以指定一个背景图，但是在JAVA代码中，可以指定多个背景图。当指定一个背景图列表的时候，列表中的第一项会被首先绘制，绘制在最下层，然后依次往上绘制。背景图片不支持缩放类型，会被强制到`Drawee`尺寸大小。 XML 中属性值: `backgroundImage` Hierarchy builder中的方法: `setBackground,``setBackgrounds` 默认值: None 默认缩放类型: N/A ### 设置叠加图(Overlay) 叠加图会最后被绘制。和背景图一样，XML中只可以指定一个，如果想指定多个，可以通过JAVA代码实现。当指定的叠加图是一个列表的时候，列表第一个元素会被先绘制，最后一个元素最后被绘制到最上层。同样的，不支持各种缩放类型。 XML 中属性值: `overlayImage` Hierarchy builder中的方法: `setOverlay,``setOverlays` 默认值: None 默认缩放类型: N/A ### 设置按压状态下的叠加图同样不支持缩放，用户按压DraweeView时呈现。 XML 中属性值: `pressedStateOverlayImage` Hierarchy builder中的方法: `setPressedStateOverlay` 默认值: None 默认缩放类型: N/A ### 缩放对于 Drawee 的[各种效果配置](#)，其中一些是支持缩放类型的。 #### 可用的缩放类型 <table><thead><tr><th>类型</th> <th>描述</th></tr></thead><tbody><tr><td>center</td> <td>居中，无缩放</td></tr><tr><td>centerCrop</td> <td>保持宽高比缩小或放大，使得两边都大于或等于显示边界。居中显示。</td></tr><tr><td><a class="internal" href="#focusCrop">focusCrop</a></td> <td>同centerCrop, 但居中点不是中点，而是指定的某个点</td></tr><tr><td>centerInside</td> <td>使两边都在显示边界内，居中显示。<br/>如果图尺寸大于显示边界，则保持长宽比缩小图片。</td></tr><tr><td>fitCenter</td> <td>保持宽高比，缩小或者放大，使得图片完全显示在显示边界内。居中显示</td></tr><tr><td>fitStart</td> <td>同上。但不居中，和显示边界左上对齐</td></tr><tr><td>fitEnd</td> <td>同fitCenter，但不居中，和显示边界右下对齐</td></tr><tr><td>fitXY</td> <td>不保存宽高比，填充满显示边界</td></tr><tr><td><a class="internal" href="#none">none</a></td> <td>如要使用tile mode显示, 需要设置为none</td></tr></tbody></table> 这些缩放类型和Android [ImageView](http://developer.android.com/reference/android/widget/ImageView.ScaleType.html) 支持的缩放类型几乎一样. 唯一不支持的缩放类型是`matrix.` Fresco 提供了`focusCrop` 作为补充。通常这个缩放效果更佳。 #### focusCrop `centerCrop`缩放模式会保持长宽比，缩放图片，填充满显示边界，居中显示。这个缩放模式在通常情况下很有用。但是对于人脸等图片时，一味地居中显示，这个模式可能会裁剪掉一些有用的信息。以人脸图片为例，借助一些类库，我们可以识别出人脸所在位置。如果可以设置以人脸位置居中裁剪显示，那么效果会好很多。 Fresco的focusCrop缩放模式正是为此而设计。只要提供一个居中聚焦点，显示时就会**尽量**以此点为中心。居中点是以相对方式给出的，比如(0.5f, 0.5f)就是居中显示，(0f, 0f)就是左上对齐显示。如果要使用此缩放模式，首先指定缩放模式。在XML: ~~~xml fresco:actualImageScaleType="focusCrop" ~~~ 在Java代码中 ~~~java PointF focusPoint; // your app populates the focus point mSimpleDraweeView .getHierarchy() .setActualImageFocusPoint(focusPoint); ~~~ #### none 如果你要使用tile mode进行显示，那么需要将scale type 设置为none. ### 圆角和圆圈 Drawee 轻松支持圆角显示，并且显示圆角时，并不复制和修改Bitmap对象，那样太耗费内存。 #### 圆角圆角实际有2中呈现方式: 1. 圆圈 - 设置`roundAsCircle`为true 1. 圆角 - 设置`roundedCornerRadius` 设置圆角时，支持4个角不同的半径。XML中无法配置，但可在Java代码中配置。 #### 设置圆角可使用以下两种方式: 1. 默认使用一个shader绘制圆角，但是仅仅占位图所要显示的图有圆角效果。失败示意图和重下载示意图无圆角效果。 1. 叠加一个`solid color`来绘制圆角。但是背景需要固定成指定的颜色。在XML中指定 `roundWithOverlayColor`, 或者通过调用`setOverlayColor`来完成此设定。 #### XML中配置 `SimpleDraweeView` 支持如下几种圆角配置: ~~~xml <com.facebook.drawee.view.SimpleDraweeView ... fresco:roundedCornerRadius="5dp" fresco:roundBottomLeft="false" fresco:roundBottomRight="false" fresco:roundWithOverlayColor="@color/blue" fresco:roundingBorderWidth="1dp" fresco:roundingBorderColor="@color/red" ~~~ #### 代码中配置在创建 DraweeHierarchy 时，可以给`GenericDraweeHierarchyBuilder`指定一个 RoundingParams 用来绘制圆角效果。 ~~~java RoundingParams roundingParams = RoundingParams.fromCornersRadius(7f); roundingParams.setOverlayColor(R.color.green); // 或用 fromCornersRadii 以及 asCircle 方法 genericDraweeHierarchyBuilder .setRoundingParams(roundingParams); ~~~ 你也可以在运行时，改变圆角效果 ~~~java RoundingParams roundingParams = mSimpleDraweeView.getHierarchy().getRoundingParams(); roundingParams.setBorder(R.color.red, 1.0); roundingParams.setRoundAsCircle(true); mSimpleDraweeView.getHierarchy().setRoundingParams(roundingParams); ~~~ > 在运行时，不能改变呈现方式: 原本是圆角，不能改为圆圈。 ### 使用ControllerBuilder `SimpleDraweeView` 有两个方法可以设置所要加载显示图片，简单的方法就是`setImageURI`。如果你需要对加载显示的图片做更多的控制和定制，那就需要用到 DraweeController，本页说明如何使用。 #### DraweeController 首先，创建一个DraweeController, 然后传递图片加载请求给 PipelineDraweeControllerBuilder 随后，你可以控制controller的其他选项了: ~~~java ControllerListener listener = new BaseControllerListener() {...} DraweeController controller = Fresco.newDraweeControllerBuilder() .setUri(uri) .setTapToRetryEnabled(true) .setOldController(mSimpleDraweeView.getController()) .setControllerListener(listener) .build(); mSimpleDraweeView.setController(controller); ~~~ 在指定一个新的controller的时候，使用`setOldController`，这可节省不必要的内存分配。 #### 自定义图片加载请求在更进一步的用法中，你需要给Image pipeline 发送一个ImageRequest。下面是一个图片加载后，使用后处理器(postprocessor) 进行图片后处理的例子. ~~~java Uri uri; Postprocessor myPostprocessor = new Postprocessor() { ... } ImageRequest request = ImageRequestBuilder.newBuilderWithSource(uri) .setPostprocessor(myPostprocessor) .build(); DraweeController controller = Fresco.newDraweeControllerBuilder() .setImageRequest(request) .setOldController(mSimpleDraweeView.getController()) // 其他设置 .build(); ~~~ ### 渐进式JPEG图 *注意: 本页提及的API仅是初步设计，后续可能变动* Fresco 支持渐进式的网络JPEG图。在开始加载之后，图会从模糊到清晰渐渐呈现。你可以设置一个清晰度标准，在未达到这个清晰度之前，会一直显示占位图。渐进式JPEG图仅仅支持网络图。 ##### 初始化 [配置Image pipeline时](#) 需要传递一个 ProgressiveJpegConfig 的实例。这个实例需要完成两个事情:1. 返回下一个需要解码的扫描次数2. 确定多少个扫描次数之后的图片才能开始显示。下面的实例中，为了实现节省CPU，并不是每个扫描都进行解码。注意: - 每次解码完之后，调用`getNextScanNumberToDecode`, 等待扫描值大于返回值，才有可能进行解码。假设，随着下载的进行，下载完的扫描序列如下: `1, 4, 5, 10`。那么： 1. 首次调用`getNextScanNumberToDecode`返回为2，因为初始时，解码的扫描数为0。 1. 那么1将不会解码，下载完成4个扫描时，解码一次。下个解码为扫描数为6 1. 5不会解码，10才会解码 ~~~java ProgressiveJpegConfig pjpegConfig = new ProgressiveJpegConfig() { @Override public int getNextScanNumberToDecode(int scanNumber) { return scanNumber + 2; } public QualityInfo getQualityInfo(int scanNumber) { boolean isGoodEnough = (scanNumber >= 5); return ImmutableQualityInfo.of(scanNumber, isGoodEnough, false); } } ImagePipelineConfig config = ImagePipelineConfig.newBuilder() .setProgressiveJpegConfig(pjpeg) .build(); ~~~ 除了自己实现ProgressiveJpegConfig，也可以直接使用 SimpleProgressiveJpegConfig ##### At Request Time 目前，我们必须显式地在加载时，允许渐进式JPEG图片加载。 ~~~java Uri uri; ImageRequest request = ImageRequestBuilder .newBuilderWithSource(uri) .setProgressiveRenderingEnabled(true) .build(); PipelineDraweeController controller = Fresco.newControllerBuilder() .setImageRequest(requests) .setOldController(mSimpleDraweeView.getController()) .build(); mSimpleDraweeView.setController(controller); ~~~ 我们希望在后续的版本中，在`setImageURI`方法中可以直接支持渐进式图片加载。 ### 动画图(gif) Fresco 支持GIF和WebP 格式图片；支持WebP 格式的动画图也支持(包括扩展WebP 格式)，支持2.3及其以后那些没有原生WebP支持的系统。 #### 设置动画图自动播放如果你希望图片下载完之后自动播放，同时，当View从屏幕移除时，停止播放，只需要在[image request](#) 中简单设置，如下: ~~~java Uri uri; ImageRequest request = ImageRequestBuilder.newBuilderWithSource(uri) .setAutoPlayAnimation(true) . // other setters .build(); DraweeController controller = Fresco.newDraweeControllerBuilder() .setImageRequest(request) . // other setters .build(); mSimpleDraweeView.setController(controller); ~~~ #### 手动控制动画图播放也许，你希望在图片加载完之后，手动控制动画的播放，那么这样做： ~~~java ControllerListener controllerListener = new BaseControllerListener() { @Override public void onFinalImageSet( String id, @Nullable ImageInfo imageInfo, @Nullable Animatable anim) { if (anim != null) { // 根据业务逻辑，在合适的时机播放动画。 } }; Uri uri; PipelineDraweeController controller = Fresco.newControllerBuilder() .setControllerListener(controllerListener) .setUri(uri); // other setters .build(); mSimpleDraweeView.setController(controller); ~~~ 另外，controller提供对[Animatable](http://developer.android.com/reference/android/graphics/drawable/Animatable.html) 的访问。如果有可用动画的话，可对动画进行灵活的控制: ~~~java Animatable animation = mSimpleDraweeView.getController().getAnimatable(); if (animation != null) { // 开始播放 animation.start(); // 一段时间之后，根据业务逻辑，停止播放 animation.stop(); } ~~~ ### 多图请求及图片复用多图请求需 [自定义ImageRequest](#). #### 先显示低分辨率的图，然后是高分辨率的图如果你要显示一张高分辨率的图，但是这张图下载比较耗时。你可以在下载前，先提供一张很快能下载完的小缩略图。这比一直显示占位图，用户体验会好很多。这时，你可以设置两个图片的URI，一个是低分辨率的缩略图，一个是高分辨率的图。 ~~~java Uri lowResUri, highResUri; PipelineDraweeController controller = Fresco.newControllerBuilder() .setLowResImageRequest(ImageRequest.fromUri(lowResUri)) .setImageRequest(ImageRequest.fromUri(highResUri)) .setOldController(mSimpleDraweeView.getController()) .build(); mSimpleDraweeView.setController(controller); ~~~ #### 缩略图预览 *本功能仅支持本地URI，并且是JPEG图片格式* 如果本地JPEG图，有EXIF的缩略图，image pipeline 会立刻返回一个缩略图。完整的清晰大图，在decode完之后再显示。 ~~~java Uri uri; ImageRequest request = ImageRequestBuilder.newBuilderWithSource(uri) .setLocalThumbnailPreviewsEnabled(true) .build(); PipelineDraweeController controller = Fresco.newControllerBuilder() .setImageRequest(request) .setOldController(mSimpleDraweeView.getController()) .build(); mSimpleDraweeView.setController(controller); ~~~ #### 本地图片复用大部分的时候，一个图片可能会对应有多个URI，比如: - 拍照上传。本地图片较大，上传的图片较小。上传完成之后的图片，有一个url，如果要加载这个url，可直接加载本地图片。 - 本地已经有600x600尺寸的大图了，需要显示100x100的小图对于一个URI，image pipeline 会依次检查内存，磁盘，如果没有从网络下载。而对于一个图片的多个URI，image pipeline 会先检查他们是否在内存中。如果没有任何一个是在内存中的，会检查是否在本地存储中。如果也没有，才会执行网络下载。但凡有任何一个检查发现在内存或者在本地存储中，都会进行复用。列表顺序就是要显示的图片的优先顺序。使用时，创建一个image request 列表，然后传给ControllerBuilder: ~~~java Uri uri1, uri2; ImageRequest request = ImageRequest.fromUri(uri1); ImageRequest request2 = ImageRequest.fromUri(uri2); ImageRequest[] requests = { request1, request2 }; PipelineDraweeController controller = Fresco.newControllerBuilder() .setFirstAvailableImageRequests(requests) .setOldController(mSimpleDraweeView.getController()) .build(); mSimpleDraweeView.setController(controller); ~~~ ### 监听下载事件你也许想在图片下载完成或者下载失败之后，做一些其他事情。图片是后台线程异步加载的，我们可以使用一个`ControllerListener`实现事件的监听。 _在监听事件回调时，无法修改图片，如果需要修改图片，可使用[后处理器(Postprocessor)](#) ~~~ ControllerListener controllerListener = new BaseControllerListener() { @Override public void onFinalImageSet( String id, @Nullable ImageInfo imageInfo, @Nullable Animatable anim) { if (imageInfo == null) { return; } QualityInfo qualityInfo = imageInfo.getQualityInfo(); FLog.d("Final image received! " + "Size %d x %d", "Quality level %d, good enough: %s, full quality: %s", imageInfo.getWidth(), imageInfo.getHeight(), qualityInfo.getQuality(), qualityInfo.isOfGoodEnoughQuality(), qualityInfo.isOfFullQuality()); } @Override public void onIntermediateImageSet(String id, @Nullable ImageInfo imageInfo) { FLog.d("Intermediate image received"); } @Override public void onFailure(String id, Throwable throwable) { FLog.e(getClass(), throwable, "Error loading %s", id) } }; Uri uri; DraweeController controller = Fresco.newControllerBuilder() .setControllerListener(controllerListener) .setUri(uri); // other setters .build(); mSimpleDraweeView.setController(controller); ~~~ 对所有的图片加载，`onFinalImageSet` 或者 `onFailure` 都会被触发。前者在成功时，后者在失败时。如果允许呈现[渐进式JPEG](#)，同时图片也是渐进式图片，`onIntermediateImageSet`会在每个扫描被解码后回调。具体图片的那个扫描会被解码，参见[渐进式JPEG图](#) ### 缩放和旋转图片使用这个功能需要直接[创建 image request](#)。 ### 缩放图片 #### 什么时候该修改图片尺寸一般地，当所要显示的图片和显示区域大小不一致时，会按以下方式进行处理。 1. 从服务器下载小一些的图片 1. 显示时缩放图片 1. 调整图片尺寸大小对于一个图片，如果服务器支持不同尺寸的缩略图，那么每次下载都选择尺寸最匹配的图片，这个不仅节省数据流量也节约本地储存和CPU。如果服务器不支持，或者处理本地图片的话，第二个选择是[使用缩放类型](#)。缩放是用Androi内置的功能使图像和显示边界相符。在4.0之后，支持硬件加速。这在大部分情况下是最快，同时也是最高效的显示一张和显示边界大小相符的图片的方式。首先指定`layout_width`和`layout_width`为指定值，然后指定[缩放类型](#) 但当所要显示的图片比显示区域大许多的时候，不推荐这样做，缩放过程会导致大量的内存消耗。这时，需要改变图片尺寸。 #### 修改图片尺寸调整大小并不是修改原来的文件，而是在解码之前，在native内存中修改。这个缩放方法，比Android内置的缩放范围更大。Android相机生成的照片一般尺寸都很大，需要调整大小之后才能被显示。目前，仅仅支持JPEG格式的图片，同时，大部分的Android系统相机图片都是JPEG的。如果要修改图片尺寸，创建`ImageRequest`时，提供一个 ResizeOptions: ~~~java Uri uri = "file:///mnt/sdcard/MyApp/myfile.jpg"; int width = 50, height = 50; ImageRequest request = ImageRequestBuilder.newBuilderWithSource(uri) .setResizeOptions(new ResizeOptions(width, height)) .build(); PipelineDraweeController controller = Fresco.newDraweeControllerBuilder() .setOldController(mDraweeView.getController()) .setImageRequest(request) .build(); mSimpleDraweeView.setController(controller); ~~~ ### 自动旋转如果看到的图片是侧着的，用户是难受的。许多设备会在JPEG文件的metadata中记录下照片的方向。如果你想图片呈现的方向和设备屏幕的方向一致，你可以简单地这样做到: ~~~java ImageRequest request = ImageRequestBuilder.newBuilderWithSource(uri) .setAutoRotateEnabled(true) .build(); // as above ~~~ ### 修改图片有时，我们想对从服务器下载，或者本地的图片做些修改，比如在某个坐标统一加个网格什么的。这时使用后处理器(Postprocessor)便可达到目的。 ##### 例子: 给图片加个网格: ~~~java Uri uri; Postprocessor redMeshPostprocessor = new Postprocessor() { @Override public String getName() { return "redMeshPostprocessor"; } @Override public void process(Bitmap bitmap) { for (int x = 0; x < bitmap.getWidth(); x+=2) { for (int y = 0; y < bitmap.getHeight(); y+=2) { bitmap.setPixel(x, y, Color.RED); } } } } ImageRequest request = ImageRequestBuilder.newBuilderWithSource(uri) .setPostprocessor(redMeshPostprocessor) .build(); PipelineDraweeController controller = Fresco.newDraweeControllerBuilder() .setImageRequest(request) .setOldController(mSimpleDraweeView.getOldController()) // other setters as you need .build(); mSimpleDraweeView.setController(controller); ~~~ ##### 注意点图片在进入后处理器(postprocessor)的图片是原图的一个完整拷贝，原来的图片不受修改的影响。在5.0以前的机器上，拷贝后的图片也在native内存中。在开始一个图片显示时，即使是反复显示同一个图片，在每次进行显示时，都需要指定后处理器。对于同一个图片，每次显示，可以使用不同的后处理器。 ##### Repeated Postprocessors 如果想对同一个图片进行多次后处理，那么继承 BaseRepeatedPostprocessor 即可。该类有一个`update`方法，需要执行后处理时，调用该方法即可。下面的例子展示了在运行时，后处理改变图片网格的颜色: ~~~java public class MeshPostprocessor extends BaseRepeatedPostprocessor { private int mColor = Color.TRANSPARENT; public void setColor(int color) { mColor = color; update(); } @Override public String getName() { return "meshPostprocessor"; } @Override public void process(Bitmap bitmap) { for (int x = 0; x < bitmap.getWidth(); x+=2) { for (int y = 0; y < bitmap.getHeight(); y+=2) { bitmap.setPixel(x, y, mColor); } } } } MeshPostprocessor meshPostprocessor = new MeshPostprocessor(); // setPostprocessor as in above example // 改变颜色 meshPostprocessor.setColor(Color.RED); meshPostprocessor.setColor(Color.BLUE); ~~~ 每个image request, 仍旧只有一个`Postprocessor`，但是这个后处理器是状态相关了。 ### 图片请求如果你需要的`ImageRequest`仅仅是一个URI，那么`ImageRequest.fromURI`就足够了，在[多图请求及图片复用](#)中，有这样的用法。否则，你需要`ImageRequestBuilder`来做更多的事情。 ~~~java Uri uri; ImageDecodeOptions decodeOptions = ImageDecodeOptions.newBuilder() .setBackgroundColor(Color.GREEN) .build(); ImageRequest request = ImageRequestBuilder .newBuilderWithSource(uri) .setAutoRotateEnabled(true) .setLocalThumbnailPreviewsEnabled(true) .setLowestPermittedRequestLevel(RequestLevel.FULL_FETCH) .setProgressiveRenderingEnabled(false) .setResizeOptions(new ResizeOptions(width, height)) .build(); ~~~ ##### ImageRequest 的属性和成员 - `uri` - 唯一的必选的成员. 参考 [支持的URIs](#) - `autoRotateEnabled` - 是否支持[自动旋转](#). - `progressiveEnabled` - 是否支持[渐进式加载](#). - `postprocessor` - [后处理器(postprocess)](#). - `resizeOptions` - 图片缩放选项，用前请先阅读[缩放和旋转](#). ##### 最低请求级别 Image pipeline 加载图片时有一套明确的[请求流程](#) 1. 检查内存缓存，有如，立刻返回。这个操作是实时的。 1. 检查未解码的图片缓存，如有，解码并返回。 1. 检查磁盘缓存，如果有加载，解码，返回。 1. 下载或者加载本地文件。调整大小和旋转（如有），解码并返回。对于网络图来说，这一套流程下来是最耗时的。 `setLowestPermittedRequestLevel`允许设置一个最低请求级别，请求级别和上面对应地有以下几个取值: - `BITMAP_MEMORY_CACHE` - `ENCODED_MEMORY_CACHE` - `DISK_CACHE` - `FULL_FETCH` 如果你需要立即取到一个图片，或者在相对比较短时间内取到图片，否则就不显示的情况下，这非常有用。 ### 自定义View #### DraweeHolders 总有一些时候，`DraweeViews`是满足不了需求的，在展示图片的时候，我们还需要展示一些其他的内容，或者支持一些其他的操作。在同一个View里，我们可能会想显示一张或者多张图。在自定义View中，Fresco 提供了两个类来负责图片的展现: - `DraweeHolder` 单图情况下用。 - `MultiDraweeHolder` 多图情况下用。 #### 自定义View需要完成的事情 Android 呈现View对象，只有View对象才能得到一些系统事件的通知。`DraweeViews`处理这些事件通知，高效地管理内存。使用`DraweeHolder`时，你需要自己实现这几个方法。 ##### 处理 attach/detach 事件 **如果没按照以下步骤实现的话，很可能会引起内存泄露** 当图片不再在View上显示时，比如滑动时View滑动到屏幕外，或者不再绘制，图片就不应该再存在在内存中。Drawees 监听这些事情，并负责释放内存。当图片又需要显示时，重新加载。这些在`DraweeView`中是自动的，但是在自定义View中，需要我们自己去操作，如下: ~~~java DraweeHolder mDraweeHolder; @Override public void onDetachedFromWindow() { super.onDetachedToWindow(); mDraweeHolder.onDetach(); } @Override public void onStartTemporaryDetach() { super.onStartTemporaryDetach(); mDraweeHolder.onDetach(); } @Override public void onAttachedToWindow() { super.onAttachedToWindow(); mDraweeHolder.onAttach(); } @Override public void onFinishTemporaryDetach() { super.onFinishTemporaryDetach(); mDraweeHolder.onAttach(); } ~~~ ##### 处理触摸事件如果你启用了[点击重新加载](#)，在自定义View中，需要这样: ~~~java @Override public boolean onTouchEvent(MotionEvent event) { return mDraweeHolder.onTouchEvent(event) || super.onTouchEvent(event); } ~~~ ##### 自定义onDraw ~~~java Drawable drawable = mDraweeHolder.getHierarchy().getTopLevelDrawable(); drawable.setBounds(...); ~~~ 否则图片将不会出现 - 不要向下转换这个Drawable - 不要变换这个Drawable ##### 其他应该做的 - 重写 `verifyDrawable:` ~~~java @Override protected boolean verifyDrawable(Drawable who) { if (who == mDraweeHolder.getHierarchy().getTopLevelDrawable()) { return true; } // 对其他Drawable的验证逻辑 } ~~~ - 确保`invalidateDrawable` 处理了图片占用的那块区域。 #### 创建 DraweeHolder 这同样需要非常小心和细致 ##### 构造函数我们推荐如下实现构造函数: - 重写3个构造函数 - 在每个构造函数中调用同等签名的父类构造函数，和一个私有的`init`方法。 - 在`init`方法中执行初始化操作。即，不要在构造函数中用`this`来调用另外一个构造。这样可以保证，不管调用哪个构造，都可以正确地执行初始化流程。然后在`init`方法中创建holder。 ##### 创建 Holder 如果有可能，只在View创建时，创建Drawees。创建DraweeHierarchy开销较大，最好只做一次。 ~~~java class CustomView extends View { DraweeHolder<GenericDraweeHierarchy> mDraweeHolder; // constructors following above pattern private void init() { GenericDraweeHierarchy hierarchy = new GenericDraweeHierarchyBuilder(getResources()); .set... .set... .build(); mDraweeHolder = DraweeHolder.create(hierarchy, context); } } ~~~ ##### 设置要显示的图片使用[controller builder](#)创建DraweeController，然后调用holder的`setController`方法，而不是设置给自定义View。 ~~~java DraweeController controller = Fresco.newControllerBuilder() .setUri(uri) .setOldController(mDraweeHolder.getController()) .build(); mDraweeHolder.setController(controller); ~~~ #### MultiDraweeHolder 和`DraweeHolder`相比，`MultiDraweeHolder`有 `add`, `remove`, `clear`等方法可以操作Drawees。如下: ~~~java MultiDraweeHolder<GenericDraweeHierarchy> mMultiDraweeHolder; private void init() { GenericDraweeHierarchy hierarchy = new GenericDraweeHierarchyBuilder(getResources()); .set... .build(); mMultiDraweeHolder = new MultiDraweeHolder<GenericDraweeHierarchy>(); mMultiDraweeHolder.add(new DraweeHolder<GenericDraweeHierarchy>(hierarchy, context)); // repeat for more hierarchies } ~~~ 同样，也需要处理系统事件，设置声音等等，就想处理单个`DraweeHolder`那样。 ### 一些陷阱 ##### 不要向下转换不要试图把Fresco返回的一些对象进行向下转化，这也许会带来一些对象操作上的便利，但是也许在后续的版本中，你会遇到一些因为向下转换特性丢失导致的难以处理的问题。 ##### 不要使用getTopLevelDrawable `DraweeHierarchy.getTopLevelDrawable()`**仅仅** 应该在DraweeViews中用，除了定义View中，其他应用代码建议连碰都不要碰这个。在自定义View中，也千万不要将返回值向下转换，也许下个版本，我们会更改这个返回值类型。 ##### 不要复用 DraweeHierarchies 永远不要吧`DraweeHierarchy` 通过 `DraweeView.setHierarchy` 设置给不同的View。DraweeHierarchy是由一系列Drawable组成的。在Android中, Drawable不能被多个View共享。 ##### 不要在多个DraweeHierarchy中使用同一个Drawable 原因同上。当时可以使用不同的资源ID。Android实际会创建不同的Drawable。 ##### 不要直接给 `DraweeView` 设置图片。目前 `DraweeView` 直接继承于ImageView，因此它有 `setImageBitmap`,`setImageDrawable` 等方法。如果利用这些方法，直接设置一个图片。内部的`DraweeHierarchy`就会丢失，也就无法取到imagepipeline 的任何图像了。 ##### 使用DraweeView时，请不要使用任何ImageView的属性在后续的版本中，DraweeView会直接从View派生。任何属于ImageView但是不属于View的方法都会被移除。