Svelte Special Elements Reference (Svelte 5)

本技能覆盖 Svelte 模板中的特殊元素（以 svelte: 为前缀），用于处理错误边界、异步加载状态、窗口/文档/事件监听、动态标签、head 注入、编译器选项等场景。

When to use this skill

当用户需要捕获渲染错误或异步 pending 状态（<svelte:boundary>）、监听 window / document / body 事件、动态渲染 HTML 标签（<svelte:element>）、将内容注入到 document.head（<svelte:head>）、或配置编译器选项/自定义元素（<svelte:options>）时使用本技能。

Critical: <svelte:boundary> (Svelte 5.3+)

错误和异步边界，"隔离"应用局部以处理错误和 pending 状态。边界会捕获渲染过程中抛出的同步错误、$effect 中的错误、以及 await 表达式的 rejection；事件处理器、setTimeout、事件触发的异步工作等不在渲染流程中的错误不会被捕获。

三个关键属性

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

  {#snippet pending()}
    <p>加载中…</p>
  {/snippet}

  {#snippet failed(error, reset)}
    <button onclick={reset}>oops! try again</button>
  {/snippet}
</svelte:boundary>

SSR: transformError (Svelte 5.51+)

默认情况下，错误边界在服务端无效——一旦渲染出错，整个 render(...) 调用失败。从 5.51 起，可以在 render(...) / mount(...) / hydrate(...) 传入 transformError 函数，它必须返回一个 JSON-stringifiable 对象，用于在 failed 片段中渲染（SSR 时序列化到 HTML，客户端反序列化后用于水合）。

import { render } from 'svelte/server';
const { head, body } = await render(App, {
  transformError: (error) => {
    console.error(error); // 保留原始错误用于日志
    return { message: 'An error occurred!' }; // 返回脱敏后的安全对象
  }
});

在 onerror 中重新抛出

如果在 onerror 里抛错（或重新抛出原始错误），错误会被外层边界捕获——可用于在保留当前 failed UI 的同时把错误上报到全局边界。

reset 模式

reset 是个普通函数——可以存到 state 中，从任意位置调用（包括边界外的全局 UI、键盘快捷键等）：

<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(); }}>oops! try again</button>
{/if}

完整示例与参考：examples/boundary-examples.md、references/boundary-reference.md

Critical: <svelte:window>

监听 window 事件和绑定 window 属性：

<svelte:window onkeydown={handleKey} onresize={handleResize} />
<svelte:window bind:scrollX bind:scrollY bind:innerWidth bind:innerHeight />

可绑定属性：

可监听事件：所有 window 级别事件——键盘（onkeydown / onkeyup）、鼠标（onclick / onmousemove 等）、触摸（ontouchstart / ontouchmove）、指针（onpointerdown 等）、滚轮（onwheel）、剪贴板（oncopy / oncut / onpaste）、拖拽（ondrag 系列）、焦点（onfocus / onblur）、资源（onload / onerror / onscroll / onresize）等。

<svelte:window> 只能出现在组件顶层，不能在块级元素或条件块内。

初始挂载时不会将页面滚动到 scrollX / scrollY 的初始值（出于无障碍考虑）；只有后续值变化才会触发滚动。如需挂载即滚动，在 $effect 中调用 scrollTo()。

Critical: <svelte:document>

监听 document 级别事件（window 不支持的事件）：

<svelte:document onvisibilitychange={handleVisibility} />
<svelte:document {@attach myAttachment} />

可绑定属性（全部 readonly）：

最常用事件：onvisibilitychange（标签页切换）、onselectionchange（文本选择变化）、onreadystatechange、onfullscreenchange、onpointerlockchange、oncopy / oncut / onpaste 等。

<svelte:document> 也只允许出现在顶层；支持 {@attach ...} 给 document 附加自定义行为。

Critical: <svelte:body>

监听 body 元素事件（如 mouseenter、mouseleave，这些事件不在 window 上触发）：

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

<svelte:body> 同样支持 use: action（这是给 <body> 加 action 的唯一干净方式）。也只允许出现在顶层。

Critical: <svelte:head>

向 document.head 插入内容；SSR 时单独暴露于 body 之外，框架会把 head 内容放进 HTML <head> 标签。

<svelte:head>
  <title>Hello world!</title>
  <meta name="description" content="SEO description" />
  <meta property="og:title" content="OG title" />
  <link rel="canonical" href="/current-url" />
</svelte:head>

支持元素：

关键行为：

