Svelte 最新中文文档教程（14）—— 特殊元素

前言

Svelte，一个非常"有趣"、用起来"很爽"的前端框架。从 Svelte 诞生之初，就备受开发者的喜爱，根据统计，从 2019 年到 2024 年，连续 6 年一直是开发者最感兴趣的前端框架 No.1：

Svelte 以其独特的编译时优化机制著称，具有轻量级 、高性能 、易上手 等特性，非常适合构建轻量级 Web 项目，也是我做个人项目的首选技术栈。

目前 Svelte 基于 Svelte 5 发布了最新的官方文档，但却缺少对应的中文文档。为了帮助大家学习 Svelte，为爱发电翻译了官方文档。

我同时搭建了 Svelte 最新的中文文档站点：svelte.yayujs.com ，如果需要辅助学习，也可以入手我的小册《Svelte 开发指南》，语法篇、实战篇、原理篇三大篇章带你系统掌握 Svelte！

虽说是翻译，但个人并不喜欢严格遵守原文，为了保证中文阅读流畅，会删减部分语句，对难懂的部分也会另做补充解释，希望能给大家带来一个好的中文学习体验。

欢迎围观我的"网页版朋友圈"、加入"低调务实优秀中国好青年"前端社群，踏上前端大佬成长之路。

svelte:boundary

svelte 复制代码

<svelte:boundary onerror={handler}>...</svelte:boundary>

[!NOTE] 此功能在 5.3.0 版本中添加

边界允许你防止应用程序的某一部分出错进而影响整个应用程序，并且可以从这些错误中恢复。

如果在渲染或更新 <svelte:boundary> 的子组件时发生错误，或在执行其中包含的任何 $effect 函数时发生错误，内容将被移除。

在渲染过程之外发生的错误（例如，在事件处理程序中）不会被错误边界捕获。

属性

要使边界发挥作用，必须提供 failed 和 onerror 中的一个或两个。

`failed`

如果提供了 failed 代码片段，它将与抛出的错误一起渲染，并提供一个重新创建内容的 reset 函数（demo）：

svelte 复制代码

