图片资源

1. 引言

Web 应用程序通常会接收开发者提供的图片资源，在 HTML 文档之外进行显示（例如，在操作系统、在浏览器 UI 中等）。本规范定义了一个 WebIDL 字典，用于描述图片以及获取该图片资源的位置。用户代理随后可以利用这些额外信息，选择最适合在终端用户设备显示、或最契合用户偏好或环境的图片。

2. 隐私与安全注意事项

获取图片资源可能会暴露用户的 IP 地址。建议用户代理在开发者提供 图片资源时及时获取所选图片，并在需要时进行存储复用。这有助于限制对用户位置的长期跟踪。

3. 图片资源

一个图片资源包括：

src

一个用于获取图片数据的 URL。

sizes

一个可选的 字符串，表示图片的尺寸，语法与 link 元素的 sizes 属性一致。

type

一个可选的 图片 MIME 类型。

label

一个 字符串，表示图片的可访问名称。

在 API 中，图片资源用 ImageResource 字典表示。

在 [JSON] 中，图片资源用对象表示。

4. ImageResource 字典

WebIDLdictionary ImageResource {
  required USVString src;
  DOMString sizes;
  DOMString type;
  DOMString label;
};

const image = {
  src: "path/to/image.ico",
  sizes: "16x16 32x32 64x64",
  type: "image/vnd.microsoft.icon",
};
some.api.doSomething(image);

5. 从 API 处理 ImageResource

从 API 处理 ImageResource 的步骤如下。算法接收一个 ImageResource input，返回一个 图片资源。

1. 令 base URL 为当前使用该字典时相关设置对象的API 基准 URL。
2. 新建一个 图片资源，命名为 image。
3. 将 image 的 src 设为 input.src 和 base URL 按 URL 解析 处理的结果。如果解析失败，抛出 TypeError。
4. 如果 input 的 sizes 成员存在：
   1. 将 image 的 sizes 设为 以 input.sizes 作为一个 sizes 属性、link 元素、并且其 rel 属性包含 token icon 来解析的结果。如果解析失败，抛出 TypeError。
5. 如果 input 的 type 成员不为空字符串且存在：
   1. 如果 type 不是图片 MIME 类型，抛出 TypeError。
   2. 将 image 的 type 设为 input.type。
6. 将 image 的 label 设为推导所得的可访问名称的结果。
7. 返回 image。

6. 从 JSON 处理图片资源

要从 JSON 处理图片资源，给定一个 JSON 对象 input 和一个 URL base。它返回一个 有序映射。

1. 如果 input 不是 对象 类型，返回失败。
2. 如果 input["src"] 不是 字符串 类型，返回失败。
3. 令 src 为以 input["src"] 及 base 作为基准 URL 进行 解析的结果。
4. 如果 src 为失败，返回失败。
5. 令 image 为一个新的 有序映射。
6. 将 image["src"] 设为 src。
7. 如果 input["sizes"] 类型为 字符串 且长度大于零：
   1. 将 sizes 设为以 input["sizes"] 作为 sizes 属性、link 元素，并且其 rel 属性包含 icon 解析的结果。
   2. 如果 sizes 为失败，返回失败。
   3. 将 image["sizes"] 设为 sizes。
8. 如果 input["type"] 是 字符串，且长度大于零：
   1. 令 mime 为 解析 input["type"] 的结果。
   2. 如果 mime 为失败，返回失败。
   3. 将 image["type"] 设为 mime 的精华值。
9. 将 image["label"] 设为推导可访问名称的结果。
10. 返回 image。

7. 获取图片资源

获取图片资源的步骤如下。该算法接受一个图片资源 image，以及一个可选的 Request request，返回一个 Response。

1. 如果 request 为 undefined：
   1. 将 request 设为一个新的 Request。
   2. 将 URL 设为 image 的 src。
   3. 将 Destination 设为 "image"。
   4. 将 Client 设为当前上下文对象的 相关设置对象。
2. 如果 request 的 Client 为 null，抛出 TypeError。
3. 使用 request 执行一次 fetch 并返回 Response。

8. 推导可访问名称

为 图片资源 resource 推导可访问名称的步骤如下。它返回一个字符串。

1. 如果 resource["label"] 是 字符串，返回 input["label"]。
2. 否则，如 image 提供了嵌入式可访问名称，则返回该嵌入式可访问名称。
3. 否则，如可用外部标签替代，则返回该外部标签。
4. 返回 ""。

9. 支持嵌入可访问名称的图形格式示例

某些图形格式支持将嵌入式可访问名称作为图片内容的一部分嵌入。示例包括：

• title 元素（在 SVG 内）。
• 光栅图片元数据（例如 tiff:ImageDescription, XMP:Description）。

10. 一致性

除明确标记为非规范性的章节外，本规范中的所有创作指南、图示、示例和说明都是非规范性的。规范其它内容均为规范性内容。

本文中的 MAY、MUST、RECOMMENDED 等关键字，均应按 BCP 14 [RFC2119] [RFC8174] 的规定解释，仅当其全部大写时才具有本意。