56.2K

<NuxtLink>

源码
Nuxt 提供了 <NuxtLink> 组件，用于处理应用程序中的各种链接。
<NuxtLink> 是 Vue Router 的 <RouterLink> 组件和 HTML 的 <a> 标签的直接替代品。它智能地判断链接是 内部 链接还是 外部 链接，并根据可用的优化（预获取、默认属性等）进行相应的渲染。

内部路由

在此示例中，我们使用 <NuxtLink> 组件链接到应用程序的另一个页面。

<template>
  <NuxtLink to="/about">关于页面</NuxtLink>
</template>

向动态路由传递参数

在此示例中，我们传递 id 参数来链接到路由 ~/pages/posts/[id].vue。

<template>
  <NuxtLink :to="{ name: 'posts-id', params: { id: 123 } }">
    帖子 123
  </NuxtLink>
</template>
请查看 Nuxt DevTools 中的页面面板，以查看路由名称和它可能接受的参数。

处理静态文件和跨应用链接

默认情况下，<NuxtLink> 对相对路由使用 Vue Router 的客户端导航。当链接到 /public 目录中的静态文件或链接到同一域上托管的另一个应用程序时，可能会导致意外的 404 错误，因为它们不是客户端路由的一部分。在这种情况下，可以使用 <NuxtLink> 的 external 属性以绕过 Vue Router 的内部路由机制。

external 属性明确表示链接是外部链接。<NuxtLink> 将该链接渲染为标准的 HTML <a> 标签。这确保了链接的行为正确，绕过 Vue Router 的逻辑并直接指向资源。

链接到静态文件

对于 /public 目录中的静态文件，例如 PDF 或图像，使用 external 属性以确保链接正确解析。

pages/index.vue
<template>
  <NuxtLink to="/example-report.pdf" external>
    下载报告
  </NuxtLink>
</template>

链接到跨应用 URL

当指向同一域上的不同应用程序时，使用 external 属性可确保正确的行为。

pages/index.vue
<template>
  <NuxtLink to="/another-app" external>
    前往另一个应用
  </NuxtLink>
</template>

使用 external 属性或依赖自动处理可确保正确的导航，避免意外的路由问题，并提高与静态资源或跨应用场景的兼容性。

外部路由

在此示例中，我们使用 <NuxtLink> 组件链接到一个网站。

app.vue
<template>
  <NuxtLink to="https://nuxtjs.org">
    Nuxt 网站
  </NuxtLink>
  <!-- <a href="https://nuxtjs.org" rel="noopener noreferrer">...</a> -->
</template>

rel 和 noRel 属性

对具有 target 属性或绝对链接（例如以 http://、https:// 或 // 开头的链接）应用默认的 rel 属性 noopener noreferrer。

  • noopener 解决了旧版浏览器中的 安全漏洞。
  • noreferrer 通过不向链接站点发送 Referer 头提高用户的隐私。

这些默认值不会对 SEO 产生负面影响，并被认为是 最佳实践。

当您需要覆盖此行为时，可以使用 rel 或 noRel 属性。

app.vue
<template>
  <NuxtLink to="https://twitter.com/nuxt_js">
    Nuxt Twitter
  </NuxtLink>
  <!-- <a href="https://twitter.com/nuxt_js" rel="noopener noreferrer">...</a> -->

  <NuxtLink to="https://discord.nuxtjs.org" rel="noopener">
    Nuxt Discord
  </NuxtLink>
  <!-- <a href="https://discord.nuxtjs.org" rel="noopener">...</a> -->

  <NuxtLink to="/about" target="_blank">关于页面</NuxtLink>
  <!-- <a href="/about" target="_blank" rel="noopener noreferrer">...</a> -->
</template>

noRel 属性可用于防止将默认的 rel 属性添加到绝对链接中。

app.vue
<template>
  <NuxtLink to="https://github.com/nuxt" no-rel>
    Nuxt GitHub
  </NuxtLink>
  <!-- <a href="https://github.com/nuxt">...</a> -->
</template>
noRel 和 rel 不能同时使用。rel 将被忽略。

预获取链接

Nuxt 自动包括智能预获取。这意味着它会检测到当链接可见时（默认情况下），无论是在视口中还是在滚动时，并预获取这些页面的 JavaScript，以便在用户单击链接时准备就绪。Nuxt 只在浏览器不忙时加载资源，并在连接离线或只有 2g 连接时跳过预获取。

pages/index.vue
<NuxtLink to="/about" no-prefetch>关于页面未预获取</NuxtLink>
<NuxtLink to="/about" :prefetch="false">关于页面未预获取</NuxtLink>

自定义预获取触发器

在 v3.13.0 之后，我们现在支持 <NuxtLink> 的自定义预获取触发器。您可以使用 prefetchOn 属性控制何时预获取链接。

<template>
  <NuxtLink prefetch-on="visibility">
    当它变得可见时将进行预获取（默认）
  </NuxtLink>

  <NuxtLink prefetch-on="interaction">
    当鼠标悬停或获得焦点时将进行预获取
  </NuxtLink>
