图像

静态图片资源

React Native 提供了一种统一的方式来管理 Android 和 iOS 应用中的图片及其他媒体资产。要向应用添加静态图片，请将其放置在源代码树中的某个位置，并按如下方式引用：

tsx
<Image source={require('./my-icon.png')} />

图片名称的解析方式与 JS 模块的解析方式相同。在上面的示例中，打包器将在需要它的组件的同一文件夹中查找 my-icon.png。

您可以使用 @2x 和 @3x 后缀来为不同屏幕密度的图片提供支持。如果您有以下文件结构：

.
├── button.js
└── img
    ├── check.png
    ├── check@2x.png
    └── check@3x.png

...并且 button.js 代码包含：

tsx
<Image source={require('./img/check.png')} />

...打包器将捆绑并提供与设备屏幕密度相对应的图片。例如，check@2x.png 将用于 iPhone 7，而 check@3x.png 将用于 iPhone 7 Plus 或 Nexus 5。如果没有与屏幕密度匹配的图片，将选择最接近的最佳选项。

在 Windows 上，如果您向项目添加了新图片，可能需要重新启动打包器。

以下是您获得的一些好处：

Android 和 iOS 上的同一系统。
图片与您的 JavaScript 代码位于同一文件夹中。组件是自包含的。
没有全局命名空间，即您不必担心名称冲突。
只有实际使用的图片才会被打包到您的应用中。
添加和更改图片不需要重新编译应用，您可以像往常一样刷新模拟器。
打包器知道图片尺寸，无需在代码中重复。
图片可以通过 npm 包分发。

为了使此功能正常工作，require 中的图片名称必须是静态已知的。

tsx
// GOOD
<Image source={require('./my-icon.png')} />;

// BAD
const icon = this.props.active
  ? 'my-icon-active'
  : 'my-icon-inactive';
<Image source={require('./' + icon + '.png')} />;

// GOOD
const icon = this.props.active
  ? require('./my-icon-active.png')
  : require('./my-icon-inactive.png');
<Image source={icon} />;

请注意，以这种方式所需的图片源包含图片的尺寸（宽度、高度）信息。如果您需要动态缩放图片（例如，通过 flex），您可能需要在样式属性上手动设置 {width: undefined, height: undefined}。

静态非图片资源

上面描述的 require 语法也可以用于在您的项目中静态包含音频、视频或文档文件。支持大多数常见文件类型，包括 .mp3、.wav、.mp4、.mov、.html 和 .pdf。有关完整列表，请参阅打包器默认值。

您可以通过在您的 Metro 配置中添加一个 assetExts 解析器选项来添加对其他类型的支持。

需要注意的是，视频必须使用绝对定位而不是 flexGrow，因为目前非图片资产不传递尺寸信息。对于直接链接到 Xcode 或 Android Assets 文件夹的视频，则没有此限制。

混合应用资源中的图片

如果您正在构建混合应用（一些 UI 在 React Native 中，一些 UI 在平台代码中），您仍然可以使用已打包到应用中的图片。

对于通过 Xcode 资源目录或 Android drawable 文件夹中包含的图片，请使用不带扩展名的图片名称：

tsx
<Image
  source={{uri: 'app_icon'}}
  style={{width: 40, height: 40}}
/>

对于 Android assets 文件夹中的图片，使用 asset:/ 方案：

tsx
<Image
  source={{uri: 'asset:/app_icon.png'}}
  style={{width: 40, height: 40}}
/>

这些方法不提供安全检查。您需要自行确保这些图片在应用程序中可用。此外，您必须手动指定图片尺寸。

网络图片

您的应用中显示的许多图片在编译时不可用，或者您希望动态加载一些以减小二进制大小。与静态资源不同，_您需要手动指定图片的尺寸_。强烈建议您也使用 https，以满足 iOS 上的 App Transport Security 要求。

tsx
// GOOD
<Image source={{uri: 'https://reactjs.ac.cn/logo-og.png'}}
       style={{width: 400, height: 400}} />

// BAD
<Image source={{uri: 'https://reactjs.ac.cn/logo-og.png'}} />

图片的网络请求

如果您想在图片请求中设置 HTTP 动词、请求头或请求体等内容，可以通过在源对象上定义这些属性来实现：

