full-stack-skills 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、事件触发的异步工作等不在渲染流程中的错误不会被捕获。
三个关键属性
| 属性 | 类型 | 说明 |
|---|---|---|
pending |
Snippet |
初次渲染时显示，直到所有 await 解析完成（只在初次渲染显示） |
failed |
Snippet<[error, reset]> |
发生错误时显示，接收 error 和可恢复的 reset 函数 |
onerror |
(error, reset) => void |
出错时调用，常用于上报到 Sentry 等；与 failed 并行触发 |
<svelte:boundary => report(e)}>
<FlakyComponent />
{#snippet pending()}
<p>加载中…</p>
{/snippet}
{#snippet failed(error, reset)}
<button 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 => { error = null; reset(); }}>oops! try again</button>
{/if}
完整示例与参考：examples/boundary-examples.md、references/boundary-reference.md
Critical: <svelte:window>
监听 window 事件和绑定 window 属性：
<svelte:window />
<svelte:window bind:scrollX bind:scrollY bind:innerWidth bind:innerHeight />
可绑定属性：
| 属性 | 类型 | 只读 | 说明 |
|---|---|---|---|
innerWidth / innerHeight |
number |
是 | 视口宽/高（CSS 像素） |
outerWidth / outerHeight |
number |
是 | 浏览器窗口外尺寸（含 chrome） |
scrollX / scrollY |
number |
否 | 滚动位置（唯一可写的窗口绑定） |
online |
boolean |
是 | navigator.onLine 的别名 |
devicePixelRatio |
number |
是 | 当前显示器的 device pixel ratio |
可监听事件：所有 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 />
<svelte:document {@attach myAttachment} />
可绑定属性（全部 readonly）：
| 属性 | 类型 | 说明 |
|---|---|---|
activeElement |
Element | null |
当前焦点元素 |
fullscreenElement |
Element | null |
当前全屏元素 |
pointerLockElement |
Element | null |
指针锁定的元素 |
visibilityState |
'visible' | 'hidden' |
文档可见性 |
最常用事件：onvisibilitychange（标签页切换）、onselectionchange（文本选择变化）、onreadystatechange、onfullscreenchange、onpointerlockchange、oncopy / oncut / onpaste 等。
<svelte:document>也只允许出现在顶层；支持{@attach ...}给document附加自定义行为。
Critical: <svelte:body>
监听 body 元素事件（如 mouseenter、mouseleave，这些事件不在 window 上触发）：
<svelte:body 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>
支持元素：
| 元素 | 用途 |
|---|---|
<title> |
文档标题 |
<meta> |
SEO（name="description"）、Open Graph（property="og:..."）、Twitter Card、robots 指令 |
<link rel="stylesheet" /> |
按页/按主题样式表 |
<link rel="canonical" /> |
规范 URL |
<link rel="prefetch" | rel="preload" /> |
资源预取/预加载 |
<style> |
内联关键 CSS |
<script type="application/ld+json"> |
JSON-LD 结构化数据 |
关键行为：
- 响应式：
$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" />
| 选项 | 类型 | 说明 |
|---|---|---|
runes={true|false} |
boolean |
强制进入/退出 Runes Mode |
namespace="html|svg|mathml" |
string |
组件命名空间（默认 html） |
customElement={...} |
string | object |
编译为自定义元素（字符串即 tag） |
css="injected" |
string |
样式内联注入（SSR → style 标签；CSR → JS） |
<svelte:options>必须放在<script>之后、模板之前。
Legacy（已弃用）选项（在 Runes 模式下无效）：immutable={true|false}、accessors={true|false}。
Quick Fixes
| 问题 | 解决方案 |
|---|---|
想监听 visibilitychange / selectionchange |
用 <svelte:document> 而非 <svelte:window> |
想监听 mouseenter / mouseleave |
用 <svelte:body> |
| 动态标签不渲染 | 检查 this 是否为 nullish |
| 样式不生效 | 用 css="injected" 强制内联 |
| 渲染抛错整个应用挂掉 | 用 <svelte:boundary> + failed 片段隔离 |
| 异步加载时显示骨架屏 | 用 <svelte:boundary> + pending 片段（仅首次渲染） |
| 渲染时想上报到 Sentry | 用 <svelte:boundary> |
想让 reset 在边界外触发 |
把 error / reset 存到 $state |
动态改 <title> 或 <meta> |
用 <svelte:head> 包裹响应式表达式 |
Gotchas
- 只能出现在顶层 —
svelte:window/document/body/head/element不能在{#if}或其他块级元素内。 - SSR 行为不同 —
<svelte:head>在 SSR 时内容单独暴露，不在 body 内；<svelte:boundary>默认对 SSR 无效（5.51+ 起可用transformError启用）。 svelte:element是通用绑定 — 不支持bind:value等元素特有绑定。svelte:window的scrollX/scrollY是唯一可写绑定 — 其他都 readonly。<svelte:boundary>不捕获事件处理器 /setTimeout中的错误 — 这些不是渲染流程。<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.
| File | Description |
|---|---|
| examples/boundary-examples.md | Comprehensive examples for <svelte:boundary>: pending, failed, onerror, transformError, error reporting, nested boundaries |
| examples/svelte-head-examples.md | <svelte:head> examples: SEO meta, Open Graph, structured data, dynamic stylesheets, SSR head extraction |
| examples/svelte-element-examples.md | Examples for <svelte:window>, <svelte:document>, <svelte:body>, <svelte:element>, <svelte:component>, <svelte:self>, <svelte:options> |
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.
| File | Description |
|---|---|
| references/boundary-reference.md | Full reference for <svelte:boundary> — pending/failed/onerror, transformError (5.51+), nesting, what is/isn't caught |
| references/svelte-head-reference.md | Full reference for <svelte:head> — SSR behavior, supported elements, hydration, reactivity |
| references/svelte-window-document-body-reference.md | All events and bindable properties for <svelte:window> / <svelte:document> / <svelte:body> |
| references/svelte-element-reference.md | Reference for <svelte:element>, <svelte:component>, <svelte:self>, <svelte:fragment> |
| references/svelte-options-reference.md | Full reference for <svelte:options> — customElement, runes, namespace, css, and all compiler options |