API 参考
组件

<link> - This feature is available in the latest Canary

Canary 版本

React 对 <link> 的扩展目前仅在 React 的 Canary 和实验通道中可用。在 React 的稳定版本中，<link> 仅作为 内置浏览器 HTML 组件 工作。在此处详细了解 React 的发布通道。

内置浏览器 <link> 组件 允许您使用外部资源（如样式表）或使用链接元数据注释文档。

<link rel="icon" href="favicon.ico" />

参考

<link>

要链接到外部资源，例如样式表、字体和图标，或者使用链接元数据注释文档，请渲染 内置浏览器 <link> 组件。您可以从任何组件渲染 <link>，并且在 大多数情况下，React 会将相应的 DOM 元素放置在文档头部。

<link rel="icon" href="favicon.ico" />

请参阅下面的更多示例。

属性

<link> 支持所有 通用元素属性。

当 rel="stylesheet" 时，以下属性适用

  • precedence：字符串。告诉 React 在文档 <head> 中相对于其他节点的 <link> DOM 节点的排名，这决定了哪个样式表可以覆盖另一个。React 会推断它先发现的优先级值“较低”，而它后发现的优先级值“较高”。许多样式系统可以使用单个优先级值正常工作，因为样式规则是原子的。具有相同优先级的样式表放在一起，无论它们是 <link> 还是内联 <style> 标记，或者使用 preinit 函数加载。
  • media：字符串。将样式表限制为特定的 媒体查询。
  • title：字符串。指定 备用样式表 的名称。

当 rel="stylesheet" 时，以下属性适用，但会禁用 React 对样式表的特殊处理

  • disabled：布尔值。禁用样式表。
  • onError：函数。当样式表加载失败时调用。
  • onLoad：函数。当样式表完成加载时调用。

当 rel="preload" 或 rel="modulepreload" 时，以下属性适用

  • as：字符串。资源类型。其可能的值为 audio、document、embed、fetch、font、image、object、script、style、track、video、worker。
  • imageSrcSet：字符串。仅当 as="image" 时适用。指定图像的来源集。
  • imageSizes：字符串。仅当 as="image" 时适用。指定图像的尺寸。

当 rel="icon" 或 rel="apple-touch-icon" 时，以下属性适用

以下属性适用于所有情况

  • href：字符串。链接资源的 URL。
  • crossOrigin：字符串。要使用的CORS 策略。其可能的值为 anonymous 和 use-credentials。当 as 设置为 "fetch" 时，此属性是必需的。
  • referrerPolicy：字符串。获取资源时发送的Referrer 标头。其可能的值为 no-referrer-when-downgrade（默认值）、no-referrer、origin、origin-when-cross-origin 和 unsafe-url。
  • fetchPriority：字符串。建议获取资源的相对优先级。可能的值为 auto（默认值）、high 和 low。
  • hrefLang：字符串。链接资源的语言。
  • integrity：字符串。资源的加密哈希值，用于验证其真实性。
  • type：字符串。链接资源的 MIME 类型。

**不建议**与 React 一起使用的属性

  • blocking：字符串。如果设置为 "render"，则指示浏览器在样式表加载完成之前不要渲染页面。React 使用 Suspense 提供更细粒度的控制。

特殊渲染行为

无论 <link> 组件在 React 树中的哪个位置渲染，React 始终会将其对应的 DOM 元素放置在文档的 <head> 中。<head> 是 DOM 中唯一可以存在 <link> 的有效位置，但如果表示特定页面的组件可以自己渲染 <link> 组件，则这样做会很方便并且保持事物的可组合性。

对此有一些例外情况

  • 如果 <link> 具有 rel="stylesheet" 属性，则它还必须具有 precedence 属性才能获得这种特殊行为。这是因为文档中样式表的顺序很重要，因此 React 需要知道如何相对于其他样式表对该样式表进行排序，您可以使用 precedence 属性指定。如果省略 precedence 属性，则不会有特殊行为。
  • 如果 <link> 具有 itemProp 属性，则不会有特殊行为，因为在这种情况下，它不适用于文档，而是表示有关页面特定部分的元数据。
  • 如果 <link> 具有 onLoad 或 onError 属性，则不会有特殊行为，因为在这种情况下，您是在 React 组件中手动管理链接资源的加载。

样式表的特殊行为

