Skip to main content
SvelteKit高级

链接选项

在 SvelteKit 中，<a> 元素（而不是特定于框架的 <Link> 组件）用于在应用的路由之间导航。如果用户点击应用的 href 为 ‘owned’ 的链接（而不是指向外部站点的链接），那么 SvelteKit 将通过导入其代码然后调用它需要获取数据的任何 load 函数来导航到新页面。

¥In SvelteKit, <a> elements (rather than framework-specific <Link> components) are used to navigate between the routes of your app. If the user clicks on a link whose href is ‘owned’ by the app (as opposed to, say, a link to an external site) then SvelteKit will navigate to the new page by importing its code and then calling any load functions it needs to fetch data.

你可以使用 data-sveltekit-* 属性自定义链接的行为。这些可以应用于 <a> 本身，也可以应用于父元素。

¥You can customise the behaviour of links with data-sveltekit-* attributes. These can be applied to the <a> itself, or to a parent element.

这些选项也适用于带有 method="GET" 的 <form> 元素。

¥These options also apply to <form> elements with method="GET".

data-sveltekit-preload-data

在浏览器记录用户点击链接之前，我们可以检测到他们将鼠标悬停在链接上（在桌面上）或者触发了 touchstart 或 mousedown 事件。在这两种情况下，我们都可以有根据地猜测 click 事件即将到来。

¥Before the browser registers that the user has clicked on a link, we can detect that they’ve hovered the mouse over it (on desktop) or that a touchstart or mousedown event was triggered. In both cases, we can make an educated guess that a click event is coming.

SvelteKit 可以使用这些信息来抢先导入代码并获取页面数据，这可以为我们节省几百毫秒的时间 - 用户界面感觉迟钝和感觉敏捷之间的区别。

¥SvelteKit can use this information to get a head start on importing the code and fetching the page’s data, which can give us an extra couple of hundred milliseconds — the difference between a user interface that feels laggy and one that feels snappy.

我们可以使用 data-sveltekit-preload-data 属性控制此行为，该属性可以具有以下两个值之一：

¥We can control this behaviour with the data-sveltekit-preload-data attribute, which can have one of two values:

  • "hover" 表示鼠标停留在链接上时将开始预加载。在移动设备上，预加载从 touchstart 开始

    ¥"hover" means that preloading will start if the mouse comes to a rest over a link. On mobile, preloading begins on touchstart

  • "tap" 表示预加载将在注册 touchstart 或 mousedown 事件后立即开始

    ¥"tap" means that preloading will start as soon as a touchstart or mousedown event is registered

默认项目模板在 src/app.html 中将 data-sveltekit-preload-data="hover" 属性应用于 <body> 元素，这意味着默认情况下每个链接都会在悬停时预加载：

¥The default project template has a data-sveltekit-preload-data="hover" attribute applied to the <body> element in src/app.html, meaning that every link is preloaded on hover by default:

<body data-sveltekit-preload-data="hover">
	<div style="display: contents">%sveltekit.body%</div>
</body>

有时，当用户将鼠标悬停在链接上时调用 load 可能是不可取的，因为它可能会导致误报（单击不需要跟随悬停）或因为数据更新非常快并且延迟可能意味着陈旧。

¥Sometimes, calling load when the user hovers over a link might be undesirable, either because it’s likely to result in false positives (a click needn’t follow a hover) or because data is updating very quickly and a delay could mean staleness.

在这些情况下，你可以指定 "tap" 值，这会导致 SvelteKit 仅在用户点击或单击链接时调用 load：

¥In these cases, you can specify the "tap" value, which causes SvelteKit to call load only when the user taps or clicks on a link:

<a data-sveltekit-preload-data="tap" href="/stonks">
	Get current stonk values
</a>

你还可以以编程方式从 $app/navigation 调用 preloadData。

¥[!NOTE] You can also programmatically invoke preloadData from $app/navigation.

如果用户选择减少数据使用量，则永远不会预加载数据，这意味着 navigator.connection.saveData 是 true。

¥Data will never be preloaded if the user has chosen reduced data usage, meaning navigator.connection.saveData is true.

data-sveltekit-preload-code

即使在你不想为链接预加载数据的情况下，预加载代码也是有益的。data-sveltekit-preload-code 属性的工作方式与 data-sveltekit-preload-data 类似，不同之处在于它可以采用四个值之一，按 ‘eagerness’ 递减：

¥Even in cases where you don’t want to preload data for a link, it can be beneficial to preload the code. The data-sveltekit-preload-code attribute works similarly to data-sveltekit-preload-data, except that it can take one of four values, in decreasing ‘eagerness’:

  • "eager" 表示链接将立即预加载

    ¥"eager" means that links will be preloaded straight away

  • "viewport" 表示链接一旦进入视口就会预加载

    ¥"viewport" means that links will be preloaded once they enter the viewport

  • "hover" - 如上所述，只是只预加载了代码

    ¥"hover" - as above, except that only code is preloaded

  • "tap" - 如上所述，只是只预加载了代码

    ¥"tap" - as above, except that only code is preloaded

