Xamarin.Forms 用户界面——控件——Images

图片

在Xamarin.Forms中加载和显示图像

PDF用于离线使用

• 下载PDF

示例代码：

• ImagesSample

相关文章：

• iOS应用程序图标
• iOS启动图像
• Android图像
• Windows Phone平铺设计
• Windows Phone Splash屏幕

让我们知道你对此的感受

最后更新：2016年6月

可以使用Xamarin.Forms跨平台共享图像，可以为每个平台专门加载，也可以下载显示。

概观

图像是应用程序导航，可用性和品牌宣传的重要组成部分。Xamarin.Forms应用程序需要能够在所有平台上共享图像，但也可能在每个平台上显示不同的图像。

平台特定的图像也需要图标和闪屏; 这些需要在每个平台的基础上进行配置。

本文档讨论如下：

• 本地图像 - 显示应用程序随附的图像，包括解析诸如iOS Retina或Android高DPI版本的图像之类的本机分辨率。
• 嵌入图像 - 显示作为装配资源嵌入的图像。
• 下载的图像 - 下载和显示图像。
• 图标和splashscreens - 平台特定的图标和启动图像。

图像和ImageSource

Xamarin.Forms使用Image视图在页面上显示图像。它有两个重要的属性：

• 源 - 一个 ImageSource实例，File，Uri或Resource，用于设置要显示的图像
• 方面 - 如何在显示内容（无论是伸展，裁剪还是信箱）中显示图像的大小。

ImageSource 使用静态方法为每种类型的图像源轻松获取实例：

• FromFile - 需要可以在每个平台上解析的文件名或文件路径。
• FromUri - 需要一个Uri对象，例如。 new Uri("http://server.com/image.jpg")。
• FromResource - 使用Build Action：EmbeddedResource，将资源标识符嵌入应用程序或PCL中嵌入的图像文件 。

在Aspect确定如何图像将被缩放以适合显示区：

• 填充 - 将图像拉伸至完全填充显示区域。这可能会导致图像失真。
• AspectFill - 剪切图像，使其填满显示区域，同时保留方面（即无失真）。
• AspectFit - 将图像信号（如果需要），使整个图像适合显示区域，根据图像是宽还是高，空白空间添加到顶部/底部或侧面。

图像可以从本地文件，嵌入式资源加载或下载。

本地图片

图像文件可以添加到每个应用程序项目，并从Xamarin.Forms共享代码引用。要在所有应用程序中使用单个映像，必须在每个平台上使用相同的文件名，它应该是一个有效的Android资源名称（即只允许使用小写字母，数字，下划线和期限）。

• iOS - 将图像放在 资源文件夹中，并具有 构建操作：BundleResource。还应提供图像的Retina版本 - 分辨率的两倍和三倍，文件扩展名前的@ 2x或@ 3x后缀（例如myimage@2x.png）。
• Android - 将图像放在 资源/可绘制目录中与 Build Action：AndroidResource。还可以提供图像的高和低DPI版本（在适当名称的 资源子目录中，例如 drawable-ldpi， drawable-hdpi和 drawable-xhdpi）。
• Windows Phone - 使用Build Action：Content将图像放在应用程序的根目录中 。
• Windows / UWP - 使用Build Action：Content将图像放在应用程序的根目录中 。

此截图显示了Xamarin.Forms解决方案，每个应用程序项目中都有一个图像文件：

遵守文件命名和放置的规则允许两行共享代码在所有平台上加载和显示图像：

var beachImage = new Image { Aspect = Aspect.AspectFit };
beachImage.Source = ImageSource.FromFile("waterfront.jpg");

更好的是，有一个隐式转换，以便这一行也有效：

beachImage.Source = "waterfront.jpg";

图像文件本身可以复制（即复制到每个应用程序项目中）或保存在单个位置，并将文件链接到正确的目录中。

为了获得更大的灵活性，该Device.OnPlatform方法可用于为某些或所有平台选择不同的图像文件或路径，如此代码片段所示：

beachImage.Source =  Device.OnPlatform(
            iOS: ImageSource.FromFile("Images/waterfront.jpg"),
            Android:  ImageSource.FromFile("waterfront.jpg"),
            WinPhone: ImageSource.FromFile("Images/waterfront.png"));