tsx
<Image
  source={{
    uri: 'https://reactjs.ac.cn/logo-og.png',
    method: 'POST',
    headers: {
      Pragma: 'no-cache',
    },
    body: 'Your Body goes here',
  }}
  style={{width: 400, height: 400}}
/>

URI 数据图片

有时，您可能从 REST API 调用中获取编码的图片数据。您可以使用 'data:' URI 方案来使用这些图片。与网络资源一样，_您需要手动指定图片的尺寸_。

信息

这仅推荐用于非常小和动态的图片，例如来自数据库列表中的图标。

tsx
// include at least width and height!
<Image
  style={{
    width: 51,
    height: 51,
    resizeMode: 'contain',
  }}
  source={{
    uri: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADMAAAAzCAYAAAA6oTAqAAAAEXRFWHRTb2Z0d2FyZQBwbmdjcnVzaEB1SfMAAABQSURBVGje7dSxCQBACARB+2/ab8BEeQNhFi6WSYzYLYudDQYGBgYGBgYGBgYGBgYGBgZmcvDqYGBgmhivGQYGBgYGBgYGBgYGBgYGBgbmQw+P/eMrC5UTVAAAAABJRU5ErkJggg==',
  }}
/>

缓存控制

在某些情况下，您可能只希望在图片已存在于本地缓存中时才显示图片，例如在更高分辨率可用之前显示一个低分辨率的占位符。在其他情况下，您不关心图片是否过期，并且愿意显示过期的图片以节省带宽。cache 源属性让您可以控制网络层与缓存的交互方式。

default：使用原生平台的默认策略。
reload：将从原始源加载 URL 的数据。不应使用任何现有缓存数据来满足 URL 加载请求。
force-cache：将使用现有缓存数据来满足请求，无论其年龄或过期日期如何。如果缓存中没有与请求对应的现有数据，则从原始源加载数据。
only-if-cached：将使用现有缓存数据来满足请求，无论其年龄或过期日期如何。如果缓存中没有与 URL 加载请求对应的现有数据，则不会尝试从原始源加载数据，并且加载被视为失败。

tsx
<Image
  source={{
    uri: 'https://reactjs.ac.cn/logo-og.png',
    cache: 'only-if-cached',
  }}
  style={{width: 400, height: 400}}
/>

本地文件系统图片

请参阅 CameraRoll，了解使用 Images.xcassets 之外的本地资源的示例。

Drawable 资源

Android 支持通过 xml 文件类型加载 drawable 资源。这意味着您可以使用矢量 drawable 来渲染图标，或使用形状 drawable 来绘制形状！您可以像使用任何其他静态资源或混合资源一样导入和使用这些资源类型。您必须手动指定图片尺寸。

对于与 JS 代码一起存在的静态 drawable，使用 require 或 import 语法（两者都相同）：

tsx
<Image
  source={require('./img/my_icon.xml')}
  style={{width: 40, height: 40}}
/>

对于 Android drawable 文件夹中包含的 drawable（即 res/drawable），使用不带扩展名的资源名称：

tsx
<Image
  source={{uri: 'my_icon'}}
  style={{width: 40, height: 40}}
/>

drawable 资源与其他图片类型之间的一个主要区别是，资产必须在 Android 应用程序的编译时被引用，因为 Android 需要运行 Android Asset Packaging Tool (AAPT) 来打包资产。AAPT 创建的文件格式——二进制 XML——无法通过 Metro 通过网络加载。如果您更改资产的目录或名称，则每次都需要重新构建 Android 应用程序。

创建 XML drawable 资源

Android 在其 Drawable 资源指南中提供了有关每种支持的 drawable 资源类型的全面文档，以及原始 XML 文件的示例。您可以使用 Android Studio 的工具，如矢量资产工作室，从可伸缩矢量图形 (SVG) 和 Adobe Photoshop 文档 (PSD) 文件创建矢量 drawable。

信息

如果您想将 XML 文件视为静态图片资源（即使用 import 或 require 语句），则应避免在您创建的 XML 文件中引用其他资源。如果您希望利用对其他 drawable 或属性的引用，例如颜色状态列表或尺寸资源，您应该将您的 drawable 作为混合资源包含并通过名称导入。

最佳相机胶卷图片

