知海

<link>

ReactAPI 参考：React DOM

项目名称: zh-hansreactdev-main
源文件路径: src/content/reference/react-dom/components/link.md
目标标题:
所属分类: API 参考：React DOM

浏览器内置的 <link> 组件 允许你使用外部资源，例如样式表，或通过链接元数据注释文档。

js 复制代码 
<link rel="icon" href="favicon.ico" />

参考 {/reference/}

<link> {/link/}

渲染 浏览器内置的 <link> 组件 以链接外部资源，例如样式表、字体和图标，或者通过链接元数据在文档中添加注释。你可以在任何组件中渲染 <link>，React 在大多数情况下会将相应的 DOM 元素放置在文档的 <head> 中。

js 复制代码 
<link rel="icon" href="favicon.ico" />

请参阅下方更多示例。

属性 {/props/}

<link> 支持所有 常见元素属性。

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

  • precedence：字符串，告诉 React 在文档 <head> 中，此 <link> DOM 节点应排在何处。这决定了哪个样式表可以覆盖其他样式表。React 将其首先发现的 precedence 值推断为“较低”，而将后来发现的 precedence 值推断为“较高”。许多样式系统仅使用单个 precedence 值即可正常工作，这是因为样式规则是原子性的。具有相同优先级的样式表会一起处理，无论是 <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 策略。当 as 设置为 "fetch" 时，此属性是必需的。
  • referrerPolicy：字符串，指定获取时发送的 referer 请求头。可能的值包括 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 提供了更精细的控制。

特殊的渲染行为 {/special-rendering-behavior/}

无论 <link> 组件在 React 树中的哪个位置被渲染，React 都会始终将其对应的 DOM 元素放置在文档的 <head> 中。<head> 是 <link> 在 DOM 中唯一有效的位置，但如果表示特定页面的组件可以自行渲染 <link>，这种做法既方便又保持了可组合性。

但存在一些例外情况：

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

链接到样式表的特殊行为 {/special-behavior-for-stylesheets/}

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

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

但存在两个例外情况：

  • 如果链接没有 precedence 属性，则没有特殊行为。因为文档中样式表的顺序很重要，React 需要知道如何将此样式表与其他样式表排序，这可以通过 precedence 属性指定。
  • 如果提供了任何 onLoad、onError 或 disabled 属性，则没有特殊行为，因为这些属性表明你是在组件内部手动管理样式表的加载。

这种特殊处理伴随着两个注意事项：

  • 在链接渲染后，React 将忽略属性的更改（在开发环境中，React 会对这种情况发出警告）。
  • 即使渲染它的组件已被卸载，React 也可能将链接保留在 DOM 中。

用法 {/usage/}

你可以使用链接来添加与文档相关的资源，例如图标、规范 URL 或 pingback。无论其在 React 树中的渲染位置如何，React 都会将这些元数据放置在文档的 <head> 中。

js src/App.js active 复制代码 
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>我的博客</h1>
      <p>……</p>
    </ShowRenderedHTML>
  );
}

链接到样式表 {/linking-to-a-stylesheet/}

如果一个组件依赖某个样式表才能正确显示，你可以在该组件内部渲染指向此样式表的链接。当样式表加载时，组件会 挂起。因此，你必须提供 precedence 属性，该属性告诉 React 将此样式表放置在其他样式表的何处——具有较高优先级的样式表可以覆盖较低优先级的样式表。

当你想使用样式表时，调用 [preinit](/reference/react-dom/preinit) 函数可能会更有益。调用此函数可以让浏览器比仅渲染 `` 组件更早地开始获取样式表，例如，通过发送 [HTTP 103 Early Hints 响应](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Status/103)。
js src/App.js active 复制代码 
import ShowRenderedHTML from './ShowRenderedHTML.js';

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

控制样式表优先级 {/controlling-stylesheet-precedence/}

样式表可能会相互冲突，当冲突发生时，浏览器会选择文档中排在后面的样式表。React 允许你通过 precedence 属性控制样式表的顺序。在此示例中，三个组件渲染不同的样式表，具有相同优先级的组件在 <head> 中会被分组在一起。

js src/App.js active 复制代码 
import ShowRenderedHTML from './ShowRenderedHTML.js';

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

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

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

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

请注意，precedence 值本身是任意的，其命名由你决定。React 会将最先遇到的 precedence 值推断为“较低”优先级，而将后续遇到的 precedence 值推断为“较高”优先级。

对样式表渲染去重 {/deduplicated-stylesheet-rendering/}

如果多个组件渲染相同的样式表，React 只会在文档头部放置单个 <link>。

js src/App.js active 复制代码 
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" />;
}

使用链接为文档中的特定项目添加注释 {/annotating-specific-items-within-the-document-with-links/}

你可以使用带有 itemProp 属性的 <link> 组件，为文档中的特定项目添加指向相关资源的注释。在这种情况下，React 不会将这些注释放置在文档的 <head> 中，而是像任何其他 React 组件一样放置它们。

js 复制代码 
<section itemScope>
  <h3>为特定项目添加注释</h3>
  <link itemProp="author" href="http://example.com/" />
  <p>...</p>
</section>

帮助我们改进文档

发现翻译问题或内容错误？请告诉我们。