# Svelte 5 Runes 带有适配器静态 (SvelteKit) ## 概述使用 Svelte 5 runes 构建静态优先的 SvelteKit 应用程序，而不会破坏水合作用。在使用“适配器静态”（预渲染）并将全局存储与组件本地符文相结合时应用这些模式。 ## 相关技能 * `svelte`（Svelte 5 符文核心模式） * `sveltekit`（适配器、部署、SSR/SSG 模式） * `typescript-core` （TypeScript 模式和验证） * `vitest`（单元测试模式） ## 核心专长使用符文模式和适当的状态管理模式构建静态优先的 Svelte 5 应用程序，以适应预渲染和水合作用。 ## 关键兼容性规则 ### ❌从不：模块范围内的符文带有适配器静态 **问题**：符文在静态预渲染后无法正确水化 // ❌ BROKEN - SSG 后状态被冻结导出函数createStore() { 让状态 = $state({ 计数: 0 }); 返回{ get count() { return state.count; } }, 增量： () => { state.count++; } }; } **为什么失败**： * `adapter-static` 将组件预渲染为 HTML * 模块范围内的符文不会序列化/反序列化 * 水合后状态变为惰性/冻结 * 反应性完全破坏 **解决方案**：使用传统的 `writable()` 存储来存储全局状态 // ✅ 有效 - 传统商店可以正确补水从'svelte/store'导入{可写}；导出函数createStore() { 常量计数 = 可写(0); 返回{ 计数，增量： () => count.update(n => n + 1) }; } ### ❌从不：$ 内部自动订阅$衍生 **问题**：符文模式禁用 `$` 自动订阅语法 // ❌ BROKEN - 无法在 $driven 中使用 $ 让过滤= $衍生（$ events.filter（e => e.type === 'info'））; // ^^^^^^^ 错误：$ 在符文模式下不可用 **解决方案** : 在 `$effect()` 中订阅 → 更新 `$state()` → 在 `$衍生()` 中使用 // ✅ WORKS - 手动订阅模式从 'svelte/store' 导入 { type Writable }; 让事件 = $state([]); $效果(() => { const unsub = eventsStore.subscribe(value => { 事件=价值； }); 返回取消订阅； }); 让过滤= $衍生（events.filter（e => e.type === 'info'））; ### ❌从不：使用 Getters 存储工厂 **问题**：吸气剂不建立反应性连接 // ❌ BROKEN - Getter 模式破坏了反应性导出函数 createSocketStore() { const 套接字=可写<套接字|空>(空); 返回{ 获取套接字（）{ 返回套接字； }, // ❌ 非反应式连接：() => { /* ... */ } }; } **解决方案**：直接导出商店 // ✅ WORKS - 直接商店导出导出函数 createSocketStore() { const 套接字=可写<套接字|空>(空); const isConnected = 派生(socket, $s => $s?.connected ?? false); 返回{ socket, // ✅ 直接存储引用 isConnected, // ✅ 直接派生引用连接：() => { /* ... */ } }; } ## 推荐的混合模式 ### 全球状态：传统商店对于需要在 SSG/SSR 中生存的状态使用 `writable()`/`衍生()`： // 商店/globalState.ts 从'svelte/store'导入{可写，派生}；导出常量用户=可写<用户|空>(空); 导出常量主题=可写<'light' | '暗'>('光'); 导出 const isAuthenticated = 派生(用户, $u => $u !== null); ### 组件状态：Svelte 5 Runes 使用 runes 来表示组件本地状态和逻辑： <脚本语言=“ts”> 从 '$lib/stores/globalState' 导入 { user } ； // 带有符文的道具让{ 初始计数 = 0, onUpdate = () => {} }：{ 初始计数？：数量； onUpdate?: (count: number) => void; } = $props(); // 桥：存储 → 符文状态让 currentUser = $state<用户 |空>(空); $效果(() => { const unsub = user.subscribe(u => { 当前用户 = u; }); 返回取消订阅； }); // 组件本地状态让计数 = $state(initialCount); 让双倍= $衍生（计数* 2）; // 效果 $效果(() => { 如果（计数 > 10）{ onUpdate(计数); } }); 函数增量() { 计数++； } <按钮onclick={增量}> {当前用户？.name ?? '客人'}：{计数}（×2 = {双倍}） ## 完整的桥模式 ### 商店→符文→衍生链 <脚本语言=“ts”> 从 'svelte/store' 导入 { type Writable }; // 1.导入全局store（传统） const { 事件：eventsStore，过滤器：filtersStore } = myGlobalStore; // 2. 通往符文状态的桥梁让事件 = $state([]); 让 activeFilters = $state([]); $效果(() => { const unsubEvents = eventsStore.subscribe(v => { events = v; }); const unsubFilters =filtersStore.subscribe(v => { activeFilters = v; }); 返回（）=> { 取消子事件（）；取消子过滤器（）； }; }); // 3. 衍生计算（纯符文）让过滤= $衍生（事件.过滤器（e => activeFilters.length === 0 || activeFilters.includes(e.category) ））；让计数= $衍生(filtered.length); 让 hasEvents = $衍生(计数 > 0); {#如果有事件}