请注意，viewport 和 eager 仅适用于导航后立即出现在 DOM 中的链接 - 如果稍后添加链接（例如，在 {#if ...} 块中），它将不会被预加载，直到由 hover 或 tap 触发。这是为了避免因积极观察 DOM 的变化而导致的性能陷阱。

¥Note that viewport and eager only apply to links that are present in the DOM immediately following navigation — if a link is added later (in an {#if ...} block, for example) it will not be preloaded until triggered by hover or tap. This is to avoid performance pitfalls resulting from aggressively observing the DOM for changes.

由于预加载代码是预加载数据的先决条件，因此此属性仅在指定比任何存在的 data-sveltekit-preload-data 属性更迫切的值时才会起作用。

¥[!NOTE] Since preloading code is a prerequisite for preloading data, this attribute will only have an effect if it specifies a more eager value than any data-sveltekit-preload-data attribute that is present.

与 data-sveltekit-preload-data 一样，如果用户选择减少数据使用量，则将忽略此属性。

¥As with data-sveltekit-preload-data, this attribute will be ignored if the user has chosen reduced data usage.

data-sveltekit-reload

有时，我们需要告诉 SvelteKit 不要处理链接，而是允许浏览器处理它。将 data-sveltekit-reload 属性添加到链接...

¥Occasionally, we need to tell SvelteKit not to handle a link, but allow the browser to handle it. Adding a data-sveltekit-reload attribute to a link...

<a data-sveltekit-reload href="/path">Path</a>

...单击链接时将导致整页导航。

¥...will cause a full-page navigation when the link is clicked.

具有 rel="external" 属性的链接将获得相同的处理。此外，它们将在 prerendering 期间被忽略。

¥Links with a rel="external" attribute will receive the same treatment. In addition, they will be ignored during prerendering.

data-sveltekit-replacestate

有时你不希望导航在浏览器的会话历史记录中创建新条目。将 data-sveltekit-replacestate 属性添加到链接...

¥Sometimes you don’t want navigation to create a new entry in the browser’s session history. Adding a data-sveltekit-replacestate attribute to a link...

<a data-sveltekit-replacestate href="/path">Path</a>

...单击链接时将替换当前的 history 条目，而不是用 pushState 创建新条目。

¥...will replace the current history entry rather than creating a new one with pushState when the link is clicked.

data-sveltekit-keepfocus

有时你不希望在导航后使用 焦点将被重置。例如，也许你有一个在用户输入时提交的搜索表单，并且你希望将焦点保持在文本输入上。将 data-sveltekit-keepfocus 属性添加到它...

¥Sometimes you don’t want focus to be reset after navigation. For example, maybe you have a search form that submits as the user is typing, and you want to keep focus on the text input. Adding a data-sveltekit-keepfocus attribute to it...

<form data-sveltekit-keepfocus>
	<input type="text" name="query">
</form>

...将导致当前聚焦的元素在导航后保持焦点。一般来说，避免在链接上使用此属性，因为焦点元素将是 <a> 标签（而不是先前焦点的元素），并且屏幕阅读器和其他辅助技术用户通常希望在导航后移动焦点。你还应该只在导航后仍然存在的元素上使用此属性。如果元素不再存在，用户的焦点将丢失，从而给辅助技术用户带来混乱的体验。

¥...will cause the currently focused element to retain focus after navigation. In general, avoid using this attribute on links, since the focused element would be the <a> tag (and not a previously focused element) and screen reader and other assistive technology users often expect focus to be moved after a navigation. You should also only use this attribute on elements that still exist after navigation. If the element no longer exists, the user’s focus will be lost, making for a confusing experience for assistive technology users.

data-sveltekit-noscroll

导航到内部链接时，SvelteKit 会镜像浏览器的默认导航行为：它会将滚动位置更改为 0,0，以便用户位于页面的最左上角（除非链接包含 #hash，在这种情况下它会滚动到具有匹配 ID 的元素）。

¥When navigating to internal links, SvelteKit mirrors the browser’s default navigation behaviour: it will change the scroll position to 0,0 so that the user is at the very top left of the page (unless the link includes a #hash, in which case it will scroll to the element with a matching ID).

在某些情况下，你可能希望禁用此行为。将 data-sveltekit-noscroll 属性添加到链接...

¥In certain cases, you may wish to disable this behaviour. Adding a data-sveltekit-noscroll attribute to a link...

<a href="path" data-sveltekit-noscroll>Path</a>

...将阻止单击链接后滚动。

¥...will prevent scrolling after the link is clicked.

禁用选项(Disabling options)

¥Disabling options

要在已启用这些选项的元素内禁用任何这些选项，请使用 "false" 值：

¥To disable any of these options inside an element where they have been enabled, use the "false" value:

<div data-sveltekit-preload-data>
	<!-- these links will be preloaded -->
	<a href="/a">a</a>
	<a href="/b">b</a>
	<a href="/c">c</a>

	<div data-sveltekit-preload-data="false">
		<!-- these links will NOT be preloaded -->
		<a href="/d">d</a>
		<a href="/e">e</a>
		<a href="/f">f</a>
	</div>
</div>

要有条件地将属性应用于元素，请执行以下操作：

¥To apply an attribute to an element conditionally, do this:

<div data-sveltekit-preload-data={condition ? 'hover' : false}>
上一页 下一页
错误