<svelte:boundary>
  <FlakyComponent />

  {#snippet failed(error, reset)}
    <button onclick={reset}>糟糕！再试一次</button>
  {/snippet}
</svelte:boundary>

[!NOTE] 与传递给组件的代码片段一样，failed 代码片段可以作为属性显式传递...
svelte 复制代码
<svelte:boundary {failed}>...</svelte:boundary>
...或者像上面的例子那样直接在边界内部隐式声明。

`onerror`

如果提供了 onerror 函数，它将被调用并传入相同的两个参数 error 和 reset 。这对于使用错误报告服务跟踪错误很有用...

svelte 复制代码

<svelte:boundary onerror={(e) => report(e)}>
  ...
</svelte:boundary>

...或者在边界本身之外使用 error 和 reset：

svelte 复制代码

<script>
  let error = $state(null);
  let reset = $state(() => {});

  function onerror(e, r) {
    error = e;
    reset = r;
  }
</script>

<svelte:boundary {onerror}>
  <FlakyComponent />
</svelte:boundary>

{#if error}
  <button onclick={() => {
    error = null;
    reset();
  }}>
    糟糕！再试一次
  </button>
{/if}

如果在 onerror 函数内部发生错误（或者如果你重新抛出错误），它将被父边界处理（如果存在的话）。

svelte:window

svelte 复制代码

<svelte:window onevent={handler} />

svelte 复制代码

<svelte:window bind:prop={value} />

<svelte:window> 元素允许您向 window 对象添加事件监听器，而无需担心在组件销毁时移除它们，或在服务端渲染时检查 window 是否存在。

此元素只能出现在组件的顶层 --- 它不能在块或元素内部。

svelte 复制代码

<script>
  function handleKeydown(event) {
    alert(`按下了 ${event.key} 键`);
  }
</script>

<svelte:window onkeydown={handleKeydown} />

你还可以绑定以下属性：

innerWidth
innerHeight
outerWidth
outerHeight
scrollX
scrollY
online --- window.navigator.onLine 的别名
devicePixelRatio

除了 scrollX 和 scrollY 外，其他都是只读的。

svelte 复制代码

<svelte:window bind:scrollY={y} />

[!NOTE] 注意，页面不会滚动到初始值以避免可访问性问题。只有对 scrollX 和 scrollY 绑定变量的后续更改才会导致滚动。如果你有正当理由在组件渲染时滚动，请在 $effect 中调用 scrollTo()。

svelte:document

svelte 复制代码

<svelte:document onevent={handler} />

svelte 复制代码

<svelte:document bind:prop={value} />

与 <svelte:window> 类似，此元素允许您在 document 上添加事件监听器，比如 visibilitychange，这些事件不会在 window 上触发。它还允许您在 document 上使用 actions。

与 <svelte:window> 一样，此元素只能出现在组件的顶层，绝不能在块或元素内部。

svelte 复制代码

<svelte:document onvisibilitychange={handleVisibilityChange} use:someAction />

您还可以绑定以下属性：

activeElement
fullscreenElement
pointerLockElement
visibilityState

所有属性都是只读的。

svelte:body

svelte 复制代码

<svelte:body onevent={handler} />

与 <svelte:window> 类似，这个元素允许你在 document.body 上添加事件监听器，比如 mouseenter 和 mouseleave，这些事件在 window 上是不会触发的。它还允许你在 <body> 元素上使用actions。

与 <svelte:window> 和 <svelte:document> 一样，这个元素只能出现在组件的顶层，且绝不能在块或元素内部。

svelte 复制代码

<svelte:body onmouseenter={handleMouseenter} onmouseleave={handleMouseleave} use:someAction />

svelte:head

svelte 复制代码

<svelte:head>...</svelte:head>

这个元素可以将元素插入到 document.head 中。在服务端渲染期间，head 内容与主要的 body 内容是分开暴露（exposed）的。

与 <svelte:window>、<svelte:document> 和 <svelte:body> 一样，此元素只能出现在组件的顶层，且不能在块或元素内部。

svelte 复制代码

<svelte:head>
  <title>Hello world!</title>
  <meta name="description" content="This is where the description goes for SEO" />
</svelte:head>

svelte:element

svelte 复制代码

<svelte:element this={expression} />

<svelte:element> 元素允许你渲染一个未知的元素，例如该元素来自 CMS。存在的任何属性和事件监听器都将应用于该元素。

唯一支持的绑定是 bind:this，因为 Svelte 的内置绑定不适用于通用元素。

如果 this 是空值（nullish value），该元素及其子元素都不会被渲染。

如果 this 是空元素（例如 br）的名称，并且 <svelte:element> 包含子元素，在开发模式下将会抛出运行时错误：

svelte 复制代码

<script>
  let tag = $state('hr');
</script>

<svelte:element this={tag}>
  这段文本不能出现在 hr 元素内部
</svelte:element>

Svelte 会尽力从元素的周围环境推断出正确的命名空间，但这并不总是可行的。你可以使用 xmlns 属性明确指定它：

svelte 复制代码

<svelte:element this={tag} xmlns="http://www.w3.org/2000/svg" />

this 需要是一个有效的 DOM 元素标签，像 #text 或 svelte:head 这样的内容将不能正常运行。

svelte:options

svelte 复制代码

<svelte:options option={value} />

<svelte:options> 元素提供了一个指定每个组件编译器选项的位置，这些选项在编译器部分有详细说明。可用的选项包括：

runes={true} --- 强制组件进入 符文模式 (参见 Legacy APIs 部分)
runes={false} --- 强制组件进入 遗留模式
namespace="..." --- 该组件将使用的命名空间，可以是 "html"（默认）、"svg" 或 "mathml"
customElement={...} --- 将此组件编译为自定义元素时使用的选项。如果传入字符串，则将其用作 tag 选项
css="injected" --- 该组件将内联注入其样式：在服务端渲染期间，它会作为 <style> 标签注入到 head 中，在客户端渲染期间，它通过 JavaScript 加载

[!LEGACY] 遗留模式 Svelte 4 还包含以下废弃选项。它们在 Svelte 5 中已被废弃，在符文模式下不可用。

immutable={true} --- 从不使用可变数据，因此编译器可以进行简单的引用相等性检查来确定值是否已更改

immutable={false} --- 默认值。Svelte 将更保守地判断可变对象是否发生了变化。

accessors={true} --- 为组件的 props 添加 getter 和 setter

accessors={false} --- 默认值

svelte 复制代码

<svelte:options customElement="my-custom-element" />

Svelte 中文文档

本篇已收录在掘金专栏《Svelte 中文文档》，该系列预计 40 篇。

系统学习 Svelte，欢迎入手小册《Svelte 开发指南》。语法篇、实战篇、原理篇三大篇章带你系统掌握 Svelte！

此外我还写过 JavaScript 系列、TypeScript 系列、React 系列、Next.js 系列、冴羽答读者问等 14 个系列文章，全系列文章目录：github.com/mqyqingfeng...

通过文字建立交流本身就是一种缘分。欢迎围观我的"网页版朋友圈"、加入"低调务实优秀中国好青年"前端社群，分享技术，带你成长。