必须显式调用 ref(null) 并在模板中用同名字符串 ref="username"，才能使 username.value 精确指向原生 input dom 实例；若误用 :ref="username" 则无法自动绑定且易覆盖初始值。

在 Vue 3 的 setup 中，若模板里有原生输入框（如 <input type="text">），想用同名 ref 变量实现**精确绑定**（即 ref 名和 input 的 ref 特性值一致，并能正确获取 DOM 实例），关键在于：**不能仅靠变量名匹配，必须显式调用 ref() 并在模板中用同名字符串赋给 ref 特性**。

1. 正确声明同名 ref 变量

在 setup 中用 ref(null) 初始化，变量名与模板中 ref 特性的值严格一致（区分大小写、无空格）：

Vuejs

Vue.js 官方推荐通过 npm 进行安装，这是构建现代化前端项目最主流的方式。在终端中执行 npm install vue 即可获取最新稳定版，如需指定版本可添加 @版本号，例如 npm install vue@3.4.0。安装前请确保已配置 Node.js 环境（推荐 v18 及以上版本），并建议将 npm 镜像源切换至国内镜像以提升下载速度。对于大型项目，还可通过 npm create v

下载

import { ref } from 'vue'

export default {
  setup() {
    const username = ref(null) // ← 变量名 = 'username'
    
    return {
      username // ← 必须暴露，供模板访问
    }
  }
}

2. 模板中使用同名字符串 ref 特性

在模板中，给原生 <input> 设置 ref="username"（注意是字符串字面量，不是 :ref="username"）：

<template><input ref="username" type="text" placeholder="请输入用户名"></template>

✅ 这样 Vue 才会在挂载后把该 DOM 元素赋值给 username.value；
❌ 若写成 :ref="username"，会触发 ref 回调，但无法自动绑定到 username.value，且容易覆盖初始值。

3. 验证与使用 DOM 实例

组件挂载后，username.value 即为原生 <input> 元素，可直接操作：

• 聚焦：username.value?.focus()
• 取值：username.value?.value
• 设值：username.value.value = 'admin'
• 监听事件时配合 onMounted 确保 DOM 已就绪

4. 注意事项

• ref 名必须是合法标识符（如 userInput 可以，user-input 不行）
• 多个同名 ref 会导致最后一个覆盖前面的（不推荐重名）
• 服务端渲染（SSR）时 ref 值为 null，需加空值判断
• 若需响应式控制输入内容，应另配 v-model 绑定数据，ref 仅用于 DOM 操作