This is the full developer documentation for Svelte and SvelteKit. # Start of Svelte documentation # 概述 Svelte 是一个用于在 Web 上构建用户界面的框架。它使用编译器将用 HTML、CSS 和 JavaScript 编写的声明性组件转换为... ¥Svelte is a framework for building user interfaces on the web. It uses a compiler to turn declarative components written in HTML, CSS and JavaScript... ```svelte ``` ...精简、紧密优化的 JavaScript。 ¥...into lean, tightly optimized JavaScript. 你可以使用它在网络上构建任何东西，从独立组件到雄心勃勃的全栈应用（使用 Svelte 的配套应用框架 [SvelteKit](../kit)）以及介于两者之间的一切。 ¥You can use it to build anything on the web, from standalone components to ambitious full stack apps (using Svelte's companion application framework, [SvelteKit](../kit)) and everything in between. 这些页面用作参考文档。如果你是 Svelte 新手，我们建议你从 [互动教程](/tutorial) 开始，有问题时再回来这里。 ¥These pages serve as reference documentation. If you're new to Svelte, we recommend starting with the [interactive tutorial](/tutorial) and coming back here when you have questions. 你还可以在 [playground](https://svelte.dev/playground) 中在线试用 Svelte，或者，如果你需要功能更齐全的环境，可以在 [StackBlitz](https://sveltekit.new) 上试用。 ¥You can also try Svelte online in the [playground](https://svelte.dev/playground) or, if you need a more fully-featured environment, on [StackBlitz](https://sveltekit.new). # 立即开始 我们建议使用 [SvelteKit](../kit)，它允许你使用 [几乎可以构建任何内容](../kit/project-types)。这是 Svelte 团队的官方应用框架，由 [Vite](https://vite.dev/) 提供支持。使用以下代码创建一个新项目： ¥We recommend using [SvelteKit](../kit), which lets you [build almost anything](../kit/project-types). It's the official application framework from the Svelte team and powered by [Vite](https://vite.dev/). Create a new project with: ```bash npx sv create myapp cd myapp npm install npm run dev ``` 如果你还不了解 Svelte，请不要担心！你现在可以忽略 SvelteKit 带来的所有优秀功能，稍后再深入研究。 ¥Don't worry if you don't know Svelte yet! You can ignore all the nice features SvelteKit brings on top for now and dive into it later. ## SvelteKit 的替代品(Alternatives to SvelteKit) ¥Alternatives to SvelteKit 你还可以通过运行 `npm create vite@latest` 并选择 `svelte` 选项将 Svelte 直接与 Vite 一起使用。这样，`npm run build` 将使用 [vite-plugin-svelte](https://github.com/sveltejs/vite-plugin-svelte) 在 `dist` 目录中生成 HTML、JS 和 CSS 文件。在大多数情况下，你可能还需要 [选择路由库](faq#Is-there-a-router)。 ¥You can also use Svelte directly with Vite by running `npm create vite@latest` and selecting the `svelte` option. With this, `npm run build` will generate HTML, JS, and CSS files inside the `dist` directory using [vite-plugin-svelte](https://github.com/sveltejs/vite-plugin-svelte). In most cases, you will probably need to [choose a routing library](faq#Is-there-a-router) as well. >[!NOTE] Vite is often used in standalone mode to build [single page apps (SPAs)](../kit/glossary#SPA), which you can also [build with SvelteKit](../kit/single-page-apps). 还有适用于 [Rollup](https://github.com/sveltejs/rollup-plugin-svelte)、[Webpack](https://github.com/sveltejs/svelte-loader) [以及其他一些](https://sveltesociety.dev/packages?category=build-plugins) 的插件，但我们推荐 Vite。 ¥There are also plugins for [Rollup](https://github.com/sveltejs/rollup-plugin-svelte), [Webpack](https://github.com/sveltejs/svelte-loader) [and a few others](https://sveltesociety.dev/packages?category=build-plugins), but we recommend Vite. ## 编辑器工具(Editor tooling) ¥Editor tooling Svelte 团队维护 [VS Code 扩展](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode)，并且还与其他各种 [编辑器](https://sveltesociety.dev/resources#editor-support) 和工具集成。 ¥The Svelte team maintains a [VS Code extension](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode), and there are integrations with various other [editors](https://sveltesociety.dev/resources#editor-support) and tools as well. 你还可以使用 [sv check](https://github.com/sveltejs/cli) 从命令行检查你的代码。 ¥You can also check your code from the command line using [sv check](https://github.com/sveltejs/cli). ## 寻求帮助(Getting help) ¥Getting help 不要羞于在 [Discord 聊天室](/chat) 中寻求帮助！你还可以在 [Stack Overflow](https://stackoverflow.com/questions/tagged/svelte) 上找到答案。 ¥Don't be shy about asking for help in the [Discord chatroom](/chat)! You can also find answers on [Stack Overflow](https://stackoverflow.com/questions/tagged/svelte). # .svelte 文件 组件是 Svelte 应用的构建块。它们使用 HTML 的超集写入 `.svelte` 文件。 ¥Components are the building blocks of Svelte applications. They are written into `.svelte` files, using a superset of HTML. 所有三个部分（脚本、样式和标记）都是可选的。 ¥All three sections — script, styles and markup — are optional. ```svelte /// file: MyComponent.svelte ``` ## ` ``` 你可以从此块中 `export` 绑定，它们将成为已编译模块的导出。你不能 `export default`，因为默认导出是组件本身。 ¥You can `export` bindings from this block, and they will become exports of the compiled module. You cannot `export default`, since the default export is the component itself. > [!NOTE] 如果你使用 TypeScript 并将此类导出从 `module` 块导入到 `.ts` 文件中，请确保已设置你的编辑器，以便 TypeScript 能够识别它们。我们的 VS Code 扩展和 IntelliJ 插件就是这种情况，但在其他情况下，你可能需要设置我们的 [TypeScript editor plugin](https://www.npmjs.com/package/typescript-svelte-plugin)。 > [!LEGACY] > 在 Svelte 4 中，此脚本标签是使用 ` ``` 与你可能遇到的其他框架不同，没有用于与状态交互的 API — `count` 只是一个数字，而不是一个对象或函数，你可以像更新任何其他变量一样更新它。 ¥Unlike other frameworks you may have encountered, there is no API for interacting with state — `count` is just a number, rather than an object or a function, and you can update it like you would update any other variable. ### 深度状态(Deep state) ¥Deep state 如果 `$state` 与数组或简单对象一起使用，则结果是一个深度反应状态代理。[代理](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) 允许 Svelte 在你读取或写入属性时运行代码，包括通过 `array.push(...)` 等方法，触发细粒度更新。 ¥If `$state` is used with an array or a simple object, the result is a deeply reactive *state proxy*. [Proxies](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) allow Svelte to run code when you read or write properties, including via methods like `array.push(...)`, triggering granular updates. 状态会被递归代理，直到 Svelte 找到除数组或简单对象以外的其他内容（例如，类或使用 `Object.create` 创建的对象）。在这种情况下... ¥State is proxified recursively until Svelte finds something other than an array or simple object (like a class or an object created with `Object.create`). In a case like this... ```js let todos = $state([ { done: false, text: 'add more todos' } ]); ``` ...修改单个待办事项的属性将触发对依赖于该特定属性的 UI 中任何内容的更新： ¥...modifying an individual todo's property will trigger updates to anything in your UI that depends on that specific property: ```js let todos = [{ done: false, text: 'add more todos' }]; // ---cut--- todos[0].done = !todos[0].done; ``` 如果你将新对象推送到数组，它也将被代理： ¥If you push a new object to the array, it will also be proxified: ```js let todos = [{ done: false, text: 'add more todos' }]; // ---cut--- todos.push({ done: false, text: 'eat lunch' }); ``` > [!NOTE] 更新代理的属性时，原始对象不会发生修改。 请注意，如果你解构一个反应性值，则引用不是反应性的 - 与普通 JavaScript 一样，它们在解构时进行评估： ¥Note that if you destructure a reactive value, the references are not reactive — as in normal JavaScript, they are evaluated at the point of destructuring: ```js let todos = [{ done: false, text: 'add more todos' }]; // ---cut--- let { done, text } = todos[0]; // this will not affect the value of `done` todos[0].done = !todos[0].done; ``` ### 类(Classes) ¥Classes 类实例不被代理。相反，你可以在类字段（无论是公共字段还是私有字段）中使用 `$state`，或者将其作为 `constructor` 内部属性的第一个赋值： ¥Class instances are not proxied. Instead, you can use `$state` in class fields (whether public or private), or as the first assignment to a property immediately inside the `constructor`: ```js // @errors: 7006 2554 class Todo { done = $state(false); constructor(text) { this.text = $state(text); } reset() { this.text = ''; this.done = false; } } ``` > [!NOTE] 编译器会将 `done` 和 `text` 转换为类原型上引用私有字段的 `get`/`set` 方法。这意味着这些属性不可枚举。 在 JavaScript 中调用方法时，[`this`](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Operators/this) 的值很重要。这不起作用，因为 `reset` 方法内的 `this` 将是 ` ``` 你可以使用内联函数... ¥You can either use an inline function... ```svelte ``` ...或在类定义中使用箭头函数： ¥...or use an arrow function in the class definition: ```js // @errors: 7006 2554 class Todo { done = $state(false); constructor(text) { this.text = $state(text); } +++reset = () => {+++ this.text = ''; this.done = false; } } ``` > Svelte 提供了内置类（如 `Set` 和 `Map`）的响应式实现，可以从 [`svelte/reactivity`](svelte-reactivity) 导入。 ## `$state.raw` 如果你不希望对象和数组具有深度反应性，则可以使用 `$state.raw`。 ¥In cases where you don't want objects and arrays to be deeply reactive you can use `$state.raw`. 用 `$state.raw` 声明的状态无法修改；只能重新分配。换句话说，如果你想要更新对象或数组，则无需将其分配给对象的属性，也不必使用数组方法（如 `push`），而是将其全部替换： ¥State declared with `$state.raw` cannot be mutated; it can only be *reassigned*. In other words, rather than assigning to a property of an object, or using an array method like `push`, replace the object or array altogether if you'd like to update it: ```js let person = $state.raw({ name: 'Heraclitus', age: 49 }); // this will have no effect person.age += 1; // this will work, because we're creating a new person person = { name: 'Heraclitus', age: 50 }; ``` 这可以提高你原本不打算修改的大型数组和对象的性能，因为它避免了使它们具有反应性的成本。请注意，原始状态可以包含反应状态（例如，反应对象的原始数组）。 ¥This can improve performance with large arrays and objects that you weren't planning to mutate anyway, since it avoids the cost of making them reactive. Note that raw state can *contain* reactive state (for example, a raw array of reactive objects). 与 `$state` 一样，你可以使用 `$state.raw` 声明类字段。 ¥As with `$state`, you can declare class fields using `$state.raw`. ## `$state.snapshot` 要获取深度反应式 `$state` 代理的静态快照，请使用 `$state.snapshot`： ¥To take a static snapshot of a deeply reactive `$state` proxy, use `$state.snapshot`: ```svelte ``` 当你想要将某些状态传递给不需要代理的外部库或 API（例如 `structuredClone`）时，这很方便。 ¥This is handy when you want to pass some state to an external library or API that doesn't expect a proxy, such as `structuredClone`. ## 将状态传递给函数(Passing state into functions) ¥Passing state into functions JavaScript 是一种按值传递语言 - 当你调用函数时，参数是值而不是变量。换句话说： ¥JavaScript is a *pass-by-value* language — when you call a function, the arguments are the *values* rather than the *variables*. In other words: ```js /// file: index.js // @filename: index.js // ---cut--- /** * @param {number} a * @param {number} b */ function add(a, b) { return a + b; } let a = 1; let b = 2; let total = add(a, b); console.log(total); // 3 a = 3; b = 4; console.log(total); // still 3! ``` 如果 `add` 想要访问 `a` 和 `b` 的当前值，并返回当前 `total` 值，则需要使用函数： ¥If `add` wanted to have access to the *current* values of `a` and `b`, and to return the current `total` value, you would need to use functions instead: ```js /// file: index.js // @filename: index.js // ---cut--- /** * @param {() => number} getA * @param {() => number} getB */ function add(+++getA, getB+++) { return +++() => getA() + getB()+++; } let a = 1; let b = 2; let total = add+++(() => a, () => b)+++; console.log(+++total()+++); // 3 a = 3; b = 4; console.log(+++total()+++); // 7 ``` Svelte 中的状态没有什么不同 — 当你引用用 `$state` 符文声明的内容时…… ¥State in Svelte is no different — when you reference something declared with the `$state` rune... ```js let a = +++$state(1)+++; let b = +++$state(2)+++; ``` ...你正在访问其当前值。 ¥...you're accessing its *current value*. 请注意，'functions' 范围很广 - 它包含代理属性和 [`get`](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Functions/get)/[`set`](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Functions/set) 属性…… ¥Note that 'functions' is broad — it encompasses properties of proxies and [`get`](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Functions/get)/[`set`](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Functions/set) properties... ```js /// file: index.js // @filename: index.js // ---cut--- /** * @param {{ a: number, b: number }} input */ function add(input) { return { get value() { return input.a + input.b; } }; } let input = $state({ a: 1, b: 2 }); let total = add(input); console.log(total.value); // 3 input.a = 3; input.b = 4; console.log(total.value); // 7 ``` ...但是如果你发现自己在写这样的代码，可以考虑改用 [classes](#Classes)。 ¥...though if you find yourself writing code like that, consider using [classes](#Classes) instead. ## 跨模块传递状态(Passing state across modules) ¥Passing state across modules 你可以在 `.svelte.js` 和 `.svelte.ts` 文件中声明状态，但只有在未直接重新分配状态的情况下才能导出该状态。换句话说，你不能这样做： ¥You can declare state in `.svelte.js` and `.svelte.ts` files, but you can only *export* that state if it's not directly reassigned. In other words you can't do this: ```js /// file: state.svelte.js export let count = $state(0); export function increment() { count += 1; } ``` 这是因为对 `count` 的每个引用都会被 Svelte 编译器转换 - 上面的代码大致相当于： ¥That's because every reference to `count` is transformed by the Svelte compiler — the code above is roughly equivalent to this: ```js /// file: state.svelte.js (compiler output) // @filename: index.ts interface Signal { value: T; } interface Svelte { state(value?: T): Signal; get(source: Signal): T; set(source: Signal, value: T): void; } declare const $: Svelte; // ---cut--- export let count = $.state(0); export function increment() { $.set(count, $.get(count) + 1); } ``` > [!NOTE] 你可以通过点击 [playground](https://svelte.dev/playground) 中的 'JS Output' 选项卡来查看 Svelte 生成的代码。 由于编译器一次只操作一个文件，因此如果另一个文件导入 `count`，Svelte 并不知道它需要将每个引用封装在 `$.get` 和 `$.set` 中： ¥Since the compiler only operates on one file at a time, if another file imports `count` Svelte doesn't know that it needs to wrap each reference in `$.get` and `$.set`: ```js // @filename: state.svelte.js export let count = 0; // @filename: index.js // ---cut--- import { count } from './state.svelte.js'; console.log(typeof count); // 'object', not 'number' ``` 这为你提供了两种在模块之间共享状态的选项 - 要么不重新分配它…… ¥This leaves you with two options for sharing state between modules — either don't reassign it... ```js // This is allowed — since we're updating // `counter.count` rather than `counter`, // Svelte doesn't wrap it in `$.state` export const counter = $state({ count: 0 }); export function increment() { counter.count += 1; } ``` ...或者不直接导出它： ¥...or don't directly export it: ```js let count = $state(0); export function getCount() { return count; } export function increment() { count += 1; } ``` # $derived 派生状态用 `$derived` 符文声明： ¥Derived state is declared with the `$derived` rune: ```svelte

{count} doubled is {doubled}

