Vue.js 3.5 中 useTemplateRef 与模板引用冲突问题解析

在 Vue.js 3.5 版本中，开发者在使用组合式 API 时可能会遇到一个特殊的警告信息："Set operation on key 'value' failed: target is readonly"。这个警告通常出现在同时使用 useTemplateRef 和模板引用(ref)的场景下，特别是当两者使用了相同的变量名时。

问题现象

当开发者在组件中同时使用以下两种方式引用同一个 DOM 元素时：

1. 通过 useTemplateRef 声明响应式引用
2. 在模板中使用 ref 属性绑定同名变量

控制台会持续输出上述警告信息。这个警告表明 Vue 尝试修改一个只读属性的值但失败了，虽然不影响功能实现，但会给开发者带来困扰。

技术原理

这个问题的根源在于 Vue 的响应式系统与模板引用机制的交互方式。在 Vue 3 中：

1. useTemplateRef 创建的是一个特殊的响应式引用对象
2. 模板中的 ref 属性会自动将 DOM 元素绑定到指定的变量
3. 当两者同名时，Vue 会尝试将 DOM 元素赋值给 useTemplateRef 创建的响应式引用
4. 由于 useTemplateRef 创建的引用具有特殊处理，导致赋值操作被拒绝

解决方案

目前推荐的解决方法是避免命名冲突：

1. 为 useTemplateRef 创建的变量和模板 ref 使用不同的名称
2. 或者只选择其中一种方式来引用 DOM 元素

例如，可以这样修改代码：

const inputRef = useTemplateRef()

然后在模板中使用不同的名称：

<input ref="input" />

最佳实践

为了避免这类问题，建议开发者：

1. 统一引用命名规范，如为 useTemplateRef 创建的变量添加 Ref 后缀
2. 在项目中保持一致的 DOM 引用方式（要么都用模板 ref，要么都用 useTemplateRef）
3. 关注 Vue 官方更新，未来版本可能会优化这一行为

总结

虽然这个问题不会影响实际功能，但它提醒我们在使用 Vue 的响应式系统时需要注意命名冲突的可能性。理解 Vue 响应式原理和模板编译过程，能够帮助开发者更好地规避这类边缘情况。随着 Vue 的持续发展，这类边界情况将会得到更好的处理。