注意：如上所述，要在所有平台上使用相同的图像文件名，所有平台上的名称必须是有效的。Android可绘制具有命名限制 - 只允许使用小写字母，数字，下划线和周期 - 并且对于跨平台兼容性，必须在所有其他平台上遵循。示例文件名** waterfront.png **遵循规则，但无效文件名的示例包括“water front.png”，“WaterFront.png”，“water-front.png”和“wåterfront.png”。

使用Xaml

可以在Xaml页面中引用相同的图像，如下所示：

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
       xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
       x:Class="WorkingWithImages.LocalImagesXaml">
  <StackLayout VerticalOptions="Center" HorizontalOptions="Center">
    <Label Text="ImageSource.FromFile" />
    <Image Source="waterfront.jpg" />
    <Label Text="'waterfront.jpg' is referenced in Xaml" />
  </StackLayout>
</ContentPage>

本地决议（视网膜和高新闻媒体）

iOS和Android平台都支持不同的图像分辨率，操作系统根据设备的功能在运行时选择适当的图像。Xamarin.FormsImageSource使用本地平台的API来加载本地映像，因此如果文件正确命名并位于项目中，它将自动支持备用分辨率。

iOS Retina图像应放置在与非Retina图像相同的位置，文件名上带有@ 2x或@ 3x后缀。这个屏幕截图，来自Xamarin.FormsWorkingWithImages示例的iOS项目，显示了正常和Retina图像：

Android替代分辨率图像应放置在Android项目中的特殊目录中：

只有FileImageSource会自动加载备用分辨率图像; 在ResourceImageSource与UriImageSource下面描述的没有。

使用图像的控件

某些控件具有需要图像的属性，例如：

• 页面 - 继承的任何东西 Page都有字符串 Icon和 BackgroundImage属性，可以分配本地文件引用。当这些页面在导航控件中用作选项卡或主 - 细节时，如果平台支持该图标，则会显示该图标。将其视为一个 FileImageSource，并将图标图像文件放在每个应用程序项目中。
• ToolbarItem - 具有与 Icon属性相似的 Page.Icon属性，可以设置为本地文件引用的字符串。
• 的ImageCell -使用 ListView和 TableView控制，有一个 Image属性，其来源可以设置。该 ImageSource可以是任何支持的类型（文件，URI或资源）的。

嵌入图像

嵌入式图像也随应用程序（如本地图像）一起提供，但不是在每个应用程序的文件结构中具有图像副本，而是将图像文件作为资源嵌入到程序集中。这种分发图像的方法特别适用于创建组件，因为图像与代码捆绑在一起。

要在项目中嵌入图像，请右键单击以添加新项目并选择要添加的图像。默认情况下，该图像将具有构建操作：无 ; 这需要设置为Build Action：EmbeddedResource。

可以在文件的“ 属性”窗口中查看和更改 “ 构建操作”。

在这个例子中，资源ID是WorkingWithImages.beach.jpg。IDE通过 将此项目的默认命名空间连接到文件名，使用每个值之间的句点（。）来生成此默认值。

如果将嵌入的图像放置到项目中的文件夹中，则文件夹名称也将以资源ID中的句点（。）分隔。移动beach.jpg图像到一个文件夹，名为MyImages将导致资源ID WorkingWithImages.MyImages.beach.jpg

加载嵌入图像的代码只需将资源ID传递给ImageSource.FromResource方法，如下所示：

var embeddedImage = new Image { Aspect = Aspect.AspectFit };
embeddedImage.Source = ImageSource.FromResource("WorkingWithImages.beach.jpg");

目前资源标识符没有隐式转换，您必须使用ImageSource.FromResource或new ResourceImageSource()加载嵌入式映像。

嵌入图像故障排除

调试代码

因为有时难以理解为什么没有加载特定的图像资源，所以可以将以下调试代码临时添加到应用程序中，以帮助确认资源配置正确。它会将嵌入给定程序集的所有已知资源输出到控制台，以帮助调试资源加载问题。

using System.Reflection;
// ...
// NOTE: use for debugging, not in released app code!
var assembly = typeof(EmbeddedImages).GetTypeInfo().Assembly;
foreach (var res in assembly.GetManifestResourceNames())
{
    System.Diagnostics.Debug.WriteLine("found resource: " + res);
}

嵌入其他项目的图像不会出现

Image.FromResource只能在与代码调用相同的程序集中查找图像FromResource。使用上面的调试代码，您可以通过将typeof()语句更改为已知在每个程序集中的类型来确定哪些程序集包含特定资源。

使用Xaml

