<link>

Canary

React 对 <link> 的扩展目前仅在 React 的 canary 和实验通道中可用。在 React 的稳定版本中，<link> 仅作为内置浏览器 HTML 组件工作。了解有关 React 的发布渠道在这里的更多信息。

¥React’s extensions to <link> are currently only available in React’s canary and experimental channels. In stable releases of React <link> works only as a built-in browser HTML component. Learn more about React’s release channels here.

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

¥The built-in browser <link> component lets you use external resources such as stylesheets or annotate the document with link metadata.

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

参考

¥Reference

`<link>`

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

¥To link to external resources such as stylesheets, fonts, and icons, or to annotate the document with link metadata, render the built-in browser <link> component. You can render <link> from any component and React will in most cases place the corresponding DOM element in the document head.

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

请参阅下面的更多示例。

¥See more examples below.

属性

¥Props

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

¥<link> supports all common element props.

rel：一个字符串，必需。指定与资源的关系。从其他链接反应以不同方式对待 rel="stylesheet" 的链接。

¥rel: a string, required. Specifies the relationship to the resource. React treats links with rel="stylesheet" differently from other links.

这些属性在 rel="stylesheet" 时适用：

¥These props apply when rel="stylesheet":

precedence：一个字符串。告诉 React 相对于文档 <head> 中的其他 DOM 节点对 <link> DOM 节点进行排名，这决定了哪个样式表可以覆盖另一个样式表。React 将推断它首先发现的优先级值为 “lower”，而它稍后发现的优先级值为 “higher”。由于样式规则是原子的，因此许多样式系统可以使用单个优先级值正常工作。具有相同优先级的样式表可以组合在一起，无论它们是 <link> 还是内联 <style> 标签，还是使用 preinit 函数加载。

¥precedence: a string. Tells React where to rank the <link> DOM node relative to others in the document <head>, which determines which stylesheet can override the other. React will infer that precedence values it discovers first are “lower” and precedence values it discovers later are “higher”. Many style systems can work fine using a single precedence value because style rules are atomic. Stylesheets with the same precedence go together whether they are <link> or inline <style> tags or loaded using preinit functions.
media：一个字符串。将样式表限制为某个媒体查询。

¥media: a string. Restricts the stylesheet to a certain media query.
title：一个字符串。指定替代样式表的名称。

¥title: a string. Specifies the name of an alternative stylesheet.

这些属性在 rel="stylesheet" 时适用，但禁用 React 的样式表的特殊处理：

¥These props apply when rel="stylesheet" but disable React’s special treatment of stylesheets:

disabled：一个布尔值。禁用样式表。

¥disabled: a boolean. Disables the stylesheet.
onError：一个函数。当样式表加载失败时调用。

¥onError: a function. Called when the stylesheet fails to load.
onLoad：一个函数。当样式表加载完成时调用。

¥onLoad: a function. Called when the stylesheet finishes being loaded.

这些属性在 rel="preload" 或 rel="modulepreload" 时适用：

¥These props apply when rel="preload" or rel="modulepreload":

as：一个字符串。资源的类型。其可能值为 audio、document、embed、fetch、font、image、object、script、style、track、video、worker。

¥as: a string. The type of resource. Its possible values are audio, document, embed, fetch, font, image, object, script, style, track, video, worker.
imageSrcSet：一个字符串。仅适用于 as="image"。指定图片的源集。

¥imageSrcSet: a string. Applicable only when as="image". Specifies the source set of the image.
imageSizes：一个字符串。仅适用于 as="image"。指定图片的尺寸。

¥imageSizes: a string. Applicable only when as="image". Specifies the sizes of the image.

这些属性在 rel="icon" 或 rel="apple-touch-icon" 时适用：

¥These props apply when rel="icon" or rel="apple-touch-icon":

sizes：一个字符串。图标的大小.

¥sizes: a string. The sizes of the icon.

这些属性适用于所有情况：

¥These props apply in all cases:

