<NuxtLink>

Nuxt 提供 <NuxtLink> 组件来处理应用内的各种链接。

<NuxtLink> 是 Vue Router 的 <RouterLink> 组件和 HTML 的 <a> 标签的直接替代品。它会智能判断链接是内部还是外部，并根据可用的优化（预取、默认属性等）相应地渲染。

Internal Routing

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

<template>
  <NuxtLink to="/about">About page</NuxtLink>
</template>

<!-- (Vue Router & Smart Prefetching) -->
<a href="/about">About page</a>

Passing Params to Dynamic Routes

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

<template>
  <NuxtLink :to="{ name: 'posts-id', params: { id: 123 } }">
    Post 123
  </NuxtLink>
</template>

<a href="/posts/123">Post 123</a>

查看 Nuxt DevTools 中的 Pages 面板以查看路由名称及其可能接受的参数。

当你向 to 属性传入一个对象时，<NuxtLink> 会继承 Vue Router 对查询参数的处理。键和值会被自动编码，因此你不需要手动调用 encodeURI 或 encodeURIComponent。

Handling Static File and Cross-App Links

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

external 属性显式表明该链接是外部链接。<NuxtLink> 将把链接渲染为标准的 HTML <a> 标签。这可以确保链接正常工作，绕过 Vue Router 的逻辑并直接指向资源。

Linking to Static Files

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

app/pages/index.vue

<template>
  <NuxtLink
    to="/example-report.pdf"
    external
  >
    Download Report
  </NuxtLink>
</template>

Linking to a Cross-App URL

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

app/pages/index.vue

<template>
  <NuxtLink
    to="/another-app"
    external
  >
    Go to Another App
  </NuxtLink>
</template>

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

External Routing

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

app/app.vue

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

`rel` and `noRel` Attributes

默认情况下，带有 target 属性或绝对链接（例如以 http://、https:// 或 // 开头的链接）会自动添加 rel="noopener noreferrer" 属性。

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

这些默认设置对 SEO 没有负面影响，并被认为是最佳实践。

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

app/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"
  >About page</NuxtLink>
  <!-- <a href="/about" target="_blank" rel="noopener noreferrer">...</a> -->
</template>

noRel 属性可用于防止在绝对链接上添加默认的 rel 属性。

app/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 将被忽略。

Prefetch Links

Nuxt 自动包含智能预取。这意味着它会检测链接何时可见（默认情况下），无论是在视口中还是在滚动时，并预取这些页面的 JavaScript，使得在用户点击链接时页面已准备好。Nuxt 仅在浏览器空闲时加载资源，并在连接离线或仅有 2g 网络时跳过预取。

app/pages/index.vue

<NuxtLink to="/about" no-prefetch>
About page not pre-fetched
</NuxtLink>

<NuxtLink to="/about" :prefetch="false">
About page not pre-fetched
</NuxtLink>

Custom Prefetch Triggers

从 v3.13.0 起，我们现在支持为 <NuxtLink> 使用自定义预取触发器。你可以使用 prefetchOn 属性来控制何时预取链接。

<template>
  <NuxtLink prefetch-on="visibility">
    This will prefetch when it becomes visible (default)
  </NuxtLink>

  <NuxtLink prefetch-on="interaction">
    This will prefetch when hovered or when it gains focus
  </NuxtLink>
</template>

visibility：当链接在视口中变为可见时预取。使用 Intersection Observer API 监控元素与视口的交叉情况。预取会在元素被滚动到视口中时触发。
interaction：当链接被 hover 或获得焦点时预取。此方法监听 pointerenter 和 focus 事件，在用户表示有交互意图时主动预取资源。

你也可以使用对象来配置 prefetchOn：

<template>
  <NuxtLink :prefetch-on="{ interaction: true }">
    This will prefetch when hovered or when it gains focus
  </NuxtLink>
</template>

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

<template>
  <NuxtLink :prefetch-on="{ visibility: true, interaction: true }">
    This will prefetch when hovered/focus - or when it becomes visible
  </NuxtLink>
</template>

此配置会同时观察元素何时进入视口，并监听 pointerenter 与 focus 事件。这可能导致不必要的资源使用或重复预取，因为两者触发条件可能会在不同情况下对同一资源进行预取。

Enable Cross-origin Prefetch

要启用跨域预取，可以在 nuxt.config 中设置 crossOriginPrefetch 选项。这将使用 Speculation Rules API 启用跨域预取。

nuxt.config.ts

export default defineNuxtConfig({
  experimental: {
    crossOriginPrefetch: true,
  },
})

Disable prefetch globally

你也可以为整个应用全局启用/禁用所有链接的预取。

nuxt.config.ts

export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        prefetch: false,
      },
    },
  },
})

Props

RouterLink

当未使用 external 时，<NuxtLink> 支持所有 Vue Router 的 RouterLink props

to：任意 URL 或 Vue Router 的路由位置对象
custom：是否应该让 <NuxtLink> 将其内容包裹在 <a> 元素中。它允许完全控制链接的渲染方式以及点击时的导航行为。与 Vue Router 的 custom 属性工作方式相同
exactActiveClass：应用于精确激活链接的类。与 Vue Router 的 exactActiveClass 属性在内部链接上的行为相同。默认为 Vue Router 的默认值（"router-link-exact-active"）
activeClass：应用于激活链接的类。与 Vue Router 的 activeClass 属性在内部链接上的行为相同。默认为 Vue Router 的默认值（"router-link-active"）
replace：在内部链接上与 Vue Router 的 replace 属性行为相同
ariaCurrentValue：在精确激活链接上应用的 aria-current 属性值。与 Vue Router 的 ariaCurrentValue 属性在内部链接上的行为相同

NuxtLink

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

Anchor

target：应用于链接的 target 属性值
rel：应用于链接的 rel 属性值。外部链接默认值为 "noopener noreferrer"

默认值可以被覆盖，如果你想更改它们，请参阅覆盖默认值。

Overwriting Defaults

In Nuxt Config

你可以在 nuxt.config 中覆盖某些 <NuxtLink> 的默认值

这些选项将来可能会被移到其他位置，例如 app.config 或 app/ 目录中。

nuxt.config.ts

export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        // default values
        componentName: 'NuxtLink',
        externalRelAttribute: 'noopener noreferrer',
        activeClass: 'router-link-active',
        exactActiveClass: 'router-link-exact-active',
        prefetchedClass: undefined, // can be any valid string class name
        trailingSlash: undefined, // can be 'append' or 'remove'
        prefetch: true,
        prefetchOn: { visibility: true },
      },
    },
  },
})

Custom Link Component

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

app/components/MyNuxtLink.ts

export default defineNuxtLink({
  componentName: 'MyNuxtLink',
  /* see signature below for more */
})

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

`defineNuxtLink` Signature

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 > 4 X > Examples > Routing > Pages.

Was this helpful?

报告问题或者在 GitHub 上编辑此页面

Nuxt provides the <NuxtLayout> component to show layouts on pages and error pages.

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