因为从没有内置型转换器string到ResourceImageSource，这些类型的图像无法通过本地加载的XAML。

要解决这个限制，可以使用Xaml中指定的资源ID来编写一个简单的自定义Xaml标记扩展名来加载图像。

[ContentProperty ("Source")]
public class ImageResourceExtension : IMarkupExtension
{
  public string Source { get; set; }

  public object ProvideValue (IServiceProvider serviceProvider)
  {
    if (Source == null)
    {
      return null;
    }
    // Do your translation lookup here, using whatever method you require
    var imageSource = ImageSource.FromResource(Source);

    return imageSource;
  }
}

要使用此扩展xmlns，请为Xaml 添加自定义，使用正确的命名空间和项目的程序集值。然后可以使用以下语法设置图像源：{local:ImageResource WorkingWithImages.beach.jpg}。完整的Xaml示例如下所示：

<?xml version="1.0" encoding="UTF-8" ?>
<ContentPage
    xmlns="http://xamarin.com/schemas/2014/forms"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:local="clr-namespace:WorkingWithImages;assembly=WorkingWithImages"
    x:Class="WorkingWithImages.EmbeddedImagesXaml">
  <StackLayout VerticalOptions="Center" HorizontalOptions="Center">
    <!-- use a custom Markup Extension -->
    <Image Source="{local:ImageResource WorkingWithImages.beach.jpg}" />
  </StackLayout>
</ContentPage>

下载图片

该UriImageSource可自动下载用于显示的图像。它支持一个Uri对象，可以使用有效的图像URL进行初始化。

var webImage = new Image { Aspect = Aspect.AspectFit };
webImage.Source = ImageSource.FromUri(new Uri("https://xamarin.com/content/images/pages/forms/example-app.png"));

还有一个Url字符串的隐式转换，所以下面也可以使用：

webImage.Source = "https://xamarin.com/content/images/pages/forms/example-app.png";

使用Xaml

相同的图像可以在Xaml页面中下载，如下所示：

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
       xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
       x:Class="WorkingWithImages.DownloadImagesXaml">
  <StackLayout VerticalOptions="Center" HorizontalOptions="Center">
    <Label Text="Image UriSource Xaml" />
    <Image Source="https://xamarin.com/content/images/pages/forms/example-app.png" />
    <Label Text="example-app.png gets downloaded from xamarin.com" />
  </StackLayout>
</ContentPage>

下载的图像缓存

UriImageSource 还支持缓存下载的图像，通过以下属性进行配置：

• CachingEnabled - 是否启用缓存（true默认情况下）。
• CacheValidity - TimeSpan定义图像在本地存储多长时间。

默认情况下启用缓存，并将映像本地存储24小时。要禁用特定图像的缓存，请像这样实例化图像源：

Image.Source = new UriImageSource {CachingEnabled = false, Uri="http://server.com/image"};

要设置特定的缓存期（例如5天），请像这样实例化图像源：

webImage.Source = new UriImageSource {
    Uri = new Uri("https://xamarin.com/content/images/pages/forms/example-app.png"),
    CachingEnabled = true,
    CacheValidity = new TimeSpan(5,0,0,0)
};

内置缓存可以很容易地支持像滚动列表的图像一样的场景，您可以在其中设置（或绑定）每个单元格中的图像，并让内置缓存在滚动单元格时重新加载图像回到视野。

图标和splashscreens

虽然与Image课程无关，应用程序图标和splashscreens也是Xamarin.Forms项目中图像的重要用途。

为每个应用程序项目完成Xamarin.Forms应用程序的设置图标和启动屏幕。这意味着为iOS，Android和Windows Phone中的每一个生成正确大小的图像。这些图像应根据每个平台的要求进行命名和定位。

图标

有关创建这些应用程序资源的更多信息，请参阅iOS使用图像，Google图标和Windows Phone平铺设计指南

Splashscreens

只有iOS和Windows Phone应用程序需要启动屏幕（也称为启动屏幕或默认映像）。

请参阅Windows Phone 8的多分辨率应用程序中的iOS使用图像和闪屏的文档。

概要

Xamarin.Forms提供了许多不同的方法来在跨平台应用程序中包含图像，允许在平台或特定于平台的图像之间使用相同的图像。下载的图像也自动缓存，自动执行常见的编码场景。

应用程序图标和闪屏图像的设置和配置为非Xamarin.Forms应用程序 - 遵循与平台特定应用程序相同的指导。