• 响应式：$state / $derived 变化时 head 自动更新。
• 重复合并：同种元素（如两个 <title>）后渲染的会覆盖前一个（不重复追加）。
• 多个块：同一组件内可有多个 <svelte:head>，全部合并到 head。
• SSR 单独暴露：render() 返回 { head, body }，框架需要把 head 放进 <head> 标签。

完整示例：examples/svelte-head-examples.md、references/svelte-head-reference.md

Critical: <svelte:element>

动态渲染未知标签（如来自 CMS 或数据库）：

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

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

行为规则：

• this 为 null / undefined → 元素不渲染
• this 为 void 元素（br、hr、img 等）但有子元素 → 开发模式下运行时错误
• Svelte 自动推断 namespace（svg、mathml），可用 xmlns 显式指定
• this 必须是合法的 DOM 标签名（如 div / circle）；#text、svelte:head 等无效

唯一支持的绑定：bind:this（因为通用元素不支持 Svelte 内建绑定如 bind:value）

Critical: <svelte:options>

设置编译器选项：

<svelte:options runes={true} />
<svelte:options namespace="svg" />
<svelte:options customElement="my-element" />
<svelte:options css="injected" />

<svelte:options> 必须放在 <script> 之后、模板之前。

Legacy（已弃用）选项（在 Runes 模式下无效）：immutable={true|false}、accessors={true|false}。

Quick Fixes

Gotchas

1. 只能出现在顶层 — svelte:window/document/body/head/element 不能在 {#if} 或其他块级元素内。
2. SSR 行为不同 — <svelte:head> 在 SSR 时内容单独暴露，不在 body 内；<svelte:boundary> 默认对 SSR 无效（5.51+ 起可用 transformError 启用）。
3. svelte:element 是通用绑定 — 不支持 bind:value 等元素特有绑定。
4. svelte:window 的 scrollX / scrollY 是唯一可写绑定 — 其他都 readonly。
5. <svelte:boundary> 不捕获事件处理器 / setTimeout 中的错误 — 这些不是渲染流程。
6. <svelte:boundary> 的 pending 只在初次渲染显示 — 后续异步更新用 $effect.pending()。

FAQ

Q: <svelte:boundary> 和 try/catch 有什么区别？ A: svelte:boundary 捕获渲染时的同步/异步错误和 $effect 中的错误；try/catch 只能捕获同步错误。boundary 还可配合 {#snippet pending} 处理初次异步加载状态。

Q: 什么时候用 onerror，什么时候用 failed？ A: failed 是 UI——决定出错时显示什么；onerror 是副作用——决定出错时做什么（如上报到 Sentry）。两者完全独立，可以只用其一，也可以同时使用。

Q: svelte:element 和普通组件有什么区别？ A: svelte:element 渲染 HTML 标签（不是 Svelte 组件），适用于标签在运行时才确定的场景，如 CMS 内容。

Q: 什么时候用 namespace="svg"？ A: 当组件会作为 SVG 子元素被使用时（如 <Icon.svelte> 作为 <svg> 内 <g> 使用）。

Q: mount / hydrate / render 怎么传 transformError？ A: 都是同一签名——传一个 (error) => JSON-stringifiable-object 的函数：

import { mount, hydrate } from 'svelte';
import { render } from 'svelte/server';

mount(App, { target, transformError: (e) => ({ message: e.message }) });
hydrate(App, { target, transformError: (e) => ({ message: 'Hydration failed' }) });
const { head, body } = await render(App, { transformError: (e) => ({ message: '...' }) });

Q: 可以在多个组件中用同一个 <svelte:head> 块吗？ A: 不行——<svelte:head> 是组件级的作用域。但你可以把 head 内容拆成 snippet，在多个组件中分别引入，或者封装一个 <MetaTags> 组件。

Q: <svelte:window> 的事件处理器会影响性能吗？ A: onresize / onscroll 这类高频事件建议做节流/防抖；其他事件开销可忽略。Svelte 会在组件销毁时自动移除监听器，无需手动清理。

Examples

Practical examples demonstrating all svelte: special elements.

Quick Examples

• svelte:boundary: error fallback, loading skeleton, Sentry reporting, SSR transformError
• svelte:window: keyboard shortcuts, resize handling, scroll position binding
• svelte:document: page visibility, text selection tracking
• svelte:body: mouse enter/leave events
• svelte:head: dynamic <title>, Open Graph meta, JSON-LD, per-page stylesheets
• svelte:element: dynamic heading levels (h1-h6), conditional tags, SVG namespace
• svelte:component: dynamic component switching
• svelte:options: customElement, runes mode, SVG namespace

References

Detailed reference documentation for all special elements and compiler options.