href：一个字符串。链接资源的 URL。

¥href: a string. The URL of the linked resource.
crossOrigin：一个字符串。要使用的 CORS 政策。它的可能值为 anonymous 和 use-credentials。当 as 设置为 "fetch" 时需要。

¥crossOrigin: a string. The CORS policy to use. Its possible values are anonymous and use-credentials. It is required when as is set to "fetch".
referrerPolicy：一个字符串。获取时发送的推荐人标头。其可能的值为 no-referrer-when-downgrade（默认值）、no-referrer、origin、origin-when-cross-origin 和 unsafe-url。

¥referrerPolicy: a string. The Referrer header to send when fetching. Its possible values are no-referrer-when-downgrade (the default), no-referrer, origin, origin-when-cross-origin, and unsafe-url.
fetchPriority：一个字符串。建议获取资源的相对优先级。可能的值为 auto（默认值）、high 和 low。

¥fetchPriority: a string. Suggests a relative priority for fetching the resource. The possible values are auto (the default), high, and low.
hrefLang：一个字符串。链接资源的语言。

¥hrefLang: a string. The language of the linked resource.
integrity：一个字符串。资源的加密哈希值，为验证其真实性。

¥integrity: a string. A cryptographic hash of the resource, to verify its authenticity.
type：一个字符串。链接资源的 MIME 类型。

¥type: a string. The MIME type of the linked resource.

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

¥Props that are not recommended for use with React:

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

¥blocking: a string. If set to "render", instructs the browser not to render the page until the stylesheet is loaded. React provides more fine-grained control using Suspense.

特殊渲染行为

¥Special rendering behavior

React 总是将与 <link> 组件对应的 DOM 元素放置在文档的 <head> 中，无论它在 React 树中的哪个位置渲染。<head> 是 <link> 在 DOM 中存在的唯一有效位置，但如果表示特定页面的组件可以自行渲染 <link> 组件，那么它会很方便并且保持可组合性。

¥React will always place the DOM element corresponding to the <link> component within the document’s <head>, regardless of where in the React tree it is rendered. The <head> is the only valid place for <link> to exist within the DOM, yet it’s convenient and keeps things composable if a component representing a specific page can render <link> components itself.

但也有一些例外：

¥There are a few exceptions to this:

如果 <link> 有 rel="stylesheet" 属性，那么它还必须有 precedence 属性才能获得这种特殊行为。这是因为文档中样式表的顺序很重要，因此 React 需要知道如何相对于其他样式表排序此样式表，你可以使用 precedence 属性指定该样式表。如果省略 precedence 属性，则没有特殊行为。

¥If the <link> has a rel="stylesheet" prop, then it has to also have a precedence prop to get this special behavior. This is because the order of stylesheets within the document is significant, so React needs to know how to order this stylesheet relative to others, which you specify using the precedence prop. If the precedence prop is omitted, there is no special behavior.
如果 <link> 有 itemProp 属性，则没有特殊行为，因为在这种情况下，它不适用于文档，而是表示有关页面特定部分的元数据。

¥If the <link> has an itemProp prop, there is no special behavior, because in this case it doesn’t apply to the document but instead represents metadata about a specific part of the page.
如果 <link> 有 onLoad 或 onError 属性，因为在这种情况下，你将在 React 组件中手动管理链接资源的加载。

¥If the <link> has an onLoad or onError prop, because in that case you are managing the loading of the linked resource manually within your React component.

样式表的特殊行为

¥Special behavior for stylesheets

另外，如果 <link> 是样式表（即它的属性中有 rel="stylesheet"），React 会通过以下方式特殊对待它：

¥In addition, if the <link> is to a stylesheet (namely, it has rel="stylesheet" in its props), React treats it specially in the following ways:

加载样式表时，渲染 <link> 的组件将渲染 suspend。

¥The component that renders <link> will suspend while the stylesheet is loading.
如果多个组件渲染到同一个样式表的链接，React 会删除它们的重复项，并且只将单个链接放入 DOM 中。如果两个链接具有相同的 href prop，则认为它们是相同的。