``` `$derived(...)` 中的表达式应该没有副作用。Svelte 将禁止在派生表达式内更改状态（例如 `count++`）。 ¥The expression inside `$derived(...)` should be free of side-effects. Svelte will disallow state changes (e.g. `count++`) inside derived expressions. 与 `$state` 一样，你可以将类字段标记为 `$derived`。 ¥As with `$state`, you can mark class fields as `$derived`. > [!NOTE] Svelte 组件中的代码仅在创建时执行一次。如果没有 `$derived` 符文，即使 `count` 发生变化，`doubled` 也会保持其原始值。 ## `$derived.by` 有时你需要创建不适合简短表达式的复杂派生。在这些情况下，你可以使用接受函数作为其参数的 `$derived.by`。 ¥Sometimes you need to create complex derivations that don't fit inside a short expression. In these cases, you can use `$derived.by` which accepts a function as its argument. ```svelte ``` 本质上，`$derived(expression)` 相当于 `$derived.by(() => expression)`。 ¥In essence, `$derived(expression)` is equivalent to `$derived.by(() => expression)`. ## 了解依赖(Understanding dependencies) ¥Understanding dependencies 在 `$derived` 表达式（或 `$derived.by` 函数体）内同步读取的任何内容都被视为派生状态的依赖。当状态发生变化时，派生将被标记为脏，并在下次读取时重新计算。 ¥Anything read synchronously inside the `$derived` expression (or `$derived.by` function body) is considered a *dependency* of the derived state. When the state changes, the derived will be marked as *dirty* and recalculated when it is next read. 要使某个状态不被视为依赖，请使用 [`untrack`](svelte#untrack)。 ¥To exempt a piece of state from being treated as a dependency, use [`untrack`](svelte#untrack). ## 覆盖派生值(Overriding derived values) ¥Overriding derived values 当派生表达式的依赖发生变化时，会重新计算它们，但你可以通过重新分配它们来暂时覆盖它们的值（除非它们是用 `const` 声明的）。这对于乐观 UI 之类的东西很有用，其中一个值来自 '真相来源'（例如来自服务器的数据），但你希望立即向用户显示反馈： ¥Derived expressions are recalculated when their dependencies change, but you can temporarily override their values by reassigning them (unless they are declared with `const`). This can be useful for things like *optimistic UI*, where a value is derived from the 'source of truth' (such as data from your server) but you'd like to show immediate feedback to the user: ```svelte ``` > [!NOTE] 在 Svelte 5.25 之前，派生类是只读的。 ## 衍生品和反应性(Deriveds and reactivity) ¥Deriveds and reactivity 与将对象和数组转换为 [深度反应代理]($state#Deep-state) 的 `$state` 不同，`$derived` 值保持原样。例如，[在这种情况下](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE4VU22rjMBD9lUHd3aaQi9PdstS1A3t5XvpQ2Ic4D7I1iUUV2UjjNMX431eS7TRdSosxgjMzZ45mjt0yzffIYibvy0ojFJWqDKCQVBk2ZVup0LJ43TJ6rn2aBxw-FP2o67k9oCKP5dziW3hRaUJNjoYltjCyplWmM1JIIAn3FlL4ZIkTTtYez6jtj4w8WwyXv9GiIXiQxLVs9pfTMR7EuoSLIuLFbX7Z4930bZo_nBrD1bs834tlfvsBz9_SyX6PZXu9XaL4gOWn4sXjeyzftv4ZWfyxubpzxzg6LfD4MrooxELEosKCUPigQCMPKCZh0OtQE1iSxcsmdHuBvCiHZXALLXiN08EL3RRkaJ_kDVGle0HcSD5TPEeVtj67O4Nrg9aiSNtBY5oODJkrL5QsHtN2cgXp6nSJMWzpWWGasdlsGEMbzi5jPr5KFr0Ep7pdeM2-TCelCddIhDxAobi1jqF3cMaC1RKp64bAW9iFAmXGIHfd4wNXDabtOLN53w8W53VvJoZLh7xk4Rr3CoL-UNoLhWHrT1JQGcM17u96oES5K-kc2XOzkzqGCKL5De79OUTyyrg1zgwXsrEx3ESfx4Bz0M5UjVMHB24mw9SuXtXFoN13fYKOM1tyUT3FbvbWmSWCZX2Er-41u5xPoml45svRahl9Wb9aasbINJixDZwcPTbyTLZSUsAvrg_cPuCR7s782_WU8343Y72Qtlb8OYatwuOQvuN13M_hJKNfxann1v1U_B1KZ_D_mzhzhz24fw85CSz2irtN9w9HshBK7AQAAA==)... ¥Unlike `$state`, which converts objects and arrays to [deeply reactive proxies]($state#Deep-state), `$derived` values are left as-is. For example, [in a case like this](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE4VU22rjMBD9lUHd3aaQi9PdstS1A3t5XvpQ2Ic4D7I1iUUV2UjjNMX431eS7TRdSosxgjMzZ45mjt0yzffIYibvy0ojFJWqDKCQVBk2ZVup0LJ43TJ6rn2aBxw-FP2o67k9oCKP5dziW3hRaUJNjoYltjCyplWmM1JIIAn3FlL4ZIkTTtYez6jtj4w8WwyXv9GiIXiQxLVs9pfTMR7EuoSLIuLFbX7Z4930bZo_nBrD1bs834tlfvsBz9_SyX6PZXu9XaL4gOWn4sXjeyzftv4ZWfyxubpzxzg6LfD4MrooxELEosKCUPigQCMPKCZh0OtQE1iSxcsmdHuBvCiHZXALLXiN08EL3RRkaJ_kDVGle0HcSD5TPEeVtj67O4Nrg9aiSNtBY5oODJkrL5QsHtN2cgXp6nSJMWzpWWGasdlsGEMbzi5jPr5KFr0Ep7pdeM2-TCelCddIhDxAobi1jqF3cMaC1RKp64bAW9iFAmXGIHfd4wNXDabtOLN53w8W53VvJoZLh7xk4Rr3CoL-UNoLhWHrT1JQGcM17u96oES5K-kc2XOzkzqGCKL5De79OUTyyrg1zgwXsrEx3ESfx4Bz0M5UjVMHB24mw9SuXtXFoN13fYKOM1tyUT3FbvbWmSWCZX2Er-41u5xPoml45svRahl9Wb9aasbINJixDZwcPTbyTLZSUsAvrg_cPuCR7s782_WU8343Y72Qtlb8OYatwuOQvuN13M_hJKNfxann1v1U_B1KZ_D_mzhzhz24fw85CSz2irtN9w9HshBK7AQAAA==)... ```svelte let items = $state([...]); let index = $state(0); let selected = $derived(items[index]); ``` ...你可以更改（或将 `bind:` 更改为）`selected` 的属性，这将影响底层 `items` 数组。如果 `items` 不是深度反应，则改变 `selected` 将不会产生任何影响。 ¥...you can change (or `bind:` to) properties of `selected` and it will affect the underlying `items` array. If `items` was *not* deeply reactive, mutating `selected` would have no effect. ## 更新传播(Update propagation) ¥Update propagation Svelte 使用一种称为推拉反应性的东西 - 当状态更新时，依赖于状态的所有内容（无论是直接还是间接）都会立即收到更改通知（'push'），但派生值不会重新评估，直到实际读取它们（'pull'）。 ¥Svelte uses something called *push-pull reactivity* — when state is updated, everything that depends on the state (whether directly or indirectly) is immediately notified of the change (the 'push'), but derived values are not re-evaluated until they are actually read (the 'pull'). 如果派生的新值在引用上与其先前的值相同，则将跳过下游更新。换句话说，Svelte 只会在 `large` 更改时更新按钮内的文本，而不会在 `count` 更改时更新，即使 `large` 依赖于 `count`： ¥If the new value of a derived is referentially identical to its previous value, downstream updates will be skipped. In other words, Svelte will only update the text inside the button when `large` changes, not when `count` changes, even though `large` depends on `count`: ```svelte ``` # $effect 效果是在状态更新时运行的函数，可用于调用第三方库、绘制 `` 元素或发出网络请求等。它们仅在浏览器中运行，而不是在服务器端渲染期间运行。 ¥Effects are functions that run when state updates, and can be used for things like calling third-party libraries, drawing on `` elements, or making network requests. They only run in the browser, not during server-side rendering. 一般来说，你不应该在效果中更新状态，因为这会使代码更加复杂，并且经常导致永无止境的更新周期。如果你发现自己这样做了，请参阅 [何时不使用 `$effect`](#When-not-to-use-$effect) 以了解替代方法。 ¥Generally speaking, you should *not* update state inside effects, as it will make code more convoluted and will often lead to never-ending update cycles. If you find yourself doing so, see [when not to use `$effect`](#When-not-to-use-$effect) to learn about alternative approaches. 你可以使用 `$effect` 符文 ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE31S246bMBD9lZF3pSRSAqTVvrCAVPUP2sdSKY4ZwJJjkD0hSVH-vbINuWxXfQH5zMyZc2ZmZLVUaFn6a2R06ZGlHmBrpvnBvb71fWQHVOSwPbf4GS46TajJspRlVhjZU1HqkhQSWPkHIYdXS5xw-Zas3ueI6FRn7qHFS11_xSRZhIxbFtcDtw7SJb1iXaOg5XIFeQGjzyPRaevYNOGZIJ8qogbpe8CWiy_VzEpTXiQUcvPDkSVrSNZz1UlW1N5eLcqmpdXUvaQ4BmqlhZNUCgxuzFHDqUWNAxrYeUM76AzsnOsdiJbrBp_71lKpn3RRbii-4P3f-IMsRxS-wcDV_bL4PmSdBa2wl7pKnbp8DMgVvJm8ZNskKRkEM_OzyOKQFkgqOYBQ3Nq89Ns0nbIl81vMFN-jKoLMTOr-SOBOJS-Z8f5Y6D1wdcR8dFqvEBdetK-PHwj-z-cH8oHPY54wRJ8Ys7iSQ3Bg3VA9azQbmC9k35kKzYa6PoVtfwbbKVnBixBiGn7Pq0rqJoUtHiCZwAM3jdTPWCVtr_glhVrhecIa3vuksJ_b7TqFs4DPyriSjd5IwoNNQaAmNI-ESfR2p8zimzvN1swdCkvJHPH6-_oX8o1SgcIDAAA=)) 创建效果： ¥You can create an effect with the `$effect` rune ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE31S246bMBD9lZF3pSRSAqTVvrCAVPUP2sdSKY4ZwJJjkD0hSVH-vbINuWxXfQH5zMyZc2ZmZLVUaFn6a2R06ZGlHmBrpvnBvb71fWQHVOSwPbf4GS46TajJspRlVhjZU1HqkhQSWPkHIYdXS5xw-Zas3ueI6FRn7qHFS11_xSRZhIxbFtcDtw7SJb1iXaOg5XIFeQGjzyPRaevYNOGZIJ8qogbpe8CWiy_VzEpTXiQUcvPDkSVrSNZz1UlW1N5eLcqmpdXUvaQ4BmqlhZNUCgxuzFHDqUWNAxrYeUM76AzsnOsdiJbrBp_71lKpn3RRbii-4P3f-IMsRxS-wcDV_bL4PmSdBa2wl7pKnbp8DMgVvJm8ZNskKRkEM_OzyOKQFkgqOYBQ3Nq89Ns0nbIl81vMFN-jKoLMTOr-SOBOJS-Z8f5Y6D1wdcR8dFqvEBdetK-PHwj-z-cH8oHPY54wRJ8Ys7iSQ3Bg3VA9azQbmC9k35kKzYa6PoVtfwbbKVnBixBiGn7Pq0rqJoUtHiCZwAM3jdTPWCVtr_glhVrhecIa3vuksJ_b7TqFs4DPyriSjd5IwoNNQaAmNI-ESfR2p8zimzvN1swdCkvJHPH6-_oX8o1SgcIDAAA=)): ```svelte ``` 当 Svelte 运行效果函数时，它会跟踪访问了哪些状态（和派生状态）（除非在 [`untrack`](svelte#untrack) 内部访问），并在该状态稍后发生变化时重新运行该函数。 ¥When Svelte runs an effect function, it tracks which pieces of state (and derived state) are accessed (unless accessed inside [`untrack`](svelte#untrack)), and re-runs the function when that state later changes. > [!NOTE] 如果你无法理解为什么你的 `$effect` 会重新运行或未运行，请参阅 [understanding dependencies](#Understanding-dependencies)。如果你之前使用过 Svelte 4，其触发效果与你可能习惯的 `$:` 块不同。 ### 了解生命周期(Understanding lifecycle) ¥Understanding lifecycle 你的效果在组件安装到 DOM 后运行，并在状态更改后的 [microtask](https://web.nodejs.cn/en-US/docs/Web/API/HTML_DOM_API/Microtask_guide) 中运行。重新运行是分批的（即在同一时刻更改 `color` 和 `size` 不会导致两次单独的运行），并且在应用任何 DOM 更新后发生。 ¥Your effects run after the component has been mounted to the DOM, and in a [microtask](https://web.nodejs.cn/en-US/docs/Web/API/HTML_DOM_API/Microtask_guide) after state changes. Re-runs are batched (i.e. changing `color` and `size` in the same moment won't cause two separate runs), and happen after any DOM updates have been applied. 你可以在任何地方使用 `$effect`，而不仅仅是在组件的顶层，只要在父效果运行时调用它即可。 ¥You can use `$effect` anywhere, not just at the top level of a component, as long as it is called while a parent effect is running. > [!NOTE] Svelte 在内部使用效果来表示模板中的逻辑和表达式 - 这就是当 `name` 发生变化时 `

hello {name}!

` 更新的方式。 效果可以返回拆卸函数，该函数将在效果重新运行（[demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE42SQVODMBCF_8pOxkPRKq3HCsx49K4n64xpskjGkDDJ0tph-O8uINo6HjxB3u7HvrehE07WKDbiyZEhi1osRWksRrF57gQdm6E2CKx_dd43zU3co6VB28mIf-nKO0JH_BmRRRVMQ8XWbXkAgfKtI8jhIpIkXKySu7lSG2tNRGZ1_GlYr1ZTD3ddYFmiosUigbyAbpC2lKbwWJkIB8ZhhxBQBWRSw6FCh3sM8GrYTthL-wqqku4N44TyqEgwF3lmRHr4Op0PGXoH31c5rO8mqV-eOZ49bikgtcHBL55tmhIkEMqg_cFB2TpFxjtg703we6NRL8HQFCS07oSUCZi6Rm04lz1yytIHBKoQpo1w6Gsm4gmyS8b8Y5PydeMdX8gwS2Ok4I-ov5NZtvQde95GMsccn_1wzNKfu3RZtS66cSl9lvL7qO1aIk7knbJGvefdtIOzi73M4bYvovUHDFk6AcX_0HRESxnpBOW_jfCDxIZCi_1L_wm4xGQ60wIAAA==)）之前立即运行。 ¥An effect can return a *teardown function* which will run immediately before the effect re-runs ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE42SQVODMBCF_8pOxkPRKq3HCsx49K4n64xpskjGkDDJ0tph-O8uINo6HjxB3u7HvrehE07WKDbiyZEhi1osRWksRrF57gQdm6E2CKx_dd43zU3co6VB28mIf-nKO0JH_BmRRRVMQ8XWbXkAgfKtI8jhIpIkXKySu7lSG2tNRGZ1_GlYr1ZTD3ddYFmiosUigbyAbpC2lKbwWJkIB8ZhhxBQBWRSw6FCh3sM8GrYTthL-wqqku4N44TyqEgwF3lmRHr4Op0PGXoH31c5rO8mqV-eOZ49bikgtcHBL55tmhIkEMqg_cFB2TpFxjtg703we6NRL8HQFCS07oSUCZi6Rm04lz1yytIHBKoQpo1w6Gsm4gmyS8b8Y5PydeMdX8gwS2Ok4I-ov5NZtvQde95GMsccn_1wzNKfu3RZtS66cSl9lvL7qO1aIk7knbJGvefdtIOzi73M4bYvovUHDFk6AcX_0HRESxnpBOW_jfCDxIZCi_1L_wm4xGQ60wIAAA==)). ```svelte

{count}

``` 当效果被销毁时，拆卸函数也会运行，当其父级被销毁（例如，卸载组件）或父级效果重新运行时会发生这种情况。 ¥Teardown functions also run when the effect is destroyed, which happens when its parent is destroyed (for example, a component is unmounted) or the parent effect re-runs. ### 了解依赖(Understanding dependencies) ¥Understanding dependencies `$effect` 会自动获取在其函数主体内同步读取的任何反应值（`$state`、`$derived`、`$props`）（包括通过函数调用间接读取）并将它们注册为依赖。当这些依赖发生变化时，`$effect` 会安排重新运行。 ¥`$effect` automatically picks up any reactive values (`$state`, `$derived`, `$props`) that are *synchronously* read inside its function body (including indirectly, via function calls) and registers them as dependencies. When those dependencies change, the `$effect` schedules a re-run. 如果 `$state` 和 `$derived` 直接在 `$effect` 内部使用（例如，在创建 [反应类](https://svelte.nodejs.cn/docs/svelte/$state#Classes) 期间），则这些值将不会被视为依赖。 ¥If `$state` and `$derived` are used directly inside the `$effect` (for example, during creation of a [reactive class](https://svelte.nodejs.cn/docs/svelte/$state#Classes)), those values will *not* be treated as dependencies. 异步读取的值（例如在 `await` 之后或在 `setTimeout` 内部）将不会被跟踪。在这里，当 `color` 更改时，画布将被重新绘制，但当 `size` 更改（[demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE31T246bMBD9lZF3pWSlBEirfaEQqdo_2PatVIpjBrDkGGQPJGnEv1e2IZfVal-wfHzmzJyZ4cIqqdCy9M-F0blDlnqArZjmB3f72XWRHVCRw_bc4me4aDWhJstSlllhZEfbQhekkMDKfwg5PFvihMvX5OXH_CJa1Zrb0-Kpqr5jkiwC48rieuDWQbqgZ6wqFLRcvkC-hYvnkWi1dWqa8ESQTxFRjfQWsOXiWzmr0sSLhEJu3p1YsoJkNUcdZUnN9dagrBu6FVRQHAM10sJRKgUG16bXcGxQ44AGdt7SDkTDdY02iqLHnJVU6hedlWuIp94JW6Tf8oBt_8GdTxlF0b4n0C35ZLBzXb3mmYn3ae6cOW74zj0YVzDNYXRHFt9mprNgHfZSl6mzml8CMoLvTV6wTZIUDEJv5us2iwMtiJRyAKG4tXnhl8O0yhbML0Wm-B7VNlSSSd31BG7z8oIZZ6dgIffAVY_5xdU9Qrz1Bnx8fCfwtZ7v8Qc9j3nB8PqgmMWlHIID6-bkVaPZwDySfWtKNGtquxQ23Qlsq2QJT0KIqb8dL0up6xQ2eIBkAg_c1FI_YqW0neLnFCqFpwmreedJYT7FVOBfwWRhXstZrSXiwKQjUhOZeMIleb5JZfHWn2Yq5pWEpmR7Hv-N_wEqT8hEEAAA=)）时则不会： ¥Values that are read *asynchronously* — after an `await` or inside a `setTimeout`, for example — will not be tracked. Here, the canvas will be repainted when `color` changes, but not when `size` changes ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE31T246bMBD9lZF3pWSlBEirfaEQqdo_2PatVIpjBrDkGGQPJGnEv1e2IZfVal-wfHzmzJyZ4cIqqdCy9M-F0blDlnqArZjmB3f72XWRHVCRw_bc4me4aDWhJstSlllhZEfbQhekkMDKfwg5PFvihMvX5OXH_CJa1Zrb0-Kpqr5jkiwC48rieuDWQbqgZ6wqFLRcvkC-hYvnkWi1dWqa8ESQTxFRjfQWsOXiWzmr0sSLhEJu3p1YsoJkNUcdZUnN9dagrBu6FVRQHAM10sJRKgUG16bXcGxQ44AGdt7SDkTDdY02iqLHnJVU6hedlWuIp94JW6Tf8oBt_8GdTxlF0b4n0C35ZLBzXb3mmYn3ae6cOW74zj0YVzDNYXRHFt9mprNgHfZSl6mzml8CMoLvTV6wTZIUDEJv5us2iwMtiJRyAKG4tXnhl8O0yhbML0Wm-B7VNlSSSd31BG7z8oIZZ6dgIffAVY_5xdU9Qrz1Bnx8fCfwtZ7v8Qc9j3nB8PqgmMWlHIID6-bkVaPZwDySfWtKNGtquxQ23Qlsq2QJT0KIqb8dL0up6xQ2eIBkAg_c1FI_YqW0neLnFCqFpwmreedJYT7XX8FVOBfwWRhXstZrSXiwKQjUhOZeMIleb5JZfHWn2Yq5pWEpmR7Hv-N_wEqT8hEEAAA=)): ```ts // @filename: index.ts declare let canvas: { width: number; height: number; getContext(type: '2d', options?: CanvasRenderingContext2DSettings): CanvasRenderingContext2D; }; declare let color: string; declare let size: number; // ---cut--- $effect(() => { const context = canvas.getContext('2d'); context.clearRect(0, 0, canvas.width, canvas.height); // this will re-run whenever `color` changes... context.fillStyle = color; setTimeout(() => { // ...but not when `size` changes context.fillRect(0, 0, size, size); }, 0); }); ``` 效果仅在其读取的对象发生变化时重新运行，而不是在其内部的属性发生变化时重新运行。（如果你想在开发时观察对象内部的变化，你可以使用 [`$inspect`]($inspect)。） ¥An effect only reruns when the object it reads changes, not when a property inside it changes. (If you want to observe changes *inside* an object at dev time, you can use [`$inspect`]($inspect).) ```svelte