此外，如果 `<link>` 是指向样式表的（即，其属性中包含 `rel="stylesheet"`），则 React 会以以下方式对其进行特殊处理：

  • 渲染 `<link>` 的组件将在样式表加载时 暂停。
  • 如果多个组件渲染指向同一样式表的链接，React 将对其进行去重，并且只在 DOM 中放置一个链接。如果两个链接具有相同的 `href` 属性，则认为它们是相同的。

这种特殊行为有两个例外情况：

  • 如果链接没有 `precedence` 属性，则不会有特殊行为，因为文档中样式表的顺序很重要，因此 React 需要知道如何相对于其他样式表对此样式表进行排序，您可以使用 `precedence` 属性指定。
  • 如果您提供了 `onLoad`、`onError` 或 `disabled` 属性中的任何一个，则不会有特殊行为，因为这些属性表明您正在组件中手动管理样式表的加载。

这种特殊处理方式有两点需要注意：

  • 链接渲染后，React 将忽略对属性的更改。（如果发生这种情况，React 将在开发过程中发出警告。）
  • 即使渲染链接的组件已卸载，React 仍可能将链接保留在 DOM 中。

用法

链接到相关资源

您可以使用指向相关资源（如图标、规范 URL 或 pingback）的链接来注释文档。React 将把这些元数据放在文档的 `<head>` 中，而不管它在 React 树中的哪个位置渲染。

import ShowRenderedHTML from './ShowRenderedHTML.js';

export default function BlogPage() {
  return (
    <ShowRenderedHTML>
      <link rel="icon" href="favicon.ico" />
      <link rel="pingback" href="http://www.example.com/xmlrpc.php" />
      <h1>My Blog</h1>
      <p>...</p>
    </ShowRenderedHTML>
  );
}

链接到样式表

如果某个组件依赖于某个样式表才能正确显示，则可以在该组件中渲染指向该样式表的链接。您的组件将在样式表加载时 暂停。您必须提供 `precedence` 属性，该属性告诉 React 将此样式表放置在相对于其他样式表的哪个位置 — 优先级较高的样式表可以覆盖优先级较低的样式表。

注意

当您要使用样式表时，调用 preinit 函数可能会有所帮助。调用此函数可以让浏览器比仅渲染 `<link>` 组件更早地开始获取样式表，例如，通过发送 HTTP Early Hints 响应。

import ShowRenderedHTML from './ShowRenderedHTML.js';

export default function SiteMapPage() {
  return (
    <ShowRenderedHTML>
      <link rel="stylesheet" href="sitemap.css" precedence="medium" />
      <p>...</p>
    </ShowRenderedHTML>
  );
}

控制样式表优先级

样式表可能会相互冲突，当它们发生冲突时，浏览器会使用文档中较晚出现的样式表。React 允许您使用 `precedence` 属性控制样式表的顺序。在此示例中，两个组件渲染样式表，优先级较高的样式表在文档中较晚出现，即使渲染它的组件较早出现。

import ShowRenderedHTML from './ShowRenderedHTML.js';

export default function HomePage() {
  return (
    <ShowRenderedHTML>
      <FirstComponent />
      <SecondComponent />
      ...
    </ShowRenderedHTML>
  );
}

function FirstComponent() {
  return <link rel="stylesheet" href="first.css" precedence="high" />;
}

function SecondComponent() {
  return <link rel="stylesheet" href="second.css" precedence="low" />;
}

去重样式表渲染

如果您从多个组件渲染同一样式表，React 将只在文档头部放置一个 `<link>`。

import ShowRenderedHTML from './ShowRenderedHTML.js';

export default function HomePage() {
  return (
    <ShowRenderedHTML>
      <Component />
      <Component />
      ...
    </ShowRenderedHTML>
  );
}

function Component() {
  return <link rel="stylesheet" href="styles.css" precedence="medium" />;
}

使用链接注释文档中的特定项目

您可以将 `<link>` 组件与 `itemProp` 属性一起使用，以使用指向相关资源的链接来注释文档中的特定项目。在这种情况下，React *不会*将这些注释放在文档的 `<head>` 中，而是像任何其他 React 组件一样放置它们。

<section itemScope>
  <h3>Annotating specific items</h3>
  <link itemProp="author" href="http://example.com/" />
  <p>...</p>
</section>
上一页<textarea>
下一页<meta>