<NuxtLink>

Nuxt 提供了 <NuxtLink> 组件来处理您应用程序中的各种链接。

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

内部路由

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

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

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

将参数传递给动态路由

在此示例中，我们将 `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`。

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

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

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

链接到静态文件

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

app/pages/index.vue

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

链接到跨应用 URL

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

app/pages/index.vue

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

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

外部路由

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

app/app.vue

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

`rel` 和 `noRel` 属性

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

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

预加载链接

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>

自定义预加载触发器

在 `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`: 当链接被悬停或聚焦时进行预加载。这种方法监听 `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` 事件。由于这两种触发器都可能在不同条件下预加载同一资源，因此可能会导致不必要的资源使用或重复预加载。

启用跨域预加载

要启用跨域预加载，您可以在 `nuxt.config` 中设置 `crossOriginPrefetch` 选项。这将使用Speculation Rules 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` 属性

`to`: 任何 URL 或 Vue Router 的路由位置对象来自 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`: 强制链接渲染为 `` 标签而不是 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: {
        // 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 },
      },
    },
  },
})

自定义链接组件

您可以通过使用 `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`: 应用于已预加载链接的默认类。

在 Docs > 4 X > Examples > Routing > Pages 中阅读并编辑实时示例。

这有帮助吗？

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

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

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