</template>
  • visibility：当链接在视口中变得可见时进行预获取。使用 Intersection Observer API 监控元素与视口的交集。当元素滚动到视图中时触发预获取。
  • interaction：当链接悬停或获得焦点时进行预获取。此方法监听 pointerenter 和 focus 事件，在用户表示有意进行交互时主动预获取资源。

您还可以使用对象来配置 prefetchOn：

<template>
  <NuxtLink :prefetch-on="{ interaction: true }">
    当悬停或获得焦点时将进行预获取
  </NuxtLink>
</template>

您可能不希望同时启用两者！

<template>
  <NuxtLink :prefetch-on="{ visibility: true, interaction: true }">
    当悬停/聚焦或变得可见时将进行预获取
  </NuxtLink>
</template>

此配置将观察元素何时进入视口，并监听 pointerenter 和 focus 事件。这可能导致不必要的资源使用或冗余预获取，因为两种触发器在不同条件下可以预获取相同的资源。

启用跨源预获取

要启用跨源预取，您可以在您的 nuxt.config 中设置 crossOriginPrefetch 选项。这将使用 推测规则 API 启用跨源预取。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    crossOriginPrefetch: true,
  },
})

全局禁用预获取

也可以为您的应用全局启用/禁用所有链接的预获取。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        prefetch: false,
      },
    },
  },
})

属性

RouterLink

在未使用 external 时，<NuxtLink> 支持所有 Vue Router 的 RouterLink 属性

NuxtLink

  • href：to 的别名。如果与 to 一起使用，将忽略 href
  • noRel：如果设置为 true，则不会向外部链接添加 rel 属性
  • external：强制链接渲染为 <a> 标签，而不是 Vue Router 的 RouterLink。
  • prefetch：启用时将预获取在视口中的链接的中间件、布局和有效负载（使用 payloadExtraction 时）。由实验性 crossOriginPrefetch 配置使用。
  • prefetchOn：允许自定义控制何时预获取链接。可选选项有 interaction 和 visibility（默认）。您也可以传递一个对象以获得完全控制，例如：{ interaction: true, visibility: true }。此属性仅在启用 prefetch（默认）且未设置 noPrefetch 时使用。
  • noPrefetch：禁用预获取。
  • prefetchedClass：应用于已预获取链接的类。

Anchor

  • target：应用于链接的 target 属性值
  • rel：应用于链接的 rel 属性值。对于外部链接，默认为 "noopener noreferrer"。
默认值可以被覆盖，如果您想更改它们，请参见 覆盖默认值。

覆盖默认值

在 Nuxt 配置中

您可以在 nuxt.config 中覆盖一些 <NuxtLink> 默认值。

这些选项可能在未来移动到其他地方，例如 app.config 或 app/ 目录中。
nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        // 默认值
        componentName: 'NuxtLink',
        externalRelAttribute: 'noopener noreferrer',
        activeClass: 'router-link-active',
        exactActiveClass: 'router-link-exact-active',
        prefetchedClass: undefined, // 可以是任何有效的字符串类名
        trailingSlash: undefined, // 可以是 'append' 或 'remove'
        prefetch: true,
        prefetchOn: { visibility: true } 
      }
    }
  }
})

自定义链接组件

您可以通过使用 defineNuxtLink 创建自己的链接组件来覆盖 <NuxtLink> 默认值。

components/MyNuxtLink.ts
export default defineNuxtLink({
  componentName: 'MyNuxtLink',
  /* 请参阅下面的签名以获取更多信息 */
})

然后，您可以像往常一样使用 <MyNuxtLink /> 组件，并使用您的新默认值。

defineNuxtLink 签名

interface NuxtLinkOptions {
  componentName?: string;
  externalRelAttribute?: string;
  activeClass?: string;
  exactActiveClass?: string;
  trailingSlash?: 'append' | 'remove'
  prefetch?: boolean
  prefetchedClass?: string
  prefetchOn?: Partial<{
    visibility: boolean
    interaction: boolean
  }>
}
function defineNuxtLink(options: NuxtLinkOptions): Component {}
  • componentName: 组件的名称。默认为 NuxtLink。
  • externalRelAttribute: 应用于外部链接的默认 rel 属性值。默认为 "noopener noreferrer"。将其设置为 "" 以禁用
  • activeClass: 应用于活动链接的默认类。与 Vue Router 的 linkActiveClass 选项 的工作原理相同。默认为 Vue Router 的默认值（"router-link-active"）
  • exactActiveClass: 应用于精确活动链接的默认类。与 Vue Router 的 linkExactActiveClass 选项 的工作原理相同。默认为 Vue Router 的默认值（"router-link-exact-active"）
  • trailingSlash: 一个选项，用于在 href 中添加或删除尾随斜杠。如果未设置或不匹配有效的值 append 或 remove，则将被忽略。
  • prefetch: 是否默认预获取链接。
  • prefetchOn: 以细粒度控制默认情况下应用哪些预获取策略。
  • prefetchedClass: 应用于已预获取链接的默认类。
Read and edit a live example in Docs > Examples > Routing > Pages.

<NuxtLayout>

Nuxt 提供了 <NuxtLayout> 组件来在页面和错误页面上显示布局。

<NuxtLoadingIndicator>

显示页面导航之间的进度条。