iOS 会为相机胶卷中的同一图片保存多种尺寸，出于性能原因，选择最接近的尺寸非常重要。您不会希望在显示 200x200 缩略图时使用全质量 3264x2448 图片作为源。如果有精确匹配，React Native 将选择它，否则它将使用第一个至少大 50% 的图片，以避免从接近尺寸调整大小时的模糊。所有这些都是默认完成的，因此您不必担心编写繁琐（且容易出错）的代码来亲自完成。

为什么不自动调整所有尺寸？

_在浏览器中_，如果您不给图片指定尺寸，浏览器会渲染一个 0x0 的元素，下载图片，然后根据正确尺寸渲染图片。这种行为的大问题是您的 UI 会随着图片的加载而跳动，这会带来非常糟糕的用户体验。这被称为累计布局偏移。

_在 React Native 中_，这种行为是故意不实现的。开发者提前知道远程图片的尺寸（或宽高比）会增加工作量，但我们相信这会带来更好的用户体验。通过 require('./my-icon.png') 语法从应用包加载的静态图片_可以自动调整尺寸_，因为它们的尺寸在挂载时立即可用。

例如，require('./my-icon.png') 的结果可能是：

tsx
{"__packager_asset":true,"uri":"my-icon.png","width":591,"height":573}

以对象作为源

在 React Native 中，一个有趣的决定是 src 属性被命名为 source，并且不接受字符串，而是接受一个带有 uri 属性的对象。

tsx
<Image source={{uri: 'something.jpg'}} />

在基础设施方面，原因是它允许我们将元数据附加到此对象。例如，如果您使用 require('./my-icon.png')，那么我们会添加有关其实际位置和大小的信息（不要依赖此事实，它将来可能会改变！）。这也是面向未来的，例如，我们可能希望在某个时候支持精灵图，而不是输出 {uri: ...}，我们可以输出 {uri: ..., crop: {left: 10, top: 50, width: 20, height: 40}} 并透明地支持所有现有调用站点的精灵图。

在用户端，这允许您用有用的属性注释对象，例如图片的尺寸，以便计算其将显示的尺寸。随意将其用作您的数据结构，以存储有关图片的更多信息。

通过嵌套实现背景图片

Web 开发人员熟悉的一个常见功能请求是 background-image。为了处理这种情况，您可以使用组件，它具有与相同的 props，并向其中添加您想要叠加的任何子元素。

在某些情况下，您可能不希望使用，因为其实现是基本的。有关更多信息，请参阅的文档，并在需要时创建自己的自定义组件。

tsx
return (
  <ImageBackground source={...} style={{width: '100%', height: '100%'}}>
    <Text>Inside</Text>
  </ImageBackground>
);

请注意，您必须指定一些宽度和高度样式属性。

iOS 边框半径样式

请注意，iOS 的图片组件可能会忽略以下特定于角的边框半径样式属性：

borderTopLeftRadius
borderTopRightRadius
borderBottomLeftRadius
borderBottomRightRadius

非线程解码

图片解码可能需要超过一帧的时间。这是 Web 上掉帧的主要原因之一，因为解码是在主线程中完成的。在 React Native 中，图片解码在不同的线程中完成。实际上，您已经需要处理图片尚未下载的情况，因此在解码时多显示几帧占位符不需要任何代码更改。

配置 iOS 图片缓存限制

在 iOS 上，我们提供了一个 API 来覆盖 React Native 的默认图片缓存限制。这应该从您的原生 AppDelegate 代码中调用（例如，在 didFinishLaunchingWithOptions 中）。

objectivec
RCTSetImageCacheLimits(4*1024*1024, 200*1024*1024);

参数

姓名	类型	必需	描述
imageSizeLimit	数字	是	图片缓存大小限制。
totalCostLimit	数字	是	总缓存成本限制。

在上面的代码示例中，图片大小限制设置为 4 MB，总成本限制设置为 200 MB。

静态图片资源​

静态非图片资源​

混合应用资源中的图片​

网络图片​

图片的网络请求​

URI 数据图片​

缓存控制​

本地文件系统图片​

Drawable 资源​

创建 XML drawable 资源​

最佳相机胶卷图片​

为什么不自动调整所有尺寸？​

以对象作为源​

通过嵌套实现背景图片​

iOS 边框半径样式​

非线程解码​

配置 iOS 图片缓存限制​