v3.17

<NuxtLink>

Source
Nuxt 提供 <NuxtLink> 组件来处理应用中任何类型的链接。
<NuxtLink> 是 Vue Router 的 <RouterLink> 组件和 HTML 的 <a> 标签的简易替代品。它智能地判断链接是内部链接还是外部链接，并根据可用的优化（预取、默认属性等）进行渲染。

内部路由

¥Internal Routing

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

¥In this example, we use <NuxtLink> component to link to another page of the application.

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

传递参数动态路由

¥Passing Params to Dynamic Routes

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

¥In this example, we pass the id param to link to the route ~/pages/posts/[id].vue.

<template>
  <NuxtLink :to="{ name: 'posts-id', params: { id: 123 } }">
    Post 123
  </NuxtLink>
</template>
查看 Nuxt DevTools 中的“页面”面板，了解路由名称及其可能需要的参数。

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

¥Handling Static File and Cross-App Links

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

¥By default, <NuxtLink> uses Vue Router's client side navigation for relative route. When linking to static files in the /public directory or to another application hosted on the same domain, it might result in unexpected 404 errors because they are not part of the client routes. In such cases, you can use the external prop with <NuxtLink> to bypass Vue Router's internal routing mechanism.

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

¥The external prop explicitly indicates that the link is external. <NuxtLink> will render the link as a standard HTML <a> tag. This ensures the link behaves correctly, bypassing Vue Router’s logic and directly pointing to the resource.

链接到静态文件

¥Linking to Static Files

对于此类自定义，Nuxt 提供了 /public 功能，允许你扩展和更改页面配置。

¥For static files in the /public directory, such as PDFs or images, use the external prop to ensure the link resolves correctly.

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

链接到跨应用 URL

¥Linking to a Cross-App URL

当指向同一域名下的其他应用时，使用 external 属性可确保正确的行为。

¥When pointing to a different application on the same domain, using the external prop ensures the correct behavior.

pages/index.vue
<template>
  <NuxtLink to="/another-app" external>
    Go to Another App
  </NuxtLink>
</template>

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

¥Using the external prop or relying on automatic handling ensures proper navigation, avoids unexpected routing issues, and improves compatibility with static resources or cross-application scenarios.

外部路由

¥External Routing

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

¥In this example, we use <NuxtLink> component to link to a website.

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

rel 和 noRel 属性

¥rel and noRel Attributes

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

¥A rel attribute of noopener noreferrer is applied by default to links with a target attribute or to absolute links (e.g., links starting with http://, https://, or //).

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

这些默认值对 SEO 没有负面影响，并且被视为 最佳实践。

¥These defaults have no negative impact on SEO and are considered best practice.

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

¥When you need to overwrite this behavior you can use the rel or noRel props.

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 属性添加到绝对链接。

¥A noRel prop can be used to prevent the default rel attribute from being added to the absolute links.

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 流量，则会跳过预加载。

¥Nuxt automatically includes smart prefetching. That means it detects when a link is visible (by default), either in the viewport or when scrolling and prefetches the JavaScript for those pages so that they are ready when the user clicks the link. Nuxt only loads the resources when the browser isn't busy and skips prefetching if your connection is offline or if you only have 2g connection.

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 属性来控制何时预获取链接。

¥We now support custom prefetch triggers for <NuxtLink> after v3.13.0. You can use the prefetchOn prop to control when to prefetch links.

<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：当链接在视口中可见时进行预加载。使用 交叉监视器 API 监控元素与视口的交集。当元素滚动到视图中时触发预加载。
  • interaction：当链接悬停或聚焦时进行预加载。此方法监听 pointerenter 和 focus 事件，并在用户表示有交互意图时主动预加载资源。

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

¥You can also use an object to configure prefetchOn:

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

你可能不想同时启用这两个功能！

¥That you probably don't want both enabled!

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

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

¥This configuration will observe when the element enters the viewport and also listen for pointerenter and focus events. This may result in unnecessary resource usage or redundant prefetching, as both triggers can prefetch the same resource under different conditions.

启用跨域预取

¥Enable Cross-origin Prefetch

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

¥To enable cross-origin prefetching, you can set the crossOriginPrefetch option in your nuxt.config. This will enable cross-origin prefetching using the Speculation Rules API.

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

全局禁用预取

¥Disable prefetch globally

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

¥It's also possible to enable/disable prefetching all links globally for your app.

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

Props

RouterLink

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

¥When not using external, <NuxtLink> supports all Vue Router's RouterLink props

NuxtLink

  • href：to 的别名。如果与 to 一起使用，href 将被忽略。
  • noRel：如果设置为 true，则外部链接中不会添加任何 rel 属性。
  • external：幸运的是，Nuxt 提供了指南和特定变量来帮助你确定代码的执行位置。
  • prefetch：启用后，将预取视口中链接的中间件、布局和有效负载（使用 payloadExtraction 时）。由实验性 crossOriginPrefetch 配置使用。
  • prefetchOn：允许自定义控制何时预获取链接。可选选项为 interaction 和 visibility（默认值）。你还可以传递一个对象以获得完全控制，例如：{ interaction: true, visibility: true }。此属性仅在启用 prefetch（默认）且未设置 noPrefetch 时使用。
  • noPrefetch：禁用预获取。
  • prefetchedClass：应用于已预取链接的类。

锚点

¥Anchor

  • target：应用于链接的 target 属性值
  • rel：应用于链接的 rel 属性值。外部链接默认为 "noopener noreferrer"。
默认值可以被覆盖，如果你想更改默认值，请参阅 overwriting defaults。

覆盖默认值

¥Overwriting Defaults

Nuxt 配置中

¥In Nuxt Config

你可以在 nuxt.config 中覆盖部分 <NuxtLink> 的默认值。

¥You can overwrite some <NuxtLink> defaults in your nuxt.config

这些选项将来可能会被移动到其他地方，例如移动到 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> 的默认值。

¥You can overwrite <NuxtLink> defaults by creating your own link component using defineNuxtLink.

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

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

¥You can then use <MyNuxtLink /> component as usual with your new defaults.

defineNuxtLink 签名

¥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：HTML 注释也被视为元素。
  • prefetchedClass：应用于已预取链接的默认类。
Read and edit a live example in Docs > Examples > Routing > Pages.