Svelte `$bindable` rune：让组件 Props 双向绑定成为一等公民

在 Svelte 的 runes 模式下，props 默认只能从父组件流向子组件。$bindable rune 打破了这一单向约束：通过它把某个 prop 标记为可绑定后，数据可以沿 bind: 指令反向流动，从子组件流回父组件。读完本篇，你将掌握 $bindable 的完整用法（含 fallback 值规则）、它在编译器分析阶段与客户端转换阶段的具体实现位置，以及如何结合 bind: 指令 在真实项目中安全地构建父子双向通信。

从单向 props 到双向绑定

按照惯例，props 是单向的：父组件把值传下去，子组件只读。这让数据流向清晰可预测。而 Svelte 允许将组件 prop 变为可绑定（bindable）状态，即数据也可以从子组件向上传递。

官方文档对此给出了明确的克制度提示：

• 双向绑定不是应该经常做的事——过度使用会让数据流向变得难以预测，组件也更难维护；
• 但谨慎、少量地使用它可以显著简化代码（典型场景就是封装输入框这类"值会被用户修改"的控件）；
• 它还意味着子组件内可以直接**修改（mutate）**这个 state proxy，例如对数组 push、对对象改属性、对数字执行 ++。

这里有一个重要的边界区分（原文档 NOTE）：普通（非 $bindable）prop 其实也能被修改，但这是强烈不推荐的行为——Svelte 在检测到组件修改了自己并不"拥有"的状态时会发出警告。$bindable 把这个"灰色操作"变成了显式声明的合法 API：父组件用 bind: 表明"这个值我们共享，你可以改我"，子组件的修改就顺理成章地回流。

基本用法：标记 bindable prop

要用 $bindable rune 标记一个 prop，只需把它作为解构默认值写进 $props() 声明中：

/// file: FancyInput.svelte
<script>
	let { value = $bindable(), ...props } = $props();
</script>

<input bind:value={value} {...props} />

<style>
	input {
		font-family: 'Comic Sans MS';
		color: deeppink;
	}
</style>

关键点在于 input 上的 bind:value={value}：用户输入改变了 value，而 value 是绑定 prop，这个改变会沿着父组件的 bind: 回传。

父组件侧使用 bind: 指令：

/// file: App.svelte
<script>
	import FancyInput from './FancyInput.svelte';

	let message = $state('hello');
</script>

<FancyInput bind:value={message} />
<p>{message}</p>

此时 <p>{message}</p> 与输入框内容实时同步——子组件里的输入直接改写了父组件的 $state。仓库中的运行时测试 props-bound/Counter.svelte 验证了另一条常见路径：子组件自己修改 bindable prop 也能触发更新：

<script>
	let { count = $bindable() } = $props();
</script>

<button on:click={() => count++}>{count}</button>

父组件并非必须使用 bind:

文档特别指出：父组件没有义务使用 bind:，它完全可以只传一个普通 prop——"有些父组件不想听孩子说什么"。$bindable 是一种能力声明（capability），而不是一种强制契约。这带来两个好处：

1. 同一个组件既能被双向绑定，也能被只读传值，复用语义清晰；
2. 子组件内部对 bindable prop 的修改在"父端只读"场景下表现为子组件本地的私有状态，不会越权改父组件数据。

Fallback 值与绑定歧义规则

当没有传入任何 prop 时，你可以给 bindable prop 指定一个 fallback 值：

/// file: FancyInput.svelte
let { value = $bindable('fallback'), ...props } = $props();

类型签名上，$bindable 接受零个或一个参数，并在 ambient.d.ts 中声明为 declare function $bindable<T>(fallback?: T): T;——有 fallback 时返回类型即 fallback 的类型，无 fallback 时返回未定义的 T。

核心规则：当 bindable prop 带有 fallback 值时，父组件若使用 bind:，必须传入一个非 undefined 的值。原因很直白：绑定意味着父子应当共享同一个值，如果父端传了 undefined 而子端又有 fallback，就会存在"到底以哪个为准"的歧义。

这条规则不只是文档约定，编译器与运行时都有对应的约束检查。例如测试用例 ownership-invalid-binding-bindable-fallback 就构造了带对象 fallback 的链式绑定场景来验证所有权边界：

// Parent.svelte
<script>
	import Child from './Child.svelte';

	let { test = $bindable({}) } = $props();
</script>

<Child bind:test />

带 fallback 场景的更多行为可以参见 props-bound-fallback 测试样本。

编译器视角：$bindable 的位置与参数约束

只能出现在 $props() 解构中

$bindable() 的使用位置在编译期被严格校验。编译器报错定义见 errors.js，对应 编译错误文档：

bindable_invalid_location：$bindable() can only be used inside a $props() declaration

在 CallExpression 分析访问器 中可以看到校验逻辑：