找到 {count} 个事件

{#each 作为事件过滤} <事件卡{事件} /> {/每个} {：其他}

没有事件与过滤器匹配

{/如果} ## SSG/SSR 注意事项 ### 预渲染安全模式 // ✅ 可以安全地进行预渲染导出 const load = async ({ fetch }) => { const data = wait fetch('/api/data').then(r => r.json()); 返回{数据}； }; <脚本语言=“ts”> 从 '$app/environment' 导入 { browser } ；让 { 数据 } = $props(); // ✅ 仅客户端初始化 $效果(() => { 如果（浏览器）{ // WebSocket、localStorage 等初始化ClientOnlyFeatures(); } }); ### 预防水合作用不匹配 // ✅ 避免水合作用不匹配让时间戳= $状态<数字|空>(空); $效果(() => { 如果（浏览器）{ 时间戳= Date.now(); // 只在客户端设置 } }); {#如果浏览器} <实时时钟/> {：其他}

正在加载时钟...

{/如果} ## TypeScript 集成 ### 带符文的打字道具 <脚本语言=“ts”> 从 'svelte' 导入类型 { Snippet } ；接口道具 { 标题：字符串；数？：数量；项目：数组<{id：字符串；名称：字符串 }>; onSelect?: (id: string) => void; 孩子们？：片段； } 让{ 标题，计数 = 0，物品， onSelect = () => {}, 儿童 }: 道具 = $props(); 让所选 = $state<字符串 |空>(空); 让filteredItems = $衍生（项目.过滤器（项目=> 已选择===空|| item.id === 已选择））；

{标题}（{计数}）

{#每个filteredItems作为项目} <按钮 onclick={() => onSelect(item.id)}> {项目.名称} {/每个} {@渲染孩子？.()} ### 类型化存储桥 <脚本语言=“ts”> 从 'svelte/store' 导入类型 { Writable, Readable }; 接口 StoreShape { 数据：可写<字符串[]>；状态：可读<'正在加载' | '准备好' | '错误'>; } const 商店： StoreShape = getMyStores(); 让数据 = $state([]); 让状态 = $state<'正在加载' | '准备好' | '错误'>('加载'); $效果(() => { const unsubData =stores.data.subscribe(v => { data = v; }); const unsubStatus =stores.status.subscribe(v => { status = v; }); 返回（）=> { 取消子数据（）；取消子状态（）； }; }); 让 isEmpty = $衍生(data.length === 0); 让 isReady = $衍生(status === '准备好'); ## 常见模式 ### 可绑定组件状态 <脚本语言=“ts”> 让{ 值 = $bindable(''), 禁用=假 }：{ 值？：字符串；禁用？：布尔值； } = $props(); 让聚焦 = $state(false); 让 charCount = $衍生(value.length); 让 isValid = $衍生(charCount >= 3 && charCount <= 100); <输入绑定：值 {禁用} onfocus={() => { 聚焦 = true; }} onblur={() => { 聚焦 = false; }} 类别：专注类：无效={！isValid} />

{charCount}/100

### 表单状态管理 <脚本语言=“ts”> 接口表单数据{ 电子邮件：字符串；密码：字符串； } 让 formData = $state({ 电子邮件：''，密码：'' }); 让错误= $state>>({}); 让 isValid = $衍生( formData.email.includes('@') && formData.password.length >= 8 ）；让 canSubmit = $衍生( isValid && Object.keys(errors).length === 0 ）；函数验证（字段：FormData 的键）{ if (field === 'email' && !formData.email.includes('@')) { error.email = '无效的电子邮件'; } else if (field === 'password' && formData.password.length < 8) { error.password = '密码太短'; } 否则{ 删除错误[字段]； } } 异步函数handleSubmit() { if (!canSubmit) 返回； // 提交逻辑 const 结果 = 等待submitForm(formData); 如果（结果.ok）{ // 成功 } 否则{ 错误=结果.错误； } }

<输入类型=“电子邮件” 绑定：值= {formData.email} onblur={() => 验证('电子邮件')} /> {#if 错误.电子邮件} {errors.email} {/如果} <输入类型=“密码” 绑定：值= {formData.password} onblur={() => 验证('密码')} /> {#if 错误.密码} {errors.password} {/如果} <按钮类型=“提交”禁用= {！canSubmit}> 提交 ### 去抖搜索 <脚本语言=“ts”> 从'svelte/store'导入{可写，派生}； const searchQuery = 可写(''); // 具有去抖功能的传统派生存储 const debouncedQuery = 派生( 搜索查询，（$查询，设置）=> { const 超时 = setTimeout(() => set($query), 300); 返回（）=>清除超时（超时）； }, '' // 初始值）； // 通往符文状态的桥梁让查询 = $state(''); 让 debouncedValue = $state(''); $效果(() => { searchQuery.set(查询); }); $效果(() => { const unsub = debouncedQuery.subscribe(v => { 去抖值 = v; }); 返回取消订阅； }); // 在派生中使用让结果= $衍生( debouncedValue.length >= 3 ？执行搜索（去抖值）：[] ）； <输入类型=“搜索” 绑定：值={查询} 占位符=“搜索...” /> {#每个结果作为结果} <搜索结果{结果}/> {/每个} ## 迁移清单使用适配器静态从 Svelte 4 迁移到 Svelte 5 时： * 将组件级 `$:` 替换为 `$衍生()` * 将 `export let prop` 替换为 `let { prop } = $props()` * 将全局存储保持为`writable()`/`衍生()` * 为商店→符文状态添加桥梁图案 * 将`$store`语法替换为`$effect()`中的手动订阅 * 使用“npm run build”测试预渲染 * 验证水合作用是否正常 * 检查控制台中的水合作用是否不匹配 * 确保仅客户端代码受到“浏览器”检查的保护 ## 测试模式 ### 单元测试符文从 'svelte' 导入 { mount }; 从'svelte'导入{tick}；从 'vitest' 导入 { 描述、它、期望 }；从 './Counter.svelte' 导入计数器；描述('计数器', () => { it('增量计数', async () => { const { 组件 } = 安装（计数器，{ 目标：文档.body，道具：{初始计数：0} }); const 按钮 = document.querySelector('button'); 按钮？.click(); 等待刻度线（）； Expect(button?.textContent).toContain('1'); }); }); ### 测试商店桥从 'svelte/store' 导入 { get }; 从'svelte'导入{tick}；从 'vitest' 导入 { 描述、它、期望 }；从 './myStore' 导入 { createMyStore }；描述('存储桥', () => { it('将存储同步到符文状态', async () => { const store = createMyStore(); store.data.set(['item1', 'item2']); 等待刻度线（）； Expect(get(store.data)).toEqual(['item1', 'item2']); }); }); ## 性能考虑因素 ### 避免不必要的反应 // ❌ 过度反应让 items = $state([1, 2, 3, 4, 5]); 让 doubled = $衍生(items.map(x => x * 2)); 让三倍= $衍生（items.map（x => x * 3））; 让四倍= $衍生（items.map（x => x * 4））; // ✅ 只计算需要的内容让 items = $state([1, 2, 3, 4, 5]); 让transformedItems = $衍生（模式==='双'？ items.map(x => x * 2) : 模式==='三重'？ items.map(x => x * 3) : items.map(x => x * 4) ）； ### 记忆昂贵的计算 // 用于昂贵计算的传统派生存储 const 昂贵计算 = 派生( [来源1，来源2]， ([$s1, $s2]) => { // 昂贵的计算返回复杂算法($s1, $s2); } ）； // 符文桥梁让结果 = $state(null); $效果(() => { const unsub = luckyComputation.subscribe(v => { 结果 = v; }); 返回取消订阅； }); ## 故障排除 ### 症状：水合后状态不更新 **原因**：模块范围内的符文带有适配器静态 **修复**：使用传统的 `writable()` 存储来存储全局状态 ### 症状：$衍生中出现“$未定义”错误 **原因**：尝试在符文模式下使用 `$store` 语法 **修复**：使用桥接模式和“$effect()”订阅 ### 症状：SSG 后“无法读取未定义的属性” **原因**：使用吸气剂存储工厂而不是直接导出 **修复** ：直接导出 store，而不是用 getters 包装 ### 症状：水合不匹配警告 **原因**：SSR 期间呈现仅客户端状态 **修复** ：使用“浏览器”检查进行防护或使用“{#if browser}” ## 决策框架 **在以下情况下使用传统商店：** * 状态需要在 SSG/SSR 预渲染中生存 * 状态是全局的/跨组件共享的 * 状态需要序列化/反序列化 * 使用静态适配器 **在以下情况下使用符文：** * 状态是组件本地的 * 构建反应式 UI 逻辑 * 使用 props 和组件生命周期 * 从本地状态创建派生计算 **在以下情况下使用桥接模式：** * 需要将全球商店与组件符文结合起来 * 想要从存储值导出计算 * 构建复杂的反应链 ## 相关技能 * **toolchains-javascript-frameworks-svelte** ：基本 Svelte 模式 * **工具链-typescript-core**：TypeScript 集成 * **toolchains-ui-styling-tailwind** ：Svelte 组件样式 * **toolchains-javascript-testing-vitest** ：测试 Svelte 5 ## 参考文献 * [Svelte 5 Runes 文档]() * [SvelteKit 适配器静态]() * [Svelte 商店]()

Svelte5 符文静态

包含技能