{state.value} doubled is {derived.value}

``` 效果仅取决于它上次运行时读取的值。这对于具有条件代码的效果具有有趣的含义。 ¥An effect only depends on the values that it read the last time it ran. This has interesting implications for effects that have conditional code. 例如，如果下面代码片段中的 `condition` 是 `true`，则 `if` 块内的代码将运行并评估 `color`。因此，更改为 `condition` 或 `color` [将导致效果重新运行](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE21RQW6DMBD8ytaNBJHaJFLViwNIVZ8RcnBgXVk1xsILTYT4e20TQg89IOPZ2fHM7siMaJBx9tmaWpFqjQNlAKXEihx7YVJpdIyfRkY3G4gB8Pi97cPanRtQU8AuwuF_eNUaQuPlOMtc1SlLRWlKUo1tOwJflUikQHZtA0klzCDc64Imx0ANn8bInV1CDhtHgjClrsftcSXotluLybOUb3g4JJHhOZs5WZpuIS9gjNqkJKQP5e2ClrR4SMdZ13E4xZ8zTPOTJU2A2uE_PQ9COCI926_hTVarIU4hu_REPlBrKq2q73ycrf1N-vS4TMUsulaVg3EtR8H9rFgsg8uUsT1B2F9eshigZHBRpuaD0D3mY8Qm2BfB5N2YyRzdNEYVDy0Ja-WsFjcOUuP1HvFLWA6H3XuHTUSmmDV2--0TXonxsKbp7G9C6R__NONS-MFNvxj_d6mBAgAA)。 ¥For instance, if `condition` is `true` in the code snippet below, the code inside the `if` block will run and `color` will be evaluated. As such, changes to either `condition` or `color` [will cause the effect to re-run](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE21RQW6DMBD8ytaNBJHaJFLViwNIVZ8RcnBgXVk1xsILTYT4e20TQg89IOPZ2fHM7siMaJBx9tmaWpFqjQNlAKXEihx7YVJpdIyfRkY3G4gB8Pi97cPanRtQU8AuwuF_eNUaQuPlOMtc1SlLRWlKUo1tOwJflUikQHZtA0klzCDc64Imx0ANn8bInV1CDhtHgjClrsftcSXotluLybOUb3g4JJHhOZs5WZpuIS9gjNqkJKQP5e2ClrR4SMdZ13E4xZ8zTPOTJU2A2uE_PQ9COCI926_hTVarIU4hu_REPlBrKq2q73ycrf1N-vS4TMUsulaVg3EtR8H9rFgsg8uUsT1B2F9eshigZHBRpuaD0D3mY8Qm2BfB5N2YyRzdNEYVDy0Ja-WsFjcOUuP1HvFLWA6H3XuHTUSmmDV2--0TXonxsKbp7G9C6R__NONS-MFNvxj_d6mBAgAA). 相反，如果 `condition` 是 `false`，则不会评估 `color`，并且只有当 `condition` 发生变化时，效果才会重新运行。 ¥Conversely, if `condition` is `false`, `color` will not be evaluated, and the effect will *only* re-run again when `condition` changes. ```ts // @filename: ambient.d.ts declare module 'canvas-confetti' { interface ConfettiOptions { colors: string[]; } function confetti(opts?: ConfettiOptions): void; export default confetti; } // @filename: index.js // ---cut--- import confetti from 'canvas-confetti'; let condition = $state(true); let color = $state('#ff3e00'); $effect(() => { if (condition) { confetti({ colors: [color] }); } else { confetti(); } }); ``` ## `$effect.pre` 在极少数情况下，你可能需要在 DOM 更新之前运行代码。为此，我们可以使用 `$effect.pre` 符文： ¥In rare cases, you may need to run code *before* the DOM updates. For this we can use the `$effect.pre` rune: ```svelte
{#each messages as message}

{message}

{/each}
``` 除了时间之外，`$effect.pre` 的工作原理与 `$effect` 完全相同。 ¥Apart from the timing, `$effect.pre` works exactly like `$effect`. ## `$effect.tracking` `$effect.tracking` 符文是一项高级功能，可告诉你代码是否在跟踪上下文中运行，例如效果或模板内 ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAACn3PwYrCMBDG8VeZDYIt2PYeY8Dn2HrIhqkU08nQjItS-u6buAt7UDzmz8ePyaKGMWBS-nNRcmdU-hHUTpGbyuvI3KZvDFLal0v4qvtIgiSZUSb5eWSxPfWSc4oB2xDP1XYk8HHiSHkICeXKeruDDQ4Demlldv4y0rmq6z10HQwuJMxGVv4mVVXDwcJS0jP9u3knynwtoKz1vifT_Z9Jhm0WBCcOTlDD8kyspmML5qNpHg40jc3fFryJ0iWsp_UHgz3180oBAAA=))： ¥The `$effect.tracking` rune is an advanced feature that tells you whether or not the code is running inside a tracking context, such as an effect or inside your template ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAACn3PwYrCMBDG8VeZDYIt2PYeY8Dn2HrIhqkU08nQjItS-u6buAt7UDzmz8ePyaKGMWBS-nNRcmdU-hHUTpGbyuvI3KZvDFLal0v4qvtIgiSZUSb5eWSxPfWSc4oB2xDP1XYk8HHiSHkICeXKeruDDQ4Demlldv4y0rmq6z10HQwuJMxGVv4mVVXDwcJS0jP9u3knynwtoKz1vifT_Z9Jhm0WBCcOTlDD8kyspmML5qNpHg40jc3fFryJ0iWsp_UHgz3180oBAAA=)): ```svelte

in template: {$effect.tracking()}

``` 它用于实现像 [`createSubscriber`](/docs/svelte/svelte-reactivity#createSubscriber) 这样的抽象，它将创建监听器来更新反应值，但前提是这些值正在被跟踪（而不是例如在事件处理程序中读取）。 ¥It is used to implement abstractions like [`createSubscriber`](/docs/svelte/svelte-reactivity#createSubscriber), which will create listeners to update reactive values but *only* if those values are being tracked (rather than, for example, read inside an event handler). ## `$effect.root` `$effect.root` 符文是一项高级功能，可创建不会自动清理的非跟踪范围。这对于你想要手动控制的嵌套效果很有用。此符文还允许在组件初始化阶段之外创建效果。 ¥The `$effect.root` rune is an advanced feature that creates a non-tracked scope that doesn't auto-cleanup. This is useful for nested effects that you want to manually control. This rune also allows for the creation of effects outside of the component initialisation phase. ```js const destroy = $effect.root(() => { $effect(() => { // setup }); return () => { // cleanup }; }); // later... destroy(); ``` ## 何时不使用 `$effect`(When not to use `$effect`) ¥When not to use `$effect` 一般来说，`$effect` 最好被视为一种应急方案 - 对于分析和直接 DOM 操作等有用 - 而不是你应该经常使用的工具。特别是，避免使用它来同步状态。而不是这样... ¥In general, `$effect` is best considered something of an escape hatch — useful for things like analytics and direct DOM manipulation — rather than a tool you should use frequently. In particular, avoid using it to synchronise state. Instead of this... ```svelte ``` ...执行以下操作： ¥...do this: ```svelte ``` > [!NOTE] 对于比 `count * 2` 这样的简单表达式更复杂的事情，你也可以使用 `$derived.by`。 如果你使用效果是因为你希望能够重新分配派生值（例如，构建乐观的 UI），请注意从 Svelte 5.25 开始的 [派生值可以直接覆盖]($derived#Overriding-derived-values)。 ¥If you're using an effect because you want to be able to reassign the derived value (to build an optimistic UI, for example) note that [deriveds can be directly overridden]($derived#Overriding-derived-values) as of Svelte 5.25. 你可能想做一些复杂的效果来将一个值链接到另一个值。以下示例显示了 "多页应用" 和 "花费金额" 的两个相互连接的输入。如果你更新一个，另一个应该相应更新。不要为此（[demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE5WRTWrDMBCFryKGLBJoY3fRjWIHeoiu6i6UZBwEY0VE49TB-O6VxrFTSih0qe_Ne_OjHpxpEDS8O7ZMeIAnqC1hAP3RA1990hKI_Fb55v06XJA4sZ0J-IjvT47RcYyBIuzP1vO2chVHHFjxiQ2pUr3k-SZRQlbBx_LIFoEN4zJfzQph_UMQr4hRXmBd456Xy5Uqt6pPKHmkfmzyPAZL2PCnbRpg8qWYu63I7lu4gswOSRYqrPNt3CgeqqzgbNwRK1A76w76YqjFspfcQTWmK3vJHlQm1puSTVSeqdOc_r9GaeCHfUSY26TXry6Br4RSK3C6yMEGT-aqVU3YbUZ2NF6rfP2KzXgbuYzY46czdgyazy0On_FlLH3F-UDXhgIO35UGlA1rAgAA)）使用效果： ¥You might be tempted to do something convoluted with effects to link one value to another. The following example shows two inputs for "money spent" and "money left" that are connected to each other. If you update one, the other should update accordingly. Don't use effects for this ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE5WRTWrDMBCFryKGLBJoY3fRjWIHeoiu6i6UZBwEY0VE49TB-O6VxrFTSih0qe_Ne_OjHpxpEDS8O7ZMeIAnqC1hAP3RA1990hKI_Fb55v06XJA4sZ0J-IjvT47RcYyBIuzP1vO2chVHHFjxiQ2pUr3k-SZRQlbBx_LIFoEN4zJfzQph_UMQr4hRXmBd456Xy5Uqt6pPKHmkfmzyPAZL2PCnbRpg8qWYu63I7lu4gswOSRYqrPNt3CgeqqzgbNwRK1A76w76YqjFspfcQTWmK3vJHlQm1puSTVSeqdOc_r9GaeCHfUSY26TXry6Br4RSK3C6yMEGT-aqVU3YbUZ2NF6rfP2KzXgbuYzY46czdgyazy0On_FlLH3F-UDXhgIO35UGlA1rAgAA)): ```svelte ``` 相反，使用 `oninput` 回调或 - 更好的是 - 在可能的情况下使用 [函数绑定](bind#Function-bindings)（[demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE5VRvW7CMBB-FcvqECQK6dDFJEgsnfoGTQdDLsjSxVjxhYKivHvPBwFUsXS8774_nwftbQva6I_e78gdvNo6Xzu_j3quG4cQtfkaNJ1DIiWA8atkE8IiHgEpYVsb4Rm-O3gCT2yji7jrXKB15StiOJKiA1lUpXrL81VCEUjFwHTGXiJZgiyf3TYIjSxq6NwR6uyifr0ohMbEZnpHH2rWf7ImS8KZGtK6osl_UqelRIyVL5b3ir5AuwWUtoXzoee6fIWy0p31e6i0XMocLfZQDuI6qtaeykGcR7UU6XWznFAZU9LN_X9B2UyVayk9f3ji0-REugen6U9upDOCcAWcLlS7GNCejWoQTqsLtrfBqHzxDu3DrUTOf0xwIm2o62H85sk6_OHG2jQWI4y_3byXXGMCAAA=)）： ¥Instead, use `oninput` callbacks or — better still — [function bindings](bind#Function-bindings) where possible ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE5VRvW7CMBB-FcvqECQK6dDFJEgsnfoGTQdDLsjSxVjxhYKivHvPBwFUsXS8774_nwftbQva6I_e78gdvNo6Xzu_j3quG4cQtfkaNJ1DIiWA8atkE8IiHgEpYVsb4Rm-O3gCT2yji7jrXKB15StiOJKiA1lUpXrL81VCEUjFwHTGXiJZgiyf3TYIjSxq6NwR6uyifr0ohMbEZnpHH2rWf7ImS8KZGtK6osl_UqelRIyVL5b3ir5AuwWUtoXzoee6fIWy0p31e6i0XMocLfZQDuI6qtaeykGcR7UU6XWznFAZU9LN_X9B2UyVayk9f3ji0-REugen6U9upDOCcAWcLlS7GNCejWoQTqsLtrfBqHzxDu3DrUTOf0xwIm2o62H85sk6_OHG2jQWI4y_3byXXGMCAAA=)): ```svelte ``` 如果你绝对必须在效果内更新 `$state` 并因为你读取和写入相同的 `$state` 而陷入无限循环，请使用 [untrack](svelte#untrack)。 ¥If you absolutely have to update `$state` within an effect and run into an infinite loop because you read and write to the same `$state`, use [untrack](svelte#untrack). # $props 组件的输入称为 props，是属性的缩写。你将 props 传递给组件就像你将属性传递给元素一样： ¥The inputs to a component are referred to as *props*, which is short for *properties*. You pass props to components just like you pass attributes to elements: ```svelte ``` 另一方面，在 `MyComponent.svelte` 内部，我们可以使用 `$props` 符文接收属性…… ¥On the other side, inside `MyComponent.svelte`, we can receive props with the `$props` rune... ```svelte

this component is {props.adjective}

``` ...但是更常见的是，你会 [destructure](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) 你的 props： ¥...though more commonly, you'll [*destructure*](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) your props: ```svelte

this component is {+++adjective+++}

``` ## 后备值(Fallback values) ¥Fallback values 解构允许我们声明回退值，当父组件未设置给定 prop（或值为 `undefined`）时使用这些值： ¥Destructuring allows us to declare fallback values, which are used if the parent component does not set a given prop (or the value is `undefined`): ```js let { adjective = 'happy' } = $props(); ``` > [!NOTE] 回退值不会转换为响应式状态代理（更多信息请参阅 [Updating props](#Updating-props)） ## 重命名 props(Renaming props) ¥Renaming props 我们还可以使用解构赋值来重命名 props，如果它们是无效标识符或 JavaScript 关键字（如 `super`），则这是必需的： ¥We can also use the destructuring assignment to rename props, which is necessary if they're invalid identifiers, or a JavaScript keyword like `super`: ```js let { super: trouper = 'lights are gonna find me' } = $props(); ``` ## Rest 属性(Rest props) ¥Rest props 最后，我们可以使用 rest 属性来获取其余的 props： ¥Finally, we can use a *rest property* to get, well, the rest of the props: ```js let { a, b, c, ...others } = $props(); ``` ## 更新属性(Updating props) ¥Updating props 当 prop 本身更新时，对组件内部 prop 的引用也会更新 - 当 `count` 在 `App.svelte` 中更改时，它也会在 `Child.svelte` 中更改。但子组件能够暂时覆盖 prop 值，这对于未保存的短暂状态（[demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE6WQ0WrDMAxFf0WIQR0Wmu3VTQJln7HsIfVcZubIxlbGRvC_DzuBraN92qPula50tODZWB1RPi_IX16jLALWSOOUq6P3-_ihLWftNEZ9TVeOWBNHlNhGFYznfqCBzeRdYHh6M_YVzsFNsNs3pdpGd4eBcqPVDMrNxNDBXeSRtXioDgO1zU8ataeZ2RE4Utao924RFXQ9iHXwvoPHKpW1xY4g_Bg0cSVhKS0p560Za95612ZC02ONrD8ZJYdZp_rGQ37ff_mSP86Np2TWZaNNmdcH56P4P67K66_SXoK9pG-5dF5Z9QEAAA==)）很有用： ¥References to a prop inside a component update when the prop itself updates — when `count` changes in `App.svelte`, it will also change inside `Child.svelte`. But the child component is able to temporarily override the prop value, which can be useful for unsaved ephemeral state ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE6WQ0WrDMAxFf0WIQR0Wmu3VTQJln7HsIfVcZubIxlbGRvC_DzuBraN92qPula50tODZWB1RPi_IX16jLALWSOOUq6P3-_ihLWftNEZ9TVeOWBNHlNhGFYznfqCBzeRdYHh6M_YVzsFNsNs3pdpGd4eBcqPVDMrNxNDBXeSRtXioDgO1zU8ataeZ2RE4Utao924RFXQ9iHXwvoPHKpW1xY4g_Bg0cSVhKS0p560Za95612ZC02ONrD8ZJYdZp_rGQ37ff_mSP86Np2TWZaNNmdcH56P4P67K66_SXoK9pG-5dF5Z9QEAAA==)): ```svelte ``` ```svelte ``` 虽然你可以暂时重新分配属性，但除非它们是 [bindable]($bindable)，否则你不应该改变属性。 ¥While you can temporarily *reassign* props, you should not *mutate* props unless they are [bindable]($bindable). 如果 prop 是常规对象，则突变不会产生任何影响（[demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3WQwU7DMBBEf2W1QmorQgJXk0RC3PkBwiExG9WQrC17U4Es_ztKUkQp9OjxzM7bjcjtSKjwyfKNp1aLORA4b13ADHszUED1HFE-3eyaBcy-Mw_O5eFAg8xa1wb6T9eWhVgCKiyD9sZJ3XAjZnTWCzzuzfAKvbcjbPJieR2jm_uGy-InweXqtd0baaliBG0nFgW3kBIUNWYo9CGoxE-UsgvIpw2_oc9-LmAPJBCPDJCggqvlVtvdH9puErEMlvVg9HsVtzuoaojzkKKAfRuALVDfk5ZZW0fmy05wXcFdwyktlUs-KIinljTXrRVnm7-kL9dYLVbUAQAA)）： ¥If the prop is a regular object, the mutation will have no effect ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3WQwU7DMBBEf2W1QmorQgJXk0RC3PkBwiExG9WQrC17U4Es_ztKUkQp9OjxzM7bjcjtSKjwyfKNp1aLORA4b13ADHszUED1HFE-3eyaBcy-Mw_O5eFAg8xa1wb6T9eWhVgCKiyD9sZJ3XAjZnTWCzzuzfAKvbcjbPJieR2jm_uGy-InweXqtd0baaliBG0nFgW3kBIUNWYo9CGoxE-UsgvIpw2_oc9-LmAPJBCPDJCggqvlVtvdH9puErEMlvVg9HsVtzuoaojzkKKAfRuALVDfk5ZZW0fmy05wXcFdwyktlUs-KIinljTXrRVnm7-kL9dYLVbUAQAA)): ```svelte ``` ```svelte ``` 但是，如果 prop 是反应状态代理，则突变会产生影响，但你会看到 [`ownership_invalid_mutation`](runtime-warnings#Client-warnings-ownership_invalid_mutation) 警告，因为组件正在改变不会 'belong' 的状态（[demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3WR0U7DMAxFf8VESBuiauG1WycheOEbKA9p67FA6kSNszJV-XeUZhMw2GN8r-1znUmQ7FGU4pn2UqsOes-SlSGRia3S6ET5Mgk-2OiJBZGdOh6szd0eNcdaIx3-V28NMRI7UYq1awdleVNTzaq3ZmB43CndwXYwPSzyYn4dWxermqJRI4Np3rFlqODasWRcTtAaT1zCHYSbVU3r4nsyrdPMKTUFKDYiE4yfLEoePIbsQpqfy3_nOVMuJIqg0wk1RFg7GOuWfwEbz2wIDLVatR_VtLyBagNTHFIUMCqtoZXeIfAOU1JoUJsR2IC3nWTMjt7GM4yKdyBhlAMpesvhydCC0y_i0ZagHByMh26WzUhXUUxKnpbcVnBfUwhznJnNlac7JkuIURL-2VVfwxflyrWcSQIAAA==)）： ¥If the prop is a reactive state proxy, however, then mutations *will* have an effect but you will see an [`ownership_invalid_mutation`](runtime-warnings#Client-warnings-ownership_invalid_mutation) warning, because the component is mutating state that does not 'belong' to it ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3WR0U7DMAxFf8VESBuiauG1WycheOEbKA9p67FA6kSNszJV-XeUZhMw2GN8r-1znUmQ7FGU4pn2UqsOes-SlSGRia3S6ET5Mgk-2OiJBZGdOh6szd0eNcdaIx3-V28NMRI7UYq1awdleVNTzaq3ZmB43CndwXYwPSzyYn4dWxermqJRI4Np3rFlqODasWRcTtAaT1zCHYSbVU3r4nsyrdPMKTUFKDYiE4yfLEoePIbsQpqfy3_nOVMuJIqg0wk1RFg7GOuWfwEbz2wIDLVatR_VtLyBagNTHFIUMCqtoZXeIfAOU1JoUJsR2IC3nWTMjt7GM4yKdyBhlAMpesvhydCC0y_i0ZagHByMh26WzUhXUUxKnpbcVnBfUwhznJnNlac7JkuIURL-2VVfwxflyrWcSQIAAA==)): ```svelte ``` ```svelte ``` 未使用 `$bindable` 声明的 prop 的 fallback 值保持不变 — 它不会变成反应状态代理 — 这意味着突变不会导致更新（[demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3WQwU7DMBBEf2VkIbUVoYFraCIh7vwA4eC4G9Wta1vxpgJZ_nfkBEQp9OjxzOzTRGHlkUQlXpy9G0gq1idCL43ppDrAD84HUYheGwqieo2CP3y2Z0EU3-En79fhRIaz1slA_-nKWSbLQVRiE9SgPTetbVkfvRsYzztttugHd8RiXU6vr-jisbWb8idhN7O3bEQhmN5ZVDyMlIorcOddv_Eufq4AGmJEuG5PilEjQrnRcoV7JCTUuJlGWq7-YHYjs7NwVhmtDnVcrlA3iLmzLLGTAdaB-j736h68Oxv-JM1I0AFjoG1OzPfX023c1nhobUoT39QeKsRzS8owM8DFTG_pE6dcVl70AQAA)） ¥The fallback value of a prop not declared with `$bindable` is left untouched — it is not turned into a reactive state proxy — meaning mutations will not cause updates ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3WQwU7DMBBEf2VkIbUVoYFraCIh7vwA4eC4G9Wta1vxpgJZ_nfkBEQp9OjxzOzTRGHlkUQlXpy9G0gq1idCL43ppDrAD84HUYheGwqieo2CP3y2Z0EU3-En79fhRIaz1slA_-nKWSbLQVRiE9SgPTetbVkfvRsYzztttugHd8RiXU6vr-jisbWb8idhN7O3bEQhmN5ZVDyMlIorcOddv_Eufq4AGmJEuG5PilEjQrnRcoV7JCTUuJlGWq7-YHYjs7NwVhmtDnVcrlA3iLmzLLGTAdaB-j736h68Oxv-JM1I0AFjoG1OzPfX023c1nhobUoT39QeKsRzS8owM8DFTG_pE6dcVl70AQAA)) ```svelte ``` 总结：别担心，我知道我的意思使用回调 props 来传达更改，或者 - 如果父级和子级应该共享同一个对象 - 使用 [`$bindable`]($bindable) 符文。 ¥In summary: don't mutate props. Either use callback props to communicate changes, or — if parent and child should share the same object — use the [`$bindable`]($bindable) rune. ## 类型安全(Type safety) ¥Type safety 你可以通过注释你的 props 为你的组件添加类型安全性，就像你对任何其他变量声明所做的那样。在 TypeScript 中可能看起来像这样...... ¥You can add type safety to your components by annotating your props, as you would with any other variable declaration. In TypeScript that might look like this... ```svelte ``` ...而在 JSDoc 中你可以这样做： ¥...while in JSDoc you can do this: ```svelte ``` 当然，你可以将类型声明与注释分开： ¥You can, of course, separate the type declaration from the annotation: ```svelte ``` > [!NOTE] `svelte/elements` 模块提供了原生 DOM 元素的接口（参见 [Typing wrapper components](typescript#Typing-wrapper-components)）。 建议添加类型，因为它可以确保使用组件的人可以轻松发现他们应该提供哪些属性。 ¥Adding types is recommended, as it ensures that people using your component can easily discover which props they should provide. ## `$props.id()` 此符文在版本 5.20.0 中添加，生成当前组件实例唯一的 ID。当对服务器渲染的组件进行水合时，服务器和客户端之间的值将保持一致。 ¥This rune, added in version 5.20.0, generates an ID that is unique to the current component instance. When hydrating a server-rendered component, the value will be consistent between server and client. 这对于通过 `for` 和 `aria-labelledby` 等属性链接元素很有用。 ¥This is useful for linking elements via attributes like `for` and `aria-labelledby`. ```svelte
``` # $bindable 通常，props 是单向的，从父级到子级。这使得你很容易理解数据在你的应用中是如何流动的。 ¥Ordinarily, props go one way, from parent to child. This makes it easy to understand how data flows around your app. 在 Svelte 中，组件 props 可以绑定，这意味着数据也可以从子级流到父级。这不是你应该经常做的事情，但如果谨慎使用，它可以简化你的代码。 ¥In Svelte, component props can be *bound*, which means that data can also flow *up* from child to parent. This isn't something you should do often, but it can simplify your code if used sparingly and carefully. 它还意味着可以在子元素中改变状态代理。 ¥It also means that a state proxy can be *mutated* in the child. > [!NOTE] 普通 props 也可以进行修改，但强烈建议不要这样做 - 如果 Svelte 检测到组件正在修改其未指定 'own' 的状态，它会发出警告。 要将 prop 标记为可绑定，我们使用 `$bindable` 符文： ¥To mark a prop as bindable, we use the `$bindable` rune: ```svelte /// file: FancyInput.svelte ``` 现在，使用 `` 的组件可以添加 [`bind:`](bind) 指令（[demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3WQwWrDMBBEf2URBSfg2nfFMZRCoYeecqx6UJx1IyqvhLUONcb_XqSkTUOSk1az7DBvJtEai0HI90nw6FHIJIhckO7i78n7IhzQctS2OuAtvXHESByEFFVoeuO5VqTYdN71DC-amvGV_MDQ9q6DrCjP0skkWymKJxYZOgxBfyKs4SGwZlxke7TWZcuVoqo8-1P1z3lraCcP2g64nk4GM5S1osrXf0JV-lrkgvGbheR-wDm_g30V8JL-1vpOCZFogpQsEsWcemtxscyhKArfOx9gjps0Lq4hzRVfemaYfu-PoIqqwKPFY_XpaIqj4tYRP7a6M3aUkD27zjSw0RTgbZN6Z8WNs66XsEP03tBXUueUJFlelvYx_wCuI3leNwIAAA==)）： ¥Now, a component that uses `` can add the [`bind:`](bind) directive ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3WQwWrDMBBEf2URBSfg2nfFMZRCoYeecqx6UJx1IyqvhLUONcb_XqSkTUOSk1az7DBvJtEai0HI90nw6FHIJIhckO7i78n7IhzQctS2OuAtvXHESByEFFVoeuO5VqTYdN71DC-amvGV_MDQ9q6DrCjP0skkWymKJxYZOgxBfyKs4SGwZlxke7TWZcuVoqo8-1P1z3lraCcP2g64nk4GM5S1osrXf0JV-lrkgvGbheR-wDm_g30V8JL-1vpOCZFogpQsEsWcemtxscyhKArfOx9gjps0Lq4hzRVfemaYfu-PoIqqwKPFY_XpaIqj4tYRP7a6M3aUkD27zjSw0RTgbZN6Z8WNs66XsEP03tBXUueUJFlelvYx_wCuI3leNwIAAA==)): ```svelte /// file: App.svelte

{message}

``` 父组件不必使用 `bind:` — 它只需传递普通 prop。有些父级不想听子级说些什么。 ¥The parent component doesn't *have* to use `bind:` — it can just pass a normal prop. Some parents don't want to listen to what their children have to say. 在这种情况下，你可以为根本没有传递任何 prop 的情况指定一个后备值： ¥In this case, you can specify a fallback value for when no prop is passed at all: ```js /// file: FancyInput.svelte let { value = $bindable('fallback'), ...props } = $props(); ``` # $inspect > [!NOTE] `$inspect` 仅在开发期间有效。在生产版本中，它将变为空操作。 `$inspect` 符文大致相当于 `console.log`，不同之处在于它会在其参数发生变化时重新运行。`$inspect` 深度跟踪反应状态，这意味着使用细粒度反应更新对象或数组内部的某些内容将导致其重新触发（[demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAACkWQ0YqDQAxFfyUMhSotdZ-tCvu431AXtGOqQ2NmmMm0LOK_r7Utfby5JzeXTOpiCIPKT5PidkSVq2_n1F7Jn3uIcEMSXHSw0evHpAjaGydVzbUQCmgbWaCETZBWMPlKj29nxBDaHj_edkAiu12JhdkYDg61JGvE_s2nR8gyuBuiJZuDJTyQ7eE-IEOzog1YD80Lb0APLfdYc5F9qnFxjiKWwbImo6_llKRQVs-2u91c_bD2OCJLkT3JZasw7KLA2XCX31qKWE6vIzNk1fKE0XbmYrBTufiI8-_8D2cUWBA_AQAA)）： ¥The `$inspect` rune is roughly equivalent to `console.log`, with the exception that it will re-run whenever its argument changes. `$inspect` tracks reactive state deeply, meaning that updating something inside an object or array using fine-grained reactivity will cause it to re-fire ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAACkWQ0YqDQAxFfyUMhSotdZ-tCvu431AXtGOqQ2NmmMm0LOK_r7Utfby5JzeXTOpiCIPKT5PidkSVq2_n1F7Jn3uIcEMSXHSw0evHpAjaGydVzbUQCmgbWaCETZBWMPlKj29nxBDaHj_edkAiu12JhdkYDg61JGvE_s2nR8gyuBuiJZuDJTyQ7eE-IEOzog1YD80Lb0APLfdYc5F9qnFxjiKWwbImo6_llKRQVs-2u91c_bD2OCJLkT3JZasw7KLA2XCX31qKWE6vIzNk1fKE0XbmYrBTufiI8-_8D2cUWBA_AQAA)): ```svelte ``` ## $inspect(...).with `$inspect` 返回一个属性 `with`，你可以使用回调来调用它，然后将调用回调而不是 `console.log`。回调的第一个参数是 `"init"` 或 `"update"`；后续参数是传递给 `$inspect` ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAACkVQ24qDMBD9lSEUqlTqPlsj7ON-w7pQG8c2VCchmVSK-O-bKMs-DefKYRYx6BG9qL4XQd2EohKf1opC8Nsm4F84MkbsTXAqMbVXTltuWmp5RAZlAjFIOHjuGLOP_BKVqB00eYuKs82Qn2fNjyxLtcWeyUE2sCRry3qATQIpJRyD7WPVMf9TW-7xFu53dBcoSzAOrsqQNyOe2XUKr0Xi5kcMvdDB2wSYO-I9vKazplV1-T-d6ltgNgSG1KjVUy7ZtmdbdjqtzRcphxMS1-XubOITJtPrQWMvKnYB15_1F7KKadA_AQAA)) 的值： ¥`$inspect` returns a property `with`, which you can invoke with a callback, which will then be invoked instead of `console.log`. The first argument to the callback is either `"init"` or `"update"`; subsequent arguments are the values passed to `$inspect` ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAACkVQ24qDMBD9lSEUqlTqPlsj7ON-w7pQG8c2VCchmVSK-O-bKMs-DefKYRYx6BG9qL4XQd2EohKf1opC8Nsm4F84MkbsTXAqMbVXTltuWmp5RAZlAjFIOHjuGLOP_BKVqB00eYuKs82Qn2fNjyxLtcWeyUE2sCRry3qATQIpJRyD7WPVMf9TW-7xFu53dBcoSzAOrsqQNyOe2XUKr0Xi5kcMvdDB2wSYO-I9vKazplV1-T-d6ltgNgSG1KjVUy7ZtmdbdjqtzRcphxMS1-XubOITJtPrQWMvKnYB15_1F7KKadA_AQAA)): ```svelte ``` 查找某些更改的起源的一种方便方法是将 `console.trace` 传递给 `with`： ¥A convenient way to find the origin of some change is to pass `console.trace` to `with`: ```js // @errors: 2304 $inspect(stuff).with(console.trace); ``` ## $inspect.trace(...) 此符文在 5.14 中添加，导致在开发中跟踪周围的函数。任何时候函数作为 [effect]($effect) 或 [derived]($derived) 的一部分重新运行时，都会将有关哪些反应状态导致效果触发的信息打印到控制台。 ¥This rune, added in 5.14, causes the surrounding function to be *traced* in development. Any time the function re-runs as part of an [effect]($effect) or a [derived]($derived), information will be printed to the console about which pieces of reactive state caused the effect to fire. ```svelte ``` `$inspect.trace` 采用可选的第一个参数，该参数将用作标签。 ¥`$inspect.trace` takes an optional first argument which will be used as the label. # $host 将组件编译为 [自定义元素](custom-elements) 时，`$host` 符文会提供对宿主元素的访问，允许你（例如）调度自定义事件 ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE41Ry2rDMBD8FSECtqkTt1fHFpSSL-ix7sFRNkTEXglrnTYY_3uRlDgxTaEHIfYxs7szA9-rBizPPwZOZwM89wmecqxbF70as7InaMjltrWFR3mpkQDJ8pwXVnbKkKiwItUa3RGLVtk7gTHQXRDR2lXda4CY1D0SK9nCUk0QPyfrCovsRoNFe17aQOAwGncgO2gBqRzihJXiQrEs2csYOhQ-7HgKHaLIbpRhhBG-I2eD_8ciM4KnnOCbeE5dD2P6h0Dz0-Yi_arNhPLJXBtSGi2TvSXdbpqwdsXvjuYsC1veabvvUTog2ylrapKH2G2XsMFLS4uDthQnq2t1cwKkGOGLvYU5PvaQxLsxOkPmsm97Io1Mo2yUPF6VnOZFkw1RMoopKLKAE_9gmGxyDFMwMcwN-Bx_ABXQWmOtAgAA))： ¥When compiling a component as a [custom element](custom-elements), the `$host` rune provides access to the host element, allowing you to (for example) dispatch custom events ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE41Ry2rDMBD8FSECtqkTt1fHFpSSL-ix7sFRNkTEXglrnTYY_3uRlDgxTaEHIfYxs7szA9-rBizPPwZOZwM89wmecqxbF70as7InaMjltrWFR3mpkQDJ8pwXVnbKkKiwItUa3RGLVtk7gTHQXRDR2lXda4CY1D0SK9nCUk0QPyfrCovsRoNFe17aQOAwGncgO2gBqRzihJXiQrEs2csYOhQ-7HgKHaLIbpRhhBG-I2eD_8ciM4KnnOCbeE5dD2P6h0Dz0-Yi_arNhPLJXBtSGi2TvSXdbpqwdsXvjuYsC1veabvvUTog2ylrapKH2G2XsMFLS4uDthQnq2t1cwKkGOGLvYU5PvaQxLsxOkPmsm97Io1Mo2yUPF6VnOZFkw1RMoopKLKAE_9gmGxyDFMwMcwN-Bx_ABXQWmOtAgAA)): ```svelte /// file: Stepper.svelte ``` ```svelte /// file: App.svelte count -= 1} onincrement={() => count += 1} >

count: {count}

``` # 基本标记 Svelte 组件内的标记可以被视为 HTML++。 ¥Markup inside a Svelte component can be thought of as HTML++. ## 标签(Tags) ¥Tags 小写标签（如 `
`）表示常规 HTML 元素。大写标记或使用点符号的标记（例如 `` 或 ``）表示组件。 ¥A lowercase tag, like `
`, denotes a regular HTML element. A capitalised tag or a tag that uses dot notation, such as `` or ``, indicates a *component*. ```svelte
``` ## 元素属性(Element attributes) ¥Element attributes 默认情况下，属性的工作方式与其 HTML 对应项完全相同。 ¥By default, attributes work exactly like their HTML counterparts. ```svelte
``` 与 HTML 中一样，值可以不加引号。 ¥As in HTML, values may be unquoted. ```svelte ``` 属性值可以包含 JavaScript 表达式。 ¥Attribute values can contain JavaScript expressions. ```svelte page {p} ``` 或者它们可以是 JavaScript 表达式。 ¥Or they can *be* JavaScript expressions. ```svelte ``` 如果布尔属性的值为 [truthy](https://web.nodejs.cn/en-US/docs/Glossary/Truthy)，则将其包含在元素中，如果值为 [falsy](https://web.nodejs.cn/en-US/docs/Glossary/Falsy)，则将其排除。 ¥Boolean attributes are included on the element if their value is [truthy](https://web.nodejs.cn/en-US/docs/Glossary/Truthy) and excluded if it's [falsy](https://web.nodejs.cn/en-US/docs/Glossary/Falsy). 除非其他属性的值为 [nullish](https://web.nodejs.cn/en-US/docs/Glossary/Nullish)（`null` 或 `undefined`），否则将包含所有其他属性。 ¥All other attributes are included unless their value is [nullish](https://web.nodejs.cn/en-US/docs/Glossary/Nullish) (`null` or `undefined`). ```svelte
This div has no title attribute
``` > [!NOTE] 引用单个表达式不会影响值的解析方式，但在 Svelte 6 中，它会导致值被强制转换为字符串： > > > ```svelte > > ``` 当属性名称和值匹配（`name={name}`）时，可以将它们替换为 `{name}`。 ¥When the attribute name and value match (`name={name}`), they can be replaced with `{name}`. ```svelte ``` ## 组件属性(Component props) ¥Component props 按照惯例，传递给组件的值被称为属性或属性，而不是属性，这是 DOM 的一个功能。 ¥By convention, values passed to components are referred to as *properties* or *props* rather than *attributes*, which are a feature of the DOM. 与元素一样，`name={name}` 可以用 `{name}` 简写替换。 ¥As with elements, `name={name}` can be replaced with the `{name}` shorthand. ```svelte ``` ## 展开属性(Spread attributes) ¥Spread attributes 扩展属性允许将许多属性或属性一次传递到元素或组件。 ¥*Spread attributes* allow many attributes or properties to be passed to an element or component at once. 一个元素或组件可以具有多个散布属性，这些属性散布在常规属性中。顺序很重要 - 如果 `things.a` 存在，它将优先于 `a="b"`，而 `c="d"` 优先于 `things.c`： ¥An element or component can have multiple spread attributes, interspersed with regular ones. Order matters — if `things.a` exists it will take precedence over `a="b"`, while `c="d"` would take precedence over `things.c`: ```svelte ``` ## 事件(Events) ¥Events 通过向以 `on` 开头的元素添加属性，可以监听 DOM 事件。例如，要监听 `click` 事件，请将 `onclick` 属性添加到按钮： ¥Listening to DOM events is possible by adding attributes to the element that start with `on`. For example, to listen to the `click` event, add the `onclick` attribute to a button: ```svelte ``` 事件属性区分大小写。`onclick` 监听 `click` 事件，`onClick` 监听 `Click` 事件，这是不同的。这可确保你可以监听包含大写字符的自定义事件。 ¥Event attributes are case sensitive. `onclick` listens to the `click` event, `onClick` listens to the `Click` event, which is different. This ensures you can listen to custom events that have uppercase characters in them. 因为事件只是属性，所以适用与属性相同的规则： ¥Because events are just attributes, the same rules as for attributes apply: * 你可以使用简写形式：`` ¥you can use the shorthand form: `` * 你可以传播它们：`` ¥you can spread them: `` 从时间上讲，事件属性始终在绑定事件之后触发（例如，`oninput` 始终在更新到 `bind:value` 之后触发）。在底层，一些事件处理程序直接与 `addEventListener` 连接，而其他事件处理程序则是委托的。 ¥Timing-wise, event attributes always fire after events from bindings (e.g. `oninput` always fires after an update to `bind:value`). Under the hood, some event handlers are attached directly with `addEventListener`, while others are *delegated*. 使用 `ontouchstart` 和 `ontouchmove` 事件属性时，处理程序为 [passive](https://web.nodejs.cn/en-US/docs/Web/API/EventTarget/addEventListener#using_passive_listeners)，以获得更好的性能。通过允许浏览器立即滚动文档，而不是等待查看事件处理程序是否调用 `event.preventDefault()`，这极大地提高了响应能力。 ¥When using `ontouchstart` and `ontouchmove` event attributes, the handlers are [passive](https://web.nodejs.cn/en-US/docs/Web/API/EventTarget/addEventListener#using_passive_listeners) for better performance. This greatly improves responsiveness by allowing the browser to scroll the document immediately, rather than waiting to see if the event handler calls `event.preventDefault()`. 在极少数情况下，你需要防止这些事件默认值，你应该改用 [`on`](svelte-events#on)（例如在操作内部）。 ¥In the very rare cases that you need to prevent these event defaults, you should use [`on`](svelte-events#on) instead (for example inside an action). ### 事件委托(Event delegation) ¥Event delegation 为了减少内存占用并提高性能，Svelte 使用了一种称为事件委托的技术。这意味着对于某些事件（请参阅下面的列表），应用根目录中的单个事件监听器负责运行事件路径上的任何处理程序。 ¥To reduce memory footprint and increase performance, Svelte uses a technique called event delegation. This means that for certain events — see the list below — a single event listener at the application root takes responsibility for running any handlers on the event's path. 有几个需要注意的陷阱： ¥There are a few gotchas to be aware of: * 当你使用委托监听器手动分派事件时，请确保设置 `{ bubbles: true }` 选项，否则它将无法到达应用根 ¥when you manually dispatch an event with a delegated listener, make sure to set the `{ bubbles: true }` option or it won't reach the application root * 直接使用 `addEventListener` 时，避免调用 `stopPropagation`，否则事件将无法到达应用根，处理程序将不会被调用。类似地，在应用根目录内手动添加的处理程序将在 DOM 中声明性地添加的处理程序（例如 `onclick={...}`）之前运行，无论是在捕获阶段还是冒泡阶段。出于这些原因，最好使用从 `svelte/events` 而不是 `addEventListener` 导入的 `on` 函数，因为它将确保保留顺序并正确处理 `stopPropagation`。 ¥when using `addEventListener` directly, avoid calling `stopPropagation` or the event won't reach the application root and handlers won't be invoked. Similarly, handlers added manually inside the application root will run *before* handlers added declaratively deeper in the DOM (with e.g. `onclick={...}`), in both capturing and bubbling phases. For these reasons it's better to use the `on` function imported from `svelte/events` rather than `addEventListener`, as it will ensure that order is preserved and `stopPropagation` is handled correctly. 以下事件处理程序被委托： ¥The following event handlers are delegated: * `beforeinput` * `click` * `change` * `dblclick` * `contextmenu` * `focusin` * `focusout` * `input` * `keydown` * `keyup` * `mousedown` * `mousemove` * `mouseout` * `mouseover` * `mouseup` * `pointerdown` * `pointermove` * `pointerout` * `pointerover` * `pointerup` * `touchend` * `touchmove` * `touchstart` ## 文本表达式(Text expressions) ¥Text expressions JavaScript 表达式可以通过用大括号括起来作为文本包含在内。 ¥A JavaScript expression can be included as text by surrounding it with curly braces. ```svelte {expression} ``` `null` 或 `undefined` 类型的表达式将被省略；其他均为 [强制转换为字符串](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion)。 ¥Expressions that are `null` or `undefined` will be omitted; all others are [coerced to strings](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion). 可以使用其 [HTML 实体](https://web.nodejs.cn/docs/Glossary/Entity) 字符串将大括号包含在 Svelte 模板中：`{` 为 `{`、`{` 或 `{`，`}` 为 `}`、`}` 或 `}`。 ¥Curly braces can be included in a Svelte template by using their [HTML entity](https://web.nodejs.cn/docs/Glossary/Entity) strings: `{`, `{`, or `{` for `{` and `}`, `}`, or `}` for `}`. 如果你使用的是正则表达式 (`RegExp`) [字面表示法](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#literal_notation_and_constructor)，则需要将其括在括号中。 ¥If you're using a regular expression (`RegExp`) [literal notation](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#literal_notation_and_constructor), you'll need to wrap it in parentheses. ```svelte

Hello {name}!

{a} + {b} = {a + b}.

{(/^[A-Za-z ]+$/).test(value) ? x : y}
``` 表达式将被字符串化并转义以防止代码注入。如果你想渲染 HTML，请改用 `{@html}` 标签。 ¥The expression will be stringified and escaped to prevent code injections. If you want to render HTML, use the `{@html}` tag instead. ```svelte {@html potentiallyUnsafeHtmlString} ``` > [!NOTE] 为了防止 [XSS attacks](https://owasp.org/www-community/attacks/xss/) 错误，请确保对传递的字符串进行转义，或者只使用你可控制的值填充它。 ## 注释(Comments) ¥Comments 你可以在组件内使用 HTML 注释。 ¥You can use HTML comments inside components. ```svelte

Hello world

``` 以 `svelte-ignore` 开头的注释将禁用下一个标记块的警告。通常，这些是可访问性警告；确保你出于充分的理由禁用它们。 ¥Comments beginning with `svelte-ignore` disable warnings for the next block of markup. Usually, these are accessibility warnings; make sure that you're disabling them for a good reason. ```svelte ``` 你可以添加以 `@component` 开头的特殊注释，当将鼠标悬停在其他文件中的组件名称上时会显示该注释。 ¥You can add a special comment starting with `@component` that will show up when hovering over the component name in other files. ````svelte

Hello, {name}

``` ` # {#if ...} ```svelte {#if expression}...{/if} ``` ```svelte {#if expression}...{:else if expression}...{/if} ``` ```svelte {#if expression}...{:else}...{/if} ``` 有条件渲染的内容可以封装在 if 块中。 ¥Content that is conditionally rendered can be wrapped in an if block. ```svelte {#if answer === 42}

what was the question?

{/if} ``` 可以使用 `{:else if expression}` 添加其他条件，可以选择以 `{:else}` 子句结尾。 ¥Additional conditions can be added with `{:else if expression}`, optionally ending in an `{:else}` clause. ```svelte {#if porridge.temperature > 100}

too hot!

{:else if 80 > porridge.temperature}

too cold!

{:else}

just right!

{/if} ``` （块不必封装元素，它们也可以封装元素内的文本。） ¥(Blocks don't have to wrap elements, they can also wrap text within elements.) # {#each ...} ```svelte {#each expression as name}...{/each} ``` ```svelte {#each expression as name, index}...{/each} ``` 可以使用 each 块对值进行迭代。所讨论的值可以是数组、类似数组的对象（即具有 `length` 属性的任何内容）或可迭代对象（如 `Map` 和 `Set`） — 换句话说，任何可以与 `Array.from` 一起使用的内容。 ¥Iterating over values can be done with an each block. The values in question can be arrays, array-like objects (i.e. anything with a `length` property), or iterables like `Map` and `Set` — in other words, anything that can be used with `Array.from`. ```svelte

Shopping list

    {#each items as item}
  • {item.name} x {item.qty}
    • {/each}
``` 每个块还可以指定一个索引，相当于 `array.map(...)` 回调中的第二个参数： ¥An each block can also specify an *index*, equivalent to the second argument in an `array.map(...)` callback: ```svelte {#each items as item, i}
  • {i + 1}: {item.name} x {item.qty}
    • {/each} ``` ## 为 each 块加键(Keyed each blocks) ¥Keyed each blocks ```svelte {#each expression as name (key)}...{/each} ``` ```svelte {#each expression as name, index (key)}...{/each} ``` 如果提供了键表达式（必须唯一地标识每个列表项），Svelte 将使用它在数据发生变化时智能地更新列表，例如插入、移动和删除项目，而不是在末尾添加或删除项目并在中间更新状态。 ¥If a *key* expression is provided — which must uniquely identify each list item — Svelte will use it to intelligently update the list when data changes by inserting, moving and deleting items, rather than adding or removing items at the end and updating the state in the middle. 键可以是任何对象，但建议使用字符串和数字，因为它们允许在对象本身更改时保留身份。 ¥The key can be any object, but strings and numbers are recommended since they allow identity to persist when the objects themselves change. ```svelte {#each items as item (item.id)}
  • {item.name} x {item.qty}
    • {/each} {#each items as item, i (item.id)}
  • {i + 1}: {item.name} x {item.qty}
    • {/each} ``` 你可以在每个块中自由使用解构和剩余模式。 ¥You can freely use destructuring and rest patterns in each blocks. ```svelte {#each items as { id, name, qty }, i (id)}
  • {i + 1}: {name} x {qty}
    • {/each} {#each objects as { id, ...rest }}
  • {id}
    • {/each} {#each items as [id, ...rest]}
  • {id}
    • {/each} ``` ## 每个块都没有项目(Each blocks without an item) ¥Each blocks without an item ```svelte {#each expression}...{/each} ``` ```svelte {#each expression, index}...{/each} ``` 如果你只想渲染 `n` 次，则可以省略 `as` 部分（[demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3WR0W7CMAxFf8XKNAk0WsSeUEaRpn3Guoc0MbQiJFHiMlDVf18SOrZJ48259_jaVgZmxBEZZ28thgCNFV6xBdt1GgPj7wOji0t2EqI-wa_OleGEmpLWiID_6dIaQkMxhm1UdwKpRQhVzWSaVORJNdvWpqbhAYVsYQCNZk8thzWMC_DCHMZk3wPSThNQ088I3mghD9UwSwHwlLE5PMIzVFUFq3G7WUZ2OyUvU3JOuZU332wCXTRmtPy1NgzXZtUFp8WFw9536uWqpbIgPEaDsJBW90cTOHh0KGi2XsBq5-cT6-3nPauxXqHnsHJnCFZ3CvJVkyuCQ0mFF9TZyCQ162WGvteLKfG197Y3iv_pz_fmS68Hxt8iPBPj5HscP8YvCNX7uhYCAAA=)）： ¥In case you just want to render something `n` times, you can omit the `as` part ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3WR0W7CMAxFf8XKNAk0WsSeUEaRpn3Guoc0MbQiJFHiMlDVf18SOrZJ48259_jaVgZmxBEZZ28thgCNFV6xBdt1GgPj7wOji0t2EqI-wa_OleGEmpLWiID_6dIaQkMxhm1UdwKpRQhVzWSaVORJNdvWpqbhAYVsYQCNZk8thzWMC_DCHMZk3wPSThNQ088I3mghD9UwSwHwlLE5PMIzVFUFq3G7WUZ2OyUvU3JOuZU332wCXTRmtPy1NgzXZtUFp8WFw9536uWqpbIgPEaDsJBW90cTOHh0KGi2XsBq5-cT6-3nPauxXqHnsHJnCFZ3CvJVkyuCQ0mFF9TZyCQ162WGvteLKfG197Y3iv_pz_fmS68Hxt8iPBPj5HscP8YvCNX7uhYCAAA=)): ```svelte
    {#each { length: 8 }, rank} {#each { length: 8 }, file}
    {/each} {/each}
    ``` ## else 块(Else blocks) ¥Else blocks ```svelte {#each expression as name}...{:else}...{/each} ``` 每个块还可以有一个 `{:else}` 子句，如果列表为空，则会渲染该子句。 ¥An each block can also have an `{:else}` clause, which is rendered if the list is empty. ```svelte {#each todos as todo}

    {todo.text}

    {:else}

    No tasks today!

    {/each} ``` # {#key ...} ```svelte {#key expression}...{/key} ``` 当表达式的值发生变化时，键块会销毁并重新创建其内容。当在组件周围使用时，这将导致它们被重新实例化和重新初始化： ¥Key blocks destroy and recreate their contents when the value of an expression changes. When used around components, this will cause them to be reinstantiated and reinitialised: ```svelte {#key value} {/key} ``` 如果你希望在值发生变化时播放过渡，它也很有用： ¥It's also useful if you want a transition to play whenever a value changes: ```svelte {#key value}
    {value}
    {/key} ``` # {#await ...} ```svelte {#await expression}...{:then name}...{:catch name}...{/await} ``` ```svelte {#await expression}...{:then name}...{/await} ``` ```svelte {#await expression then name}...{/await} ``` ```svelte {#await expression catch name}...{/await} ``` Await 块允许你在 [`Promise`](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) 的三种可能状态上进行分支 - 待处理、已完成或已拒绝。 ¥Await blocks allow you to branch on the three possible states of a [`Promise`](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — pending, fulfilled or rejected. ```svelte {#await promise}

    waiting for the promise to resolve...

    {:then value}

    The value is {value}

    {:catch error}

    Something went wrong: {error.message}

    {/await} ``` > [!NOTE] 在服务器端渲染期间，只会渲染待处理的分支。 > > 如果提供的表达式不是 `Promise`，则仅渲染 `:then` 分支，包括在服务器端渲染期间。 如果在 promise 拒绝（或不可能出现错误）时不需要渲染任何内容，则可以省略 `catch` 块。 ¥The `catch` block can be omitted if you don't need to render anything when the promise rejects (or no error is possible). ```svelte {#await promise}

    waiting for the promise to resolve...

    {:then value}

    The value is {value}

    {/await} ``` 如果你不关心挂起状态，你也可以省略初始块。 ¥If you don't care about the pending state, you can also omit the initial block. ```svelte {#await promise then value}

    The value is {value}

    {/await} ``` 类似地，如果你只想显示错误状态，则可以省略 `then` 块。 ¥Similarly, if you only want to show the error state, you can omit the `then` block. ```svelte {#await promise catch error}

    The error is {error}

    {/await} ``` > [!NOTE] 你可以将 `#await` 与 [`import(...)`](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Operators/import) 结合使用，从而实现组件的延迟渲染： > > ```svelte > {#await import('./Component.svelte') then { default: Component }} > > {/await} > ``` # {#snippet ...} ```svelte {#snippet name()}...{/snippet} ``` ```svelte {#snippet name(param1, param2, paramN)}...{/snippet} ``` Snippet 和 [渲染标签](@render) 是一种在组件内部创建可重用标记块的方法。不再需要像 [this](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE5VUYW-kIBD9K8Tmsm2yXXRzvQ-s3eR-R-0HqqOQKhAZb9sz_vdDkV1t000vRmHewMx7w2AflbIGG7GnPlK8gYhFv42JthG-m9Gwf6BGcLbVXZuPSGrzVho8ZirDGpDIhldgySN5GpEMez9kaNuckY1ANJZRamRuu2ZnhEZt6a84pvs43mzD4pMsUDDi8DMkQFYCGdkvsJwblFq5uCik9bmJ4JZwUkv1eoknWigX2eGNN6aGXa6bjV8ybP-X7sM36T58SVcrIIV2xVIaA41xeD5kKqWXuqpUJEefOqVuOkL9DfBchGrzWfu0vb-RpTd3o-zBR045Ga3HfuE5BmJpKauuhbPtENlUF2sqR9jqpsPSxWsMrlngyj3VJiyYjJXb1-lMa7IWC-iSk2M5Zzh-SJjShe-siq5kpZRPs55BbSGU5YPyte4vVV_VfFXxVb10dSLf17pS2lM5HnpPxw4Zpv6x-F57p0jI3OKlVnhv5V9wPQrNYQQ9D_f6aGHlC89fq1Z3qmDkJCTCweOGF4VUFSPJvD_DhreVdA0eu8ehJJ5x91dBaBkpWm3ureCFPt3uzRv56d4kdp-2euG38XZ6dsnd3ZmPG9yRBCrzRUvi-MccOdwz3qE-fOZ7AwAhlrtTUx3c76vRhSwlFBHDtoPhefgHX3dM0PkEAAA=) 那样编写重复的代码... ¥Snippets, and [render tags](@render), are a way to create reusable chunks of markup inside your components. Instead of writing duplicative code like [this](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE5VUYW-kIBD9K8Tmsm2yXXRzvQ-s3eR-R-0HqqOQKhAZb9sz_vdDkV1t000vRmHewMx7w2AflbIGG7GnPlK8gYhFv42JthG-m9Gwf6BGcLbVXZuPSGrzVho8ZirDGpDIhldgySN5GpEMez9kaNuckY1ANJZRamRuu2ZnhEZt6a84pvs43mzD4pMsUDDi8DMkQFYCGdkvsJwblFq5uCik9bmJ4JZwUkv1eoknWigX2eGNN6aGXa6bjV8ybP-X7sM36T58SVcrIIV2xVIaA41xeD5kKqWXuqpUJEefOqVuOkL9DfBchGrzWfu0vb-RpTd3o-zBR045Ga3HfuE5BmJpKauuhbPtENlUF2sqR9jqpsPSxWsMrlngyj3VJiyYjJXb1-lMa7IWC-iSk2M5Zzh-SJjShe-siq5kpZRPs55BbSGU5YPyte4vVV_VfFXxVb10dSLf17pS2lM5HnpPxw4Zpv6x-F57p0jI3OKlVnhv5V9wPQrNYQQ9D_f6aGHlC89fq1Z3qmDkJCTCweOGF4VUFSPJvD_DhreVdA0eu8ehJJ5x91dBaBkpWm3ureCFPt3uzRv56d4kdp-2euG38XZ6dsnd3ZmPG9yRBCrzRUvi-MccOdwz3qE-fOZ7AwAhlrtTUx3c76vRhSwlFBHDtoPhefgHX3dM0PkEAAA=)... ```svelte {#each images as image} {#if image.href}
    {image.caption}
    {image.caption}
     {:else}
    {image.caption}
    {image.caption}
    {/if} {/each} ``` ...你可以写 [this](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE5VUYW-bMBD9KxbRlERKY4jWfSA02n5H6QcXDmwVbMs-lnaI_z6D7TTt1moTAnPvzvfenQ_GpBEd2CS_HxPJekjy5IfWyS7BFz0b9id0CM62ajDVjBS2MkLjqZQldoBE9KwFS-7I_YyUOPqlRGuqnKw5orY5pVpUduj3mitUln5LU3pI0_UuBp9FjTwnDr9AHETLMSeHK6xiGoWSLi9yYT034cwSRjohn17zcQPNFTs8s153sK9Uv_Yh0-5_5d7-o9zbD-UqCaRWrllSYZQxLw_HUhb0ta-y4NnJUxfUvc7QuLJSaO0a3oh2MLBZat8u-wsPnXzKQvTtVVF34xK5d69ThFmHEQ4SpzeVRediTG8rjD5vBSeN3E5JyHh6R1DQK9-iml5kjzQUN_lSgVU8DhYLx7wwjSvRkMDvTjiwF4zM1kXZ7DlF1eN3A7IG85e-zRrYEjjm0FkI4Cc7Ripm0pHOChexhcWXzreeZyRMU6Mk3ljxC9w4QH-cQZ_b3T5pjHxk1VNr1CDrnJy5QDh6XLO6FrLNSRb2l9gz0wo3S6m7HErSgLsPGMHkpDZK31jOanXeHPQz-eruLHUP0z6yTbpbrn223V70uMXNSpQSZjpL0y8hcxxpNqA6_ql3BQAxlxvfpQ_uT9GrWjQC6iRHM8D0MP0GQsIi92QEAAA=): ¥...you can write [this](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE5VUYW-bMBD9KxbRlERKY4jWfSA02n5H6QcXDmwVbMs-lnaI_z6D7TTt1moTAnPvzvfenQ_GpBEd2CS_HxPJekjy5IfWyS7BFz0b9id0CM62ajDVjBS2MkLjqZQldoBE9KwFS-7I_YyUOPqlRGuqnKw5orY5pVpUduj3mitUln5LU3pI0_UuBp9FjTwnDr9AHETLMSeHK6xiGoWSLi9yYT034cwSRjohn17zcQPNFTs8s153sK9Uv_Yh0-5_5d7-o9zbD-UqCaRWrllSYZQxLw_HUhb0ta-y4NnJUxfUvc7QuLJSaO0a3oh2MLBZat8u-wsPnXzKQvTtVVF34xK5d69ThFmHEQ4SpzeVRediTG8rjD5vBSeN3E5JyHh6R1DQK9-iml5kjzQUN_lSgVU8DhYLx7wwjSvRkMDvTjiwF4zM1kXZ7DlF1eN3A7IG85e-zRrYEjjm0FkI4Cc7Ripm0pHOChexhcWXzreeZyRMU6Mk3ljxC9w4QH-cQZ_b3T5pjHxk1VNr1CDrnJy5QDh6XLO6FrLNSRb2l9gz0wo3S6m7HErSgLsPGMHkpDZK31jOanXeHPQz-eruLHUP0z6yTbpbrn223V70uMXNSpQSZjpL0y8hcxxpNqA6_ql3BQAxlxvfpQ_uT9GrWjQC6iRHM8D0MP0GQsIi92QEAAA=): ```svelte {#snippet figure(image)}
    {image.caption}
    {image.caption}
    {/snippet} {#each images as image} {#if image.href} {@render figure(image)} {:else} {@render figure(image)} {/if} {/each} ``` 与函数声明一样，代码片段可以有任意数量的参数，这些参数可以有默认值，并且你可以解构每个参数。但是，你不能使用 rest 参数。 ¥Like function declarations, snippets can have an arbitrary number of parameters, which can have default values, and you can destructure each parameter. You cannot use rest parameters, however. ## 代码片段范围(Snippet scope) ¥Snippet scope Snippet 可以在组件内部的任何位置声明。它们可以引用在自身之外声明的值，例如在 ` {#snippet hello(name)}

    hello {name}! {message}!

    {/snippet} {@render hello('alice')} {@render hello('bob')} ``` ...并且它们对于同一词汇范围内的所有内容都是 'visible'（即兄弟姐妹和这些兄弟姐妹的子项）： ¥...and they are 'visible' to everything in the same lexical scope (i.e. siblings, and children of those siblings): ```svelte
    {#snippet x()} {#snippet y()}...{/snippet} {@render y()} {/snippet} {@render y()}
    {@render x()} ``` Snippet 可以引用自身和彼此 ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE2WPTQqDMBCFrxLiRqH1Zysi7TlqF1YnENBJSGJLCYGeo5tesUeosfYH3c2bee_jjaWMd6BpfrAU6x5oTvdS0g01V-mFPkNnYNRaDKrxGxto5FKCIaeu1kYwFkauwsoUWtZYPh_3W5FMY4U2mb3egL9kIwY0rbhgiO-sDTgjSEqSTvIDs-jiOP7i_MHuFGAL6p9BtiSbOTl0GtzCuihqE87cqtyam6WRGz_vRcsZh5bmRg3gju4Fptq_kzQBAAA=)): ¥Snippets can reference themselves and each other ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE2WPTQqDMBCFrxLiRqH1Zysi7TlqF1YnENBJSGJLCYGeo5tesUeosfYH3c2bee_jjaWMd6BpfrAU6x5oTvdS0g01V-mFPkNnYNRaDKrxGxto5FKCIaeu1kYwFkauwsoUWtZYPh_3W5FMY4U2mb3egL9kIwY0rbhgiO-sDTgjSEqSTvIDs-jiOP7i_MHuFGAL6p9BtiSbOTl0GtzCuihqE87cqtyam6WRGz_vRcsZh5bmRg3gju4Fptq_kzQBAAA=)): ```svelte {#snippet blastoff()} 🚀 {/snippet} {#snippet countdown(n)} {#if n > 0} {n}... {@render countdown(n - 1)} {:else} {@render blastoff()} {/if} {/snippet} {@render countdown(10)} ``` ## 将片段传递给组件(Passing snippets to components) ¥Passing snippets to components ### 显式属性(Explicit props) ¥Explicit props 在模板中，片段与其他片段一样都是值。因此，它们可以传递作为 props ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3VS247aMBD9lZGpBGwDASRegonaPvQL2qdlH5zYEKvBNvbQLbL875VzAcKyj3PmzJnLGU8UOwqSkd8KJdaCk4TsZS0cyV49wYuJuQiQpGd-N2bu_ooaI1YwJ57hpVYoFDqSEepKKw3mO7VDeTTaIvxiRS1gb_URxvO0ibrS8WanIrHUyiHs7Vmigy28RmyHHmKvDMbMmFq4cQInvGSwTsBYWYoMVhCSB2rBFFPsyl0uruTlR3JZCWvlTXl1Yy_mawiR_rbZKZrellJ-5JQ0RiBUgnFhJ9OGR7HKmwVoilXeIye8DOJGfYCgRlZ3iE876TBsZPX7hPdteO75PC4QaIo8vwNPePmANQ2fMeEFHrLD7rR1jTNkW986E8C3KwfwVr8HSHOSEBT_kGRozyIkn_zQveXDL3rIfPJHtUDwzShJd_Qk3gQCbOGLsdq4yfTRJopRuin3I7nv6kL7ARRjmLdBDG3uv1mhuLA3V2mKtqNEf_oCn8p9aN-WYqH5peP4kWBl1UwJzAEPT9U7K--0fRrrWnPTXpCm1_EVdXjpNmlA8G1hPPyM1fKgMqjFHjctXGjLhZ05w0qpDhksGrybuNEHtJnCalZWsuaTlfq6nPaaBSv_HKw-K57BjzOiVj9ZKQYKzQjZodYFqydYTRN4gPhVzTDO2xnma3HsVWjaLjT8nbfwHy7Q5f2dBAAA)) 传递给组件： ¥Within the template, snippets are values just like any other. As such, they can be passed to components as props ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3VS247aMBD9lZGpBGwDASRegonaPvQL2qdlH5zYEKvBNvbQLbL875VzAcKyj3PmzJnLGU8UOwqSkd8KJdaCk4TsZS0cyV49wYuJuQiQpGd-N2bu_ooaI1YwJ57hpVYoFDqSEepKKw3mO7VDeTTaIvxiRS1gb_URxvO0ibrS8WanIrHUyiHs7Vmigy28RmyHHmKvDMbMmFq4cQInvGSwTsBYWYoMVhCSB2rBFFPsyl0uruTlR3JZCWvlTXl1Yy_mawiR_rbZKZrellJ-5JQ0RiBUgnFhJ9OGR7HKmwVoilXeIye8DOJGfYCgRlZ3iE876TBsZPX7hPdteO75PC4QaIo8vwNPePmANQ2fMeEFHrLD7rR1jTNkW986E8C3KwfwVr8HSHOSEBT_kGRozyIkn_zQveXDL3rIfPJHtUDwzShJd_Qk3gQCbOGLsdq4yfTRJopRuin3I7nv6kL7ARRjmLdBDG3uv1mhuLA3V2mKtqNEf_oCn8p9aN-WYqH5peP4kWBl1UwJzAEPT9U7K--0fRrrWnPTXpCm1_EVdXjpNmlA8G1hPPyM1fKgMqjFHjctXGjLhZ05w0qpDhksGrybuNEHtJnCalZWsuaTlfq6nPaaBSv_HKw-K57BjzOiVj9ZKQYKzQjZodYFqydYTRN4gPhVzTDO2xnma3HsVWjaLjT8nbfwHy7Q5f2dBAAA)): ```svelte {#snippet header()} fruit qty price total {/snippet} {#snippet row(d)} {d.name} {d.qty} {d.price} {d.qty * d.price} {/snippet} ``` 可以将其想象为将内容而不是数据传递给组件。这个概念类似于 Web 组件中的插槽。 ¥Think about it like passing content instead of data to a component. The concept is similar to slots in web components. ### 隐式属性(Implicit props) ¥Implicit props 为了方便创作，直接在组件内部声明的代码片段会隐式成为组件（[demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3VSTa_aMBD8Kyu_SkAbCA-JSzBR20N_QXt6vIMTO8SqsY29tI2s_PcqTiB8vaPHs7MzuxuIZgdBMvJLo0QlOElIJZXwJHsLBBvb_XUASc7Mb9Yu_B-hsMMK5sUzvDQahUZPMkJ96aTFfKd3KA_WOISfrFACKmcOMFmk8TWUTjY73RFLoz1C5U4SPWzhrcN2GKDrlcGEWauEnyRwxCaDdQLWyVJksII2uaMWTDPNLtzX5YX8-kgua-GcHJVXI3u5WEPb0d83O03TMZSmfRzOkG1Db7mNacOL19JagVALxoWbztq-H8U6j0SaYp2P2BGbOyQ2v8PQIFMXLKRDk177pq0zf6d8bMrzwBdd0pamyPMb-IjNEzS2f86Gz_Dwf-2F9nvNSUJQ_EOSoTuJNvngqK5v4Pas7n4-OCwlEEJcQTIMO-nSQwtb-GSdsX46e9gbRoP9yGQ11I0rEuycunu6PHx1QnPhxm3SFN15MOlYEFJZtf0dUywMbwZOeBGsrKNLYB54-1R9WNqVdki7usim6VmQphf7mnpshiQRhNAXdoOfMyX3OgMlKtz0cGEcF27uLSul3mewjPjgOOoDukxjPS9rqfh0pb-8zs6aBSt_7505aZ7B9xOi0T9YKW4UooVsr0zB1BTrWQJ3EL-oWcZ572GxFoezCk37QLe3897-B2i2U62uBAAA)）上的 props： ¥As an authoring convenience, snippets declared directly *inside* a component implicitly become props *on* the component ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3VSTa_aMBD8Kyu_SkAbCA-JSzBR20N_QXt6vIMTO8SqsY29tI2s_PcqTiB8vaPHs7MzuxuIZgdBMvJLo0QlOElIJZXwJHsLBBvb_XUASc7Mb9Yu_B-hsMMK5sUzvDQahUZPMkJ96aTFfKd3KA_WOISfrFACKmcOMFmk8TWUTjY73RFLoz1C5U4SPWzhrcN2GKDrlcGEWauEnyRwxCaDdQLWyVJksII2uaMWTDPNLtzX5YX8-kgua-GcHJVXI3u5WEPb0d83O03TMZSmfRzOkG1Db7mNacOL19JagVALxoWbztq-H8U6j0SaYp2P2BGbOyQ2v8PQIFMXLKRDk177pq0zf6d8bMrzwBdd0pamyPMb-IjNEzS2f86Gz_Dwf-2F9nvNSUJQ_EOSoTuJNvngqK5v4Pas7n4-OCwlEEJcQTIMO-nSQwtb-GSdsX46e9gbRoP9yGQ11I0rEuycunu6PHx1QnPhxm3SFN15MOlYEFJZtf0dUywMbwZOeBGsrKNLYB54-1R9WNqVdki7usim6VmQphf7mnpshiQRhNAXdoOfMyX3OgMlKtz0cGEcF27uLSul3mewjPjgOOoDukxjPS9rqfh0pb-8zs6aBSt_7505aZ7B9xOi0T9YKW4UooVsr0zB1BTrWQJ3EL-oWcZ572GxFoezCk37QLe3897-B2i2U62uBAAA)): ```svelte
    {#snippet header()} {/snippet} {#snippet row(d)} {/snippet}
    fruit qty price total{d.name} {d.qty} {d.price} {d.qty * d.price}
    ``` ### 隐式 `children` 代码片段(Implicit `children` snippet) ¥Implicit `children` snippet 组件内任何不属于声明片段的内容都将成为特殊的 `children` 片段。 ¥Any content inside the component tags that is *not* a snippet declaration implicitly becomes part of the `children` snippet ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3WOQQrCMBBFrzIMggql3ddY1Du4si5sOmIwnYRkFKX07lKqglqX8_7_w2uRDw1hjlsWI5ZqTPBoLEXMdy3K3fdZDzB5Ndfep_FKVnpWHSKNce1YiCVijirqYLwUJQOYxrsgsLmIOIZjcA1M02w4n-PpomSVvTclqyEutDX6DA2pZ7_ABIVugrmEC3XJH92P55_G39GodCmWBFrQJ2PrQAwdLGHig_NxNv9xrQa1dhWIawrv1Wzeqawa8953D-8QOmaEAQAA)): ```svelte ``` ```svelte ``` > [!NOTE] 请注意，如果组件内部还有内容，则不能使用名为 `children` 的 prop。因此，应避免使用同名 prop。 ### 可选代码片段属性(Optional snippet props) ¥Optional snippet props 你可以将代码片段属性声明为可选。如果未设置代码片段，你可以使用可选链接不渲染任何内容... ¥You can declare snippet props as being optional. You can either use optional chaining to not render anything if the snippet isn't set... ```svelte {@render children?.()} ``` ...或使用 `#if` 块来渲染后备内容： ¥...or use an `#if` block to render fallback content: ```svelte {#if children} {@render children()} {:else} fallback content {/if} ``` ## 键入片段(Typing snippets) ¥Typing snippets Snippet 实现从 `'svelte'` 导入的 `Snippet` 接口： ¥Snippets implement the `Snippet` interface imported from `'svelte'`: ```svelte ``` 进行此更改后，如果你尝试在不提供 `data` prop 和 `row` 代码片段的情况下使用该组件，则会出现红色波浪线。请注意，提供给 `Snippet` 的类型参数是一个元组，因为代码片段可以有多个参数。 ¥With this change, red squigglies will appear if you try and use the component without providing a `data` prop and a `row` snippet. Notice that the type argument provided to `Snippet` is a tuple, since snippets can have multiple parameters. 我们可以通过声明泛型来进一步收紧，以便 `data` 和 `row` 引用相同的类型： ¥We can tighten things up further by declaring a generic, so that `data` and `row` refer to the same type: ```svelte ``` ## 导出代码片段(Exporting snippets) ¥Exporting snippets 在 `.svelte` 文件顶层声明的 Snippet 可以从 ` {#snippet add(a, b)} {a} + {b} = {a + b} {/snippet} ``` > [!NOTE] > 这需要 Svelte 5.5.0 或更高版本。 ## 程序化代码片段(Programmatic snippets) ¥Programmatic snippets 可以使用 [`createRawSnippet`](svelte#createRawSnippet) API 以编程方式创建 Snippet。这适用于高级用例。 ¥Snippets can be created programmatically with the [`createRawSnippet`](svelte#createRawSnippet) API. This is intended for advanced use cases. ## 代码片段和插槽(Snippets and slots) ¥Snippets and slots 在 Svelte 4 中，可以使用 [slots](legacy-slots) 将内容传递给组件。Snippet 功能更强大、更灵活，因此在 Svelte 5 中已弃用插槽。 ¥In Svelte 4, content can be passed to components using [slots](legacy-slots). Snippets are more powerful and flexible, and as such slots are deprecated in Svelte 5. # {@render ...} 要渲染 [snippet](snippet)，请使用 `{@render ...}` 标签。 ¥To render a [snippet](snippet), use a `{@render ...}` tag. ```svelte {#snippet sum(a, b)}

    {a} + {b} = {a + b}

    {/snippet} {@render sum(1, 2)} {@render sum(3, 4)} {@render sum(5, 6)} ``` 表达式可以是像 `sum` 这样的标识符，也可以是任意的 JavaScript 表达式： ¥The expression can be an identifier like `sum`, or an arbitrary JavaScript expression: ```svelte {@render (cool ? coolSnippet : lameSnippet)()} ``` ## 可选片段(Optional snippets) ¥Optional snippets 如果代码片段可能未定义（例如，因为它是一个传入的 prop），那么你可以使用可选链接仅在定义时渲染它： ¥If the snippet is potentially undefined — for example, because it's an incoming prop — then you can use optional chaining to only render it when it *is* defined: ```svelte {@render children?.()} ``` 或者，使用带有 `:else` 子句的 [`{#if ...}`](if) 块来渲染后备内容： ¥Alternatively, use an [`{#if ...}`](if) block with an `:else` clause to render fallback content: ```svelte {#if children} {@render children()} {:else}

    fallback content

    {/if} ``` # {@html ...} 要将原始 HTML 注入组件，请使用 `{@html ...}` 标记： ¥To inject raw HTML into your component, use the `{@html ...}` tag: ```svelte
    {@html content}
    ``` > [!NOTE] 为了防止 [XSS attacks](https://owasp.org/www-community/attacks/xss/) 错误，请确保对传递的字符串进行转义，或者只使用你可控制的值填充它。切勿渲染未经处理的内容。 表达式应该是有效的独立 HTML — 这不起作用，因为 `
    ` 不是有效的 HTML： ¥The expression should be valid standalone HTML — this will not work, because `
    ` is not valid HTML: ```svelte {@html '
    '}content{@html '
    '} ``` 它也不会编译 Svelte 代码。 ¥It also will not compile Svelte code. ## 样式(Styling) ¥Styling 以这种方式渲染的内容对 Svelte 来说是 'invisible'，因此不会接收 [作用域样式](scoped-styles) — 换句话说，这将不起作用，并且 `a` 和 `img` 样式将被视为未使用： ¥Content rendered this way is 'invisible' to Svelte and as such will not receive [scoped styles](scoped-styles) — in other words, this will not work, and the `a` and `img` styles will be regarded as unused: ```svelte
    {@html content}
    ``` 相反，使用 `:global` 修饰符来定位 `
    ` 内的所有内容： ¥Instead, use the `:global` modifier to target everything inside the `
    `: ```svelte ``` # {@attach ...} 附件是在元素挂载到 DOM 或 [state]($state) 读取函数内部更新时在 [effect]($effect) 中运行的函数。 ¥Attachments are functions that run in an [effect]($effect) when an element is mounted to the DOM or when [state]($state) read inside the function updates. 它们可以可选地返回一个函数，该函数在附件重新运行之前调用，或者在元素稍后从 DOM 中移除之后调用。 ¥Optionally, they can return a function that is called before the attachment re-runs, or after the element is later removed from the DOM. > [!NOTE] > 附件在 Svelte 5.29 及更高版本中可用。 ```svelte
    ...
    ``` 一个元素可以包含任意数量的附件。 ¥An element can have any number of attachments. ## 附件工厂(Attachment factories) ¥Attachment factories 一个有用的模式是让函数（例如本例中的 `tooltip`）返回一个附件 ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3VT0XLaMBD8lavbDiaNCUlbHhTItG_5h5AH2T5ArdBppDOEMv73SkbGJGnH47F9t3un3TsfMyO3mInsh2SW1Sa7zlZKo8_E0zHjg42pGAjxBPxp7cTvUHOMldLjv-IVGUbDoUw295VTlh-WZslqa8kxsLL2ACtHWxh175NffnQfAAGikSGxYQGfPEvGfPSIWtOH0TiBVo2pWJEBJtKhQp4YYzjG9JIdcuMM5IZqHMPioY8vOSA997zQoevf4a7heO7cdp34olRiTGr07OhwH1IdoO2A7dLMbwahZq6MbRhKZWqxk7rBxTGVbuHmhCgb5qDgmIx_J6XtHHukHTrYYqx_YpzYng8aO4RYayql7hU-1ZJl0akqHBE_D9KLolwL-Dibzc7iSln9XjtqTF1UpMkJ2EmXR-BgQErsN4pxIJKr0RVO1qrxAqaTO4fbc9bKulZm3cfDY3aZDgvFGErWjmzhN7KmfX5rXyDeX8Pt1mU-hXjdBOrtuB97vK4GPUtmJ41XcRMEGDLD8do0nJ73zhUhSlyRw0t3vPqD8cjfLs-axiFgNBrkUd9Ulp50c-GLxlXAVlJX-ffpZyiSn7H0eLCUySZQcQdXlxj4El0Yv_FZvIKElqqGTruVLhzu7VRKCh22_5toOyxsWqLwwzK-cCbYNdg-hy-p9D7sbiZWUnts_wLUOF3CJgQAAA==))： ¥A useful pattern is for a function, such as `tooltip` in this example, to *return* an attachment ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3VT0XLaMBD8lavbDiaNCUlbHhTItG_5h5AH2T5ArdBppDOEMv73SkbGJGnH47F9t3un3TsfMyO3mInsh2SW1Sa7zlZKo8_E0zHjg42pGAjxBPxp7cTvUHOMldLjv-IVGUbDoUw295VTlh-WZslqa8kxsLL2ACtHWxh175NffnQfAAGikSGxYQGfPEvGfPSIWtOH0TiBVo2pWJEBJtKhQp4YYzjG9JIdcuMM5IZqHMPioY8vOSA997zQoevf4a7heO7cdp34olRiTGr07OhwH1IdoO2A7dLMbwahZq6MbRhKZWqxk7rBxTGVbuHmhCgb5qDgmIx_J6XtHHukHTrYYqx_YpzYng8aO4RYayql7hU-1ZJl0akqHBE_D9KLolwL-Dibzc7iSln9XjtqTF1UpMkJ2EmXR-BgQErsN4pxIJKr0RVO1qrxAqaTO4fbc9bKulZm3cfDY3aZDgvFGErWjmzhN7KmfX5rXyDeX8Pt1mU-hXjdBOrtuB97vK4GPUtmJ41XcRMEGDLD8do0nJ73zhUhSlyRw0t3vPqD8cjfLs-axiFgNBrkUd9Ulp50c-GLxlXAVlJX-ffpZyiSn7H0eLCUySZQcQdXlxj4El0Yv_FZvIKElqqGTruVLhzu7VRKCh22_5toOyxsWqLwwzK-cCbYNdg-hy-p9D7sbiZWUnts_wLUOF3CJgQAAA==)): ```svelte ``` 由于 `tooltip(content)` 表达式在 [effect]($effect) 中运行，因此每当 `content` 发生更改时，附件都会被销毁并重新创建。在附件函数首次运行时，读取的任何状态都会发生相同的情况。（如果你不希望如此，请参阅 [控制附件重新运行的时间](#Controlling-when-attachments-re-run)。） ¥Since the `tooltip(content)` expression runs inside an [effect]($effect), the attachment will be destroyed and recreated whenever `content` changes. The same thing would happen for any state read *inside* the attachment function when it first runs. (If this isn't what you want, see [Controlling when attachments re-run](#Controlling-when-attachments-re-run).) ## 内联附件(Inline attachments) ¥Inline attachments 附件也可以内联创建 ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE71Wf3OaWBT9KoyTTnW3MS-I3dYmnWXVtnRAazRJzbozRSQEApiRhwKO333vuY8m225m_9yZGOT9OPfcc84D943UTfxGr_G7K6Xr3TVeNW7D2M8avT_3DVk-YAoDNF4vNB8e2tnWjyXGlm7mPzfurVPpp5JgGmeZtwkf5PtFupCxLzVvHa832rl2lElX-s2Xm2DZFNqp_hs-rZetd4v07ORpT3qmQHu7MF2td0BZp8k6z_xkvfXP902_pZ2_1_aYWEiqm0kN8I4r79qbdZ6umnq3q_2iNf22F4dE6qt2oimwdpim_uY6XMm7Fuo-IQT_iTD_CeGTHwZ38ieIJUFQRxirR1Xf39Dw0X5z0I72Af4tD61vvPNwWKQnqmfPTbduhsEd2J3vO_oBd3dc6fF2X7umNdWGf0vBRhSS6qoV7cCXfTXWfKmvWG61_si_vfU92Wz-E4RhsLhNIYinsox9QKGVd8-tuACCeKXRX12P-T_eKf7fhTq0Hvt-f3ailtSeoxJHRo1-58NoPe1UiBc1hkL8Yeh45y_vQ3mcuNl9T8s3cXPRWLnS7YWJG_gn2Tb4tUjid8jua-PVl08j_ab8I14mH8Llx0s5Tz5Err4ql52r_GYg0mVy1bEGZuD0ze64b5TWYFiM-16wSuJ4JT5vfVpDcztrcG_YkRU4s6HxufzDWF4XuVeJ1P10IbzBemt3Vp1V2e04ZXfrJd7Wicyd039brRIv_RIVu_nXi7X1cfL2sy66ztToUp1TO7qJ7NlwZ0f30pld5qNSVE5o6PbMojFHjgZB7oSicPpGteyLclQap7SvY0dXtM_LR1NT2JFHey3aaxa0VxCeYJ7RMHemoiCcgPZV9pR7o7kgcOjeGliYk9hjDZx8FAq6enwlTPSZj_vYPw9Il64dXdIY8ZmapzwfEd8-1ZyaxWhqkIZOibXUd-6Upqi1pD4uMicCV1GA_7zi73UN8BaF4sC8peJtMjfmjbHZBFwq5ov50qRaE0l96NZggnW4KqypYRAW-uhSz9ADvklwJF2J-5W0Z5fQPBhDX92R6I_0IFxRgDftge4l4dP-gH1hjD7uqU6fsOEZ9UNrCdPB-nys6uXgY6O3ZMd9sy5T9PghqrWHdjo4jB51CgLiKJaDYYA-7WgYONf1FbjkI-mE3EAfUY_rijfuJ_CVPaR50oe9JF7Q0pI8Dw3osxxYHdYPGbp2CnwHF8KvwJv2wEv0Z3ilQI6U9uwbZxbYJXvEmjjQjjCHkvNLvNg3yhzXQd1olamsT4IRrZmX0MUDpwL7R8zzHj7pSh9hPHFSHjLezKqAST51uC5zmtQ87skDUaneLokT5RbXkPWSYz53Abgjc8_o4KFGUZ-Hgv2Z1l5OTYM9D-HfUD0L-EwxH5wRnIG61gS-khfgY1bq7IAP_DA4l5xRuh9xlm8yGjutc8t-wHtkhWv3hc7aqGwiK5KzgvM5xRkZYn193uEln-su55j1GaIv7oM4iPrsVHiG0Dx7TR9-1lBfqFdwfvSd5LNL5xyZVp5NoHFZ57FkfiF6vKs4k5zvIfrX5xX6MXmt0gM5MTu8DjnhukrHHzTRd3jm0dma0_f_x5cxP9f4jBdqHvmbq2fUjzqcKh2Cp-yWj9ntcHanXmBXxhu7Q--eyjhfNFpaV7zgz4nWEUb7zUOhpevjjf_gu_KZ99pxFlZ-T3sttkmYqrco_26q35v0Ewzv5EZPbnL_8BfduWGMnyyN3q0bZ_7hb_7KG_L4CQAA))： ¥Attachments can also be created inline ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE71Wf3OaWBT9KoyTTnW3MS-I3dYmnWXVtnRAazRJzbozRSQEApiRhwKO333vuY8m225m_9yZGOT9OPfcc84D943UTfxGr_G7K6Xr3TVeNW7D2M8avT_3DVk-YAoDNF4vNB8e2tnWjyXGlm7mPzfurVPpp5JgGmeZtwkf5PtFupCxLzVvHa832rl2lElX-s2Xm2DZFNqp_hs-rZetd4v07ORpT3qmQHu7MF2td0BZp8k6z_xkvfXP902_pZ2_1_aYWEiqm0kN8I4r79qbdZ6umnq3q_2iNf22F4dE6qt2oimwdpim_uY6XMm7Fuo-IQT_iTD_CeGTHwZ38ieIJUFQRxirR1Xf39Dw0X5z0I72Af4tD61vvPNwWKQnqmfPTbduhsEd2J3vO_oBd3dc6fF2X7umNdWGf0vBRhSS6qoV7cCXfTXWfKmvWG61_si_vfU92Wz-E4RhsLhNIYinsox9QKGVd8-tuACCeKXRX12P-T_eKf7fhTq0Hvt-f3ailtSeoxJHRo1-58NoPe1UiBc1hkL8Yeh45y_vQ3mcuNl9T8s3cXPRWLnS7YWJG_gn2Tb4tUjid8jua-PVl08j_ab8I14mH8Llx0s5Tz5Err4ql52r_GYg0mVy1bEGZuD0ze64b5TWYFiM-16wSuJ4JT5vfVpDcztrcG_YkRU4s6HxufzDWF4XuVeJ1P10IbzBemt3Vp1V2e04ZXfrJd7Wicyd039brRIv_RIVu_nXi7X1cfL2sy66ztToUp1TO7qJ7NlwZ0f30pld5qNSVE5o6PbMojFHjgZB7oSicPpGteyLclQap7SvY0dXtM_LR1NT2JFHey3aaxa0VxCeYJ7RMHemoiCcgPZV9pR7o7kgcOjeGliYk9hjDZx8FAq6enwlTPSZj_vYPw9Il64dXdIY8ZmapzwfEd8-1ZyaxWhqkIZOibXUd-6Upqi1pD4uMicCV1GA_7zi73UN8BaF4sC8peJtMjfmjbHZBFwq5ov50qRaE0l96NZggnW4KqypYRAW-uhSz9ADvklwJF2J-5W0Z5fQPBhDX92R6I_0IFxRgDftge4l4dP-gH1hjD7uqU6fsOEZ9UNrCdPB-nys6uXgY6O3ZMd9sy5T9PghqrWHdjo4jB51CgLiKJaDYYA-7WgYONf1FbjkI-mE3EAfUY_rijfuJ_CVPaR50oe9JF7Q0pI8Dw3osxxYHdYPGbp2CnwHF8KvwJv2wEv0Z3ilQI6U9uwbZxbYJXvEmjjQjjCHkvNLvNg3yhzXQd1olamsT4IRrZmX0MUDpwL7R8zzHj7pSh9hPHFSHjLezKqAST51uC5zmtQ87skDUaneLokT5RbXkPWSYz53Abgjc8_o4KFGUZ-Hgv2Z1l5OTYM9D-HfUD0L-EwxH5wRnIG61gS-khfgY1bq7IAP_DA4l5xRuh9xlm8yGjutc8t-wHtkhWv3hc7aqGwiK5KzgvM5xRkZYn193uEln-su55j1GaIv7oM4iPrsVHiG0Dx7TR9-1lBfqFdwfvSd5LNL5xyZVp5NoHFZ57FkfiF6vKs4k5zvIfrX5xX6MXmt0gM5MTu8DjnhukrHHzTRd3jm0dma0_f_x5cxP9f4jBdqHvmbq2fUjzqcKh2Cp-yWj9ntcHanXmBXxhu7Q--eyjhfNFpaV7zgz4nWEUb7zUOhpevjjf_gu_KZ99pxFlZ-T3sttkmYqrco_26q35v0Ewzv5EZPbnL_8BfduWGMnyyN3q0bZ_7hb_7KG_L4CQAA)): ```svelte { const context = canvas.getContext('2d'); $effect(() => { context.fillStyle = color; context.fillRect(0, 0, canvas.width, canvas.height); }); }} > ``` > [!NOTE] > 嵌套效果会在 `color` 发生变化时运行，而外部效果（调用 `canvas.getContext(...)` 的地方）仅运行一次，因为它不读取任何响应式状态。 ## 将附件传递给组件(Passing attachments to components) ¥Passing attachments to components 当在组件上使用时，`{@attach ...}` 将创建一个键为 [`Symbol`](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) 的 prop。如果组件将 [spreads](/tutorial/svelte/spread-props) 属性添加到元素上，则该元素将接收这些附件。 ¥When used on a component, `{@attach ...}` will create a prop whose key is a [`Symbol`](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol). If the component then [spreads](/tutorial/svelte/spread-props) props onto an element, the element will receive those attachments. 这允许你创建用于扩充元素（[demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3VUS3ObMBD-KxvajnFqsJM2PhA7TXrKob31FjITAbKtRkiMtDhJPfz3LiAMdpxhGJvdb1_fPnaeYjn3Iu-WIbJ04028lZDcetHDzsO3olbVApI74F1RhHbLJdayhFl-Sp5qhVwhufEWNjWiwJtYxSjyQhsEFEXxBiujcxg1_8O_dnQ9APwsEbVyiHDafjrvDZCgkiO4MLCEzxYZcn90z6XUZ6OxA61KlaIgV6i1pFC-sxjDrlbHaDiWRoGvdMbHsLzp5DES0mJnRxGaRBvcBHb7yFUTCQeunEWYcYtGv12TqgFUDbCK1WLaM6IWQhUlQiJUFm2ZLPly51xXMG0Rjoyd69C7UqqG2nu95QZyXvtvLVpri2-SN4hoLXXCZFfhQ8aQBU1VgdEaH_vSgyBZR_BpPp_vi0tY-rw2ulRZkGqpTQRbZvwa2BPgFC8bgbw31CbjJjAsE6WNYBZeGp7vtQXLMqHWnZx-5kM1TR5ycpkZXQR2wzL94l8Ur1C_3-g168SfQf1MyfRi3LW9fs77emJEw5QV9SREoLTq06tcczq7d6xEUcJX2vAhO1b843XK34e5unZEMBr15ekuKEusluWAF8lXhE2ZTP2r2RcIHJ-163FPKerCgYJLOB9i4GvNwviI5-gAQiFFBk3tBTOU3HFXEk0R8o86WvUD64aINhv5K3oRmpJXkw8uxMG6Hh6JY9X7OwGSqfUy9tDG3sHNoEi0d_d_fv9qndxRU0VClFqo3KVo3U655Hnt1PXB3Qra2Y2QGdEwgTAMCxopsoxOe6SD0gD8movDhT0LAnhqlE8gVCpLWnRoV7OJCkFAwEXitrYL1W7p7pbiE_P7XH6E_rihODm5s52XtiH9Ekaw0VgI9exadWL1uoEYjPtg2672k5szsxbKyWB2fdT0w5Y_0hcT8oXOlRetmLS8-g-6TLXXQgYAAA==)）的封装器组件： ¥This allows you to create *wrapper components* that augment elements ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3VUS3ObMBD-KxvajnFqsJM2PhA7TXrKob31FjITAbKtRkiMtDhJPfz3LiAMdpxhGJvdb1_fPnaeYjn3Iu-WIbJ04028lZDcetHDzsO3olbVApI74F1RhHbLJdayhFl-Sp5qhVwhufEWNjWiwJtYxSjyQhsEFEXxBiujcxg1_8O_dnQ9APwsEbVyiHDafjrvDZCgkiO4MLCEzxYZcn90z6XUZ6OxA61KlaIgV6i1pFC-sxjDrlbHaDiWRoGvdMbHsLzp5DES0mJnRxGaRBvcBHb7yFUTCQeunEWYcYtGv12TqgFUDbCK1WLaM6IWQhUlQiJUFm2ZLPly51xXMG0Rjoyd69C7UqqG2nu95QZyXvtvLVpri2-SN4hoLXXCZFfhQ8aQBU1VgdEaH_vSgyBZR_BpPp_vi0tY-rw2ulRZkGqpTQRbZvwa2BPgFC8bgbw31CbjJjAsE6WNYBZeGp7vtQXLMqHWnZx-5kM1TR5ycpkZXQR2wzL94l8Ur1C_3-g168SfQf1MyfRi3LW9fs77emJEw5QV9SREoLTq06tcczq7d6xEUcJX2vAhO1b843XK34e5unZEMBr15ekuKEusluWAF8lXhE2ZTP2r2RcIHJ-163FPKerCgYJLOB9i4GvNwviI5-gAQiFFBk3tBTOU3HFXEk0R8o86WvUD64aINhv5K3oRmpJXkw8uxMG6Hh6JY9X7OwGSqfUy9tDG3sHNoEi0d_d_fv9qndxRU0VClFqo3KVo3U655Hnt1PXB3Qra2Y2QGdEwgTAMCxopsoxOe6SD0gD8movDhT0LAnhqlE8gVCpLWnRoV7OJCkFAwEXitrYL1W7p7pbiE_P7XH6E_rihODm5s52XtiH9Ekaw0VgI9exadWL1uoEYjPtg2672k5szsxbKyWB2fdT0w5Y_0hcT8oXOlRetmLS8-g-6TLXXQgYAAA==)): ```svelte ``` ```svelte ``` ## 控制附件重新运行的时间(Controlling when attachments re-run) ¥Controlling when attachments re-run 与 [actions](use) 不同，附件是完全响应式的：`{@attach foo(bar)}` 会在 `foo` 或 `bar` 发生更改（或读取 `foo` 中的任何状态）时重新运行： ¥Attachments, unlike [actions](use), are fully reactive: `{@attach foo(bar)}` will re-run on changes to `foo` *or* `bar` (or any state read inside `foo`): ```js // @errors: 7006 2304 2552 function foo(bar) { return (node) => { veryExpensiveSetupWork(node); update(node, bar); }; } ``` 在极少数情况下，如果出现问题（例如，如果 `foo` 执行了昂贵且不可避免的设置工作），请考虑将数据传递到函数内部，并在子效果中读取： ¥In the rare case that this is a problem (for example, if `foo` does expensive and unavoidable setup work) consider passing the data inside a function and reading it in a child effect: ```js // @errors: 7006 2304 2552 function foo(+++getBar+++) { return (node) => { veryExpensiveSetupWork(node); +++ $effect(() => { update(node, getBar()); });+++ } } ``` ## 以编程方式创建附件(Creating attachments programmatically) ¥Creating attachments programmatically 要将附件添加到将展开到组件或元素的对象，请使用 [`createAttachmentKey`](svelte-attachments#createAttachmentKey)。 ¥To add attachments to an object that will be spread onto a component or element, use [`createAttachmentKey`](svelte-attachments#createAttachmentKey). ## 将操作转换为附件(Converting actions to attachments) ¥Converting actions to attachments 如果你使用的库仅提供操作，则可以使用 [`fromAction`](svelte-attachments#fromAction) 将它们转换为附件，以便（例如）与组件一起使用它们。 ¥If you're using a library that only provides actions, you can convert them to attachments with [`fromAction`](svelte-attachments#fromAction), allowing you to (for example) use them with components. # {@const ...} `{@const ...}` 标签定义了一个本地常量。 ¥The `{@const ...}` tag defines a local constant. ```svelte {#each boxes as box} {@const area = box.width * box.height} {box.width} * {box.height} = {area} {/each} ``` `{@const}` 仅允许作为块（`{#if ...}`、`{#each ...}`、`{#snippet ...}` 等）的直接子块（`` 或 ``）。 ¥`{@const}` is only allowed as an immediate child of a block — `{#if ...}`, `{#each ...}`, `{#snippet ...}` and so on — a `` or a ``. # {@debug ...} `{@debug ...}` 标签提供了 `console.log(...)` 的替代方案。当特定变量的值发生变化时，它会记录它们，并在打开开发工具时暂停代码执行。 ¥The `{@debug ...}` tag offers an alternative to `console.log(...)`. It logs the values of specific variables whenever they change, and pauses code execution if you have devtools open. ```svelte {@debug user}

    Hello {user.firstname}!

    ``` `{@debug ...}` 接受以逗号分隔的变量名列表（不是任意表达式）。 ¥`{@debug ...}` accepts a comma-separated list of variable names (not arbitrary expressions). ```svelte {@debug user} {@debug user1, user2, user3} {@debug user.firstname} {@debug myArray[0]} {@debug !isReady} {@debug typeof user === 'object'} ``` 没有任何参数的 `{@debug}` 标签将插入一个 `debugger` 语句，该语句在任何状态发生变化时触发，而不是指定的变量。 ¥The `{@debug}` tag without any arguments will insert a `debugger` statement that gets triggered when *any* state changes, as opposed to the specified variables. # bind: 数据通常从父级向下流动到子级。`bind:` 指令允许数据以另一种方式流动，从子级流向父级。 ¥Data ordinarily flows down, from parent to child. The `bind:` directive allows data to flow the other way, from child to parent. 通用语法是 `bind:property={expression}`，其中 `expression` 是 [lvalue](https://press.rebus.community/programmingfundamentals/chapter/lvalue-and-rvalue/)（即变量或对象属性）。当表达式是与属性同名的标识符时，我们可以省略表达式 - 换句话说，它们是等效的： ¥The general syntax is `bind:property={expression}`, where `expression` is an [*lvalue*](https://press.rebus.community/programmingfundamentals/chapter/lvalue-and-rvalue/) (i.e. a variable or an object property). When the expression is an identifier with the same name as the property, we can omit the expression — in other words these are equivalent: ```svelte ``` Svelte 创建一个更新绑定值的事件监听器。如果元素已经具有同一事件的监听器，则将在更新绑定值之前触发该监听器。 ¥Svelte creates an event listener that updates the bound value. If an element already has a listener for the same event, that listener will be fired before the bound value is updated. 大多数绑定都是双向的，这意味着对值的更改将影响元素，反之亦然。一些绑定是只读的，这意味着更改它们的值不会对元素产生影响。 ¥Most bindings are *two-way*, meaning that changes to the value will affect the element and vice versa. A few bindings are *readonly*, meaning that changing their value will have no effect on the element. ## 函数绑定(Function bindings) ¥Function bindings 你还可以使用 `bind:property={get, set}`，其中 `get` 和 `set` 是函数，允许你执行验证和转换： ¥You can also use `bind:property={get, set}`, where `get` and `set` are functions, allowing you to perform validation and transformation: ```svelte value, (v) => value = v.toLowerCase()} /> ``` 在像 [尺寸绑定](#Dimensions) 这样的只读绑定的情况下，`get` 值应该是 `null`： ¥In the case of readonly bindings like [dimension bindings](#Dimensions), the `get` value should be `null`: ```svelte
    ...
    ``` > [!NOTE] > 函数绑定在 Svelte 5.9.0 及更高版本中可用。 ## `` `` 元素上的 `bind:value` 指令绑定输入的 `value` 属性： ¥A `bind:value` directive on an `` element binds the input's `value` property: ```svelte

    {message}

    ``` 在数字输入（`type="number"` 或 `type="range"`）的情况下，该值将被强制转换为数字（[demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE6WPwYoCMQxAfyWEPeyiOOqx2w74Hds9pBql0IllmhGXYf5dKqwiyILsLXnwwsuI-5i4oPkaUX8yo7kCnKNQV7dNzoty4qSVBSr8jG-Poixa0KAt2z5mbb14TaxA4OCtKCm_rz4-f2m403WltrlrYhMFTtcLNkoeFGqZ8yhDF7j3CCHKzpwoDexGmqCL4jwuPUJHZ-dxVcfmyYGe5MAv-La5pbxYFf5Z9Zf_UJXb-sEMquFgJJhBmGyTW5yj8lnRaD_w9D1dAKSSj7zqAQAA)）： ¥In the case of a numeric input (`type="number"` or `type="range"`), the value will be coerced to a number ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE6WPwYoCMQxAfyWEPeyiOOqx2w74Hds9pBql0IllmhGXYf5dKqwiyILsLXnwwsuI-5i4oPkaUX8yo7kCnKNQV7dNzoty4qSVBSr8jG-Poixa0KAt2z5mbb14TaxA4OCtKCm_rz4-f2m403WltrlrYhMFTtcLNkoeFGqZ8yhDF7j3CCHKzpwoDexGmqCL4jwuPUJHZ-dxVcfmyYGe5MAv-La5pbxYFf5Z9Zf_UJXb-sEMquFgJJhBmGyTW5yj8lnRaD_w9D1dAKSSj7zqAQAA)): ```svelte

    {a} + {b} = {a + b}

    ``` 如果输入为空或无效（在 `type="number"` 的情况下），则值为 `undefined`。 ¥If the input is empty or invalid (in the case of `type="number"`), the value is `undefined`. 自 5.6.0 起，如果 `` 具有 `defaultValue` 并且是表单的一部分，则在重置表单时它将恢复为该值而不是空字符串。请注意，对于初始渲染，除非绑定的值是 `null` 或 `undefined`，否则绑定的值优先。 ¥Since 5.6.0, if an `` has a `defaultValue` and is part of a form, it will revert to that value instead of the empty string when the form is reset. Note that for the initial render the value of the binding takes precedence unless it is `null` or `undefined`. ```svelte
    ``` > [!NOTE] > 请谨慎使用重置按钮，并确保用户在尝试提交表单时不会意外点击它们。 ## `` 复选框和单选输入可以与 `bind:checked` 绑定： ¥Checkbox and radio inputs can be bound with `bind:checked`: ```svelte ``` 自 5.6.0 起，如果 `` 具有 `defaultChecked` 属性并且是表单的一部分，则在重置表单时它将恢复为该值而不是 `false`。请注意，对于初始渲染，除非绑定的值是 `null` 或 `undefined`，否则绑定的值优先。 ¥Since 5.6.0, if an `` has a `defaultChecked` attribute and is part of a form, it will revert to that value instead of `false` when the form is reset. Note that for the initial render the value of the binding takes precedence unless it is `null` or `undefined`. ```svelte
    ``` ## `` 复选框可以处于 [indeterminate](https://web.nodejs.cn/en-US/docs/Web/API/HTMLInputElement/indeterminate) 状态，无论它们是否被选中： ¥Checkboxes can be in an [indeterminate](https://web.nodejs.cn/en-US/docs/Web/API/HTMLInputElement/indeterminate) state, independently of whether they are checked or unchecked: ```svelte
    {#if indeterminate} waiting... {:else if checked} checked {:else} unchecked {/if}
    ``` ## `` 可以协同工作的输入可以使用 `bind:group`（[demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE62T32_TMBDH_5XDQkpbrct7SCMGEvCEECDxsO7BSW6L2c227EvbKOv_jp0f6jYhQKJv5_P3PvdL1wstH1Bk4hMSGdgbRzUssFaM9VJciFtF6EV23QvubNRFR_BPUVfWXvodEkdfKT3-zl8Zzag5YETuK6csF1u9ZUIGNo4VkYQNvPYsGRfJF5JKJ8s3QRJE6WoFb2Nq6K-ck13u2Sl9Vxxhlc6QUBIFnz9Brm9ifJ6esun81XoNd860FmtwslYGlLYte5AO4aHlVhJ1gIeKWq92COt1iMtJlkhFPkgh1rHZiiF6K6BUus4G5KafGznCTlIbVUMfQZUWMJh5OrL-C_qjMYSwb1DyiH7iOEuCb1ZpWTUjfHqcwC_GWDVY3ZfmME_SGttSmD9IHaYatvWHIc6xLyqad3mq6KuqcCwnWn9p8p-p71BqP2IH81zc9w2in-od7XORP7ayCpd5YCeXI_-p59mObPF9WmwGpx3nqS2Gzw8TO3zOaS5_GqUXyQUkS3h8hOSz0ZhMESHGc0c4Hm3MAn00t1wrb0l2GZRkqvt4sXwczm6Qh8vnUJzI2LV4vAkvqWgfehTZrSSPx19WiVfFfAQAAA==)）： ¥Inputs that work together can use `bind:group` ([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE62T32_TMBDH_5XDQkpbrct7SCMGEvCEECDxsO7BSW6L2c227EvbKOv_jp0f6jYhQKJv5_P3PvdL1wstH1Bk4hMSGdgbRzUssFaM9VJciFtF6EV23QvubNRFR_BPUVfWXvodEkdfKT3-zl8Zzag5YETuK6csF1u9ZUIGNo4VkYQNvPYsGRfJF5JKJ8s3QRJE6WoFb2Nq6K-ck13u2Sl9Vxxhlc6QUBIFnz9Brm9ifJ6esun81XoNd860FmtwslYGlLYte5AO4aHlVhJ1gIeKWq92COt1iMtJlkhFPkgh1rHZiiF6K6BUus4G5KafGznCTlIbVUMfQZUWMJh5OrL-C_qjMYSwb1DyiH7iOEuCb1ZpWTUjfHqcwC_GWDVY3ZfmME_SGttSmD9IHaYatvWHIc6xLyqad3mq6KuqcCwnWn9p8p-p71BqP2IH81zc9w2in-od7XORP7ayCpd5YCeXI_-p59mObPF9WmwGpx3nqS2Gzw8TO3zOaS5_GqUXyQUkS3h8hOSz0ZhMESHGc0c4Hm3MAn00t1wrb0l2GZRkqvt4sXwczm6Qh8vnUJzI2LV4vAkvqWgfehTZrSSPx19WiVfFfAQAAA==)): ```svelte ``` > [!NOTE] 仅当输入位于同一个 Svelte 组件中时，`bind:group` 才有效。 ## `` 在具有 `type="file"` 的 `` 元素上，你可以使用 `bind:files` 来获取 [所选文件的 `FileList` 个](https://web.nodejs.cn/en-US/docs/Web/API/FileList)。当你想要以编程方式更新文件时，你始终需要使用 `FileList` 对象。目前无法直接构造 `FileList` 对象，因此你需要创建一个新的 [`DataTransfer`](https://web.nodejs.cn/en-US/docs/Web/API/DataTransfer) 对象并从那里获取 `files`。 ¥On `` elements with `type="file"`, you can use `bind:files` to get the [`FileList` of selected files](https://web.nodejs.cn/en-US/docs/Web/API/FileList). When you want to update the files programmatically, you always need to use a `FileList` object. Currently `FileList` objects cannot be constructed directly, so you need to create a new [`DataTransfer`](https://web.nodejs.cn/en-US/docs/Web/API/DataTransfer) object and get `files` from there. ```svelte ``` `FileList` 对象也无法修改，因此如果你想从列表中删除单个文件，则需要创建一个新的 `DataTransfer` 对象并添加要保留的文件。 ¥`FileList` objects also cannot be modified, so if you want to e.g. delete a single file from the list, you need to create a new `DataTransfer` object and add the files you want to keep. > [!NOTE] `DataTransfer` 可能在服务器端 JS 运行时不可用。如果组件在服务器端渲染，则将绑定到 `files` 的状态保持未初始化状态可以防止潜在的错误。 ## `` 值绑定对应于所选 ` ``` `` element behaves similarly to a checkbox group. The bound variable is an array with an entry corresponding to the `value` property of each selected `