• 参数数量超过 1 个时报 rune_invalid_arguments_length（只允许 0 或 1 个参数）；
• 节点的父级必须是 AssignmentPattern（即 x = $bindable() 形式的解构默认值），且再往上是 ObjectPattern，再往上是 VariableDeclarator，且该声明的初始化表达式必须是 $props() 调用——四者缺一即报 bindable_invalid_location；
• 校验通过后还会置位 context.state.analysis.needs_context = true，源码注释说明这是"以防绑定的 prop 过期（stale）"，即运行时需要上下文来判断绑定值的归属。

对应的反例测试样本在 runes-wrong-bindable-args 与 runes-wrong-bindable-placement，分别覆盖参数错误与位置错误两类编译错误。

分析阶段：解包 fallback 并打上 bindable_prop 标记

在 VariableDeclarator 访问器 中，编译器遍历 $props() 解构的每个属性：当发现默认值形如 $bindable(...) 调用时，会剥离 $bindable 包装——把 $bindable('fallback') 的第一个参数直接作为该 binding 的 initial 值，并把 binding.kind 设为 'bindable_prop'（普通 prop 则是 'prop'）。从源码结构看，bindable_prop 这个 kind 是后续所有差异化处理（转换、警告、所有权检查）的分发依据。

运行时视角：数据如何"流回去"

客户端转换阶段，编译器为 bindable_prop 生成了专门的读写转换。在 Program.js 中：

• 读：生成 getter 调用，每次读取拿到的是"父端绑定值 or 本地 fallback 值"中正确的那个；
• 赋值：assign 生成调用，把新值通过绑定通道推回父端；
• 修改（mutate）：对 bindable_prop，mutate 会额外传入 true 标志（源码注释写明这是"为与 legacy 父端绑定做互操作"），从而让子组件对 proxy 的原地修改（push、++ 等）也能触发父端感知；
• ++/-- 更新：走 $.update_prop / $.update_pre_prop 专用助手函数，保证先读后写都经过绑定语义而非裸状态写。

如果父组件对一个未标记为 bindable 的 prop 使用 bind:，开发期会触发 运行时错误 bind_not_bindable：

A component is attempting to bind to a non-bindable property %key% belonging to %component%. To mark a property as bindable: let { %key% = $bindable() } = $props()

错误信息直接给出了修复方案，把"运行时踩坑"变成了一行可执行的提示。

另外，前文提到"普通 prop 修改会被警告"——相关警告文案中就明确引用了 [$bindable](https://gitcode.com/GitHub_Trending/sv/svelte/blob/b2c22ab66d0978dfa14bb92196a6ab45ad0031a4/packages/svelte/messages/client-warnings/warnings.md?utm_source=gitcode_repo_files#L268) 作为替代手段："要么创建回调 prop 来通信，要么把该属性标记为 $bindable"。仓库中 non-local-mutation-with-binding 等一系列测试样本系统性地覆盖了"拥有权 + 绑定 + 修改"的各种组合，是理解这套所有权模型的好入口。

TypeScript 类型标注下的 $bindable

在开启 TypeScript 的组件中，$props() 同样支持类型标注，$bindable 参与联合声明。从 ambient.d.ts 的示例注释可以看到用法形态：

let { optionalProp = 42, requiredProp, bindableProp = $bindable() }: {
  optionalProp?: number;
  requiredProp: string;
  bindableProp: boolean;
} = $props();

类型标注让 $bindable 参与的 prop 与可选/必传 prop 共享同一套类型推导，IDE 中能获得完整的参数提示。

使用建议与最佳实践

结合文档告诫与源码中大量的所有权测试（runtime-runes 下的 non-local-mutation 系列），可以总结三条实践原则：

1. 少量使用：双向绑定优先留给"值型控件"（输入框、选择器、计数器）这类天然有回写需求的组件；对复杂业务逻辑，回调用回调 prop 往往更可控。
2. fallback 与 bind: 二选一的语义要牢记：给了 fallback，父端 bind: 就必须传非 undefined 值，避免共享值歧义；
3. 区分"拥有"与"借用"：$bindable 是显式声明"这个值不是我独有"的机制，它把原本会触发所有权警告的灰色修改变成了合法路径——这是它相比"直接改普通 prop"的核心价值。

相关测试与实现入口汇总：

关注点	位置
位置/参数校验	CallExpression.js
fallback 解包与 kind 标记	VariableDeclarator.js
客户端读写/mutate 转换	Program.js
运行时 bind_not_bindable 错误	errors.js
基础行为测试	props-bound、props-bound-fallback
链式绑定与所有权	ownership-invalid-binding-bindable-fallback、async-bindable-prop
编译错误反例	runes-wrong-bindable-placement、runes-wrong-bindable-args

至此，$bindable 的完整链路已经清楚：父组件 bind: 声明共享 → 子组件 $props() 解构中以 $bindable()（可带 fallback）标记 → 编译器打上 bindable_prop 标记并生成经绑定通道的读写/mutate 转换 → 子组件的修改与赋值合规地回流父端，越界绑定则由 bind_not_bindable 错误与所有权警告兜底。