¥If multiple components render links to the same stylesheet, React will de-duplicate them and only put a single link into the DOM. Two links are considered the same if they have the same href prop.

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

¥There are two exception to this special behavior:

如果链接没有 precedence 属性，则没有特殊行为，因为文档中样式表的顺序很重要，因此 React 需要知道如何相对于你使用 precedence 属性指定的其他样式表排序此样式表。

¥If the link doesn’t have a precedence prop, there is no special behavior, because the order of stylesheets within the document is significant, so React needs to know how to order this stylesheet relative to others, which you specify using the precedence prop.
如果你提供任何 onLoad、onError 或 disabled 属性，则不会有特殊行为，因为这些属性表明你正在组件内手动管理样式表的加载。

¥If you supply any of the onLoad, onError, or disabled props, there is no special behavior, because these props indicate that you are managing the loading of the stylesheet manually within your component.

这种特殊处理有两个注意事项：

¥This special treatment comes with two caveats:

链接渲染后，React 将忽略对属性的更改。（如果发生这种情况，React 将在开发中发出警告。）

¥React will ignore changes to props after the link has been rendered. (React will issue a warning in development if this happens.)
即使渲染链接的组件已被卸载，React 也可能会将链接保留在 DOM 中。

¥React may leave the link in the DOM even after the component that rendered it has been unmounted.

用法

¥Usage

¥Linking to related resources

你可以使用相关资源的链接对文档进行注释，例如图标、规范 URL 或 pingback。React 会将此元数据放置在文档 <head> 中，无论它在 React 树中的哪个位置渲染。

¥You can annotate the document with links to related resources such as an icon, canonical URL, or pingback. React will place this metadata within the document <head> regardless of where in the React tree it is rendered.

复刻

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>
  );
}

链接到样式表

¥Linking to a stylesheet

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

¥If a component depends on a certain stylesheet in order to be displayed correctly, you can render a link to that stylesheet within the component. Your component will suspend while the stylesheet is loading. You must supply the precedence prop, which tells React where to place this stylesheet relative to others — stylesheets with higher precedence can override those with lower precedence.

注意

当你想要使用样式表时，调用 preinit 函数会很有帮助。调用此函数可能允许浏览器比仅渲染 <link> 组件更早地开始获取样式表，例如通过发送 HTTP 早期提示响应。

¥When you want to use a stylesheet, it can be beneficial to call the preinit function. Calling this function may allow the browser to start fetching the stylesheet earlier than if you just render a <link> component, for example by sending an HTTP Early Hints response.

复刻

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 属性控制样式表的顺序。在此示例中，两个组件渲染样式表，优先级较高的组件在文档中显示得较晚，尽管渲染该样式表的组件较早出现。

¥Stylesheets can conflict with each other, and when they do, the browser goes with the one that comes later in the document. React lets you control the order of stylesheets with the precedence prop. In this example, two components render stylesheets, and the one with the higher precedence goes later in the document even though the component that renders it comes earlier.

复刻

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" />;
}

去重样式表渲染

¥Deduplicated stylesheet rendering

如果你从多个组件渲染相同的样式表，React 将仅在文档头中放置一个 <link>。

¥If you render the same stylesheet from multiple components, React will place only a single <link> in the document head.

复刻

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

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

¥You can use the <link> component with the itemProp prop to annotate specific items within the document with links to related resources. In this case, React will not place these annotations within the document <head> but will place them like any other React component.

<section itemScope>
  <h3>Annotating specific items</h3>
  <link itemProp="author" href="http://example.com/" />
  <p>...</p>
</section>

上一章<textarea>

下一章<meta>

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

Canary

参考

<link>

属性

特殊渲染行为

样式表的特殊行为

用法

链接到相关资源

链接到样式表

注意

控制样式表优先级

去重样式表渲染

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

<link>

`<link>`