实用指南：Vue 3 useModel vs defineModel：选择正确的双向绑定方案

概述

useModel() 是 Vue 3.4+ 版本中引入的一个组合式 API 辅助函数，它是驱动 defineModel() 的底层实现。这个函数主要用于在非单文件组件中实现双向数据绑定，特别是在使用原始的 setup() 函数时。

⚠️ 重要提示：如果使用 <script setup>，应当优先使用 defineModel()。

基本概念

什么是 useModel？

useModel() 是一个用于创建双向数据绑定的底层辅助函数。它允许子组件直接修改父组件传递的 prop 值，而无需手动触发 emit 事件。

与 defineModel 的关系

特性	defineModel()	useModel()
使用场景	<script setup> 语法糖	底层实现
代码简洁度	⭐⭐⭐⭐⭐	⭐⭐⭐
控制精细度	⭐⭐⭐	⭐⭐⭐⭐⭐
推荐程度	应当优先使用	特定场景使用

• ✅ defineModel() 是 <script setup> 中的语法糖，更简洁易用，应当优先使用
•  useModel() 是底层实现，适用于非单文件组件或需要更精细控制的场景

函数签名

function useModel(
props: Record,
key: string,
options?: DefineModelOptions
): ModelRef;
type DefineModelOptions = {
get?: (v: T) => any;
set?: (v: T) => any;
};
type ModelRef = Ref &
[ModelRef, Record];

参数说明

参数	类型	必需	描述
props	Record<string, any>	✅	组件的 props 对象
key	string	✅	要绑定的 prop 名称
options	DefineModelOptions	❌	自定义 getter 和 setter 函数

使用场景

1️⃣ 非单文件组件中的双向绑定

当使用传统的 setup() 函数而不是 <script setup> 时，useModel() 是创建双向绑定的最佳选择。在 <script setup> 中，请优先使用 defineModel()。

2️⃣ 需要自定义转换逻辑

当需要对传入和传出的值进行转换时，可以使用 options 参数。

3️⃣ 复杂的组件库开发

在开发可复用的组件库时，可能需要更精细的控制。

代码示例

基础用法

export default {
props: ["count"],
emits: ["update:count"],
setup(props) {
const count = useModel(props, "count");
// 直接修改值会自动触发 emit
count.value = 1;
return {
count,
};
},
};

带自定义转换的用法

export default {
props: ["value"],
emits: ["update:value"],
setup(props) {
const modelValue = useModel(props, "value", {
// 自定义 getter：将字符串转换为数字
get: (v) => (v ? parseInt(v) : 0),
// 自定义 setter：将数字转换为字符串
set: (v) => v.toString(),
});
return {
modelValue,
};
},
};

在模板中使用

export default {
props: ["count"],
emits: ["update:count"],
setup(props) {
const count = useModel(props, "count");
return {
count,
};
},
};

⚖️ 与 defineModel 的对比

✅ defineModel (推荐用于 script setup)

const count = defineModel("count");

useModel (适用于 setup 函数)

export default {
props: ["count"],
emits: ["update:count"],
setup(props) {
const count = useModel(props, "count");
return { count };
},
};

⚠️ 注意事项

版本要求

• 仅在 Vue 3.4+ 版本中可用
• ✅ 确保项目依赖版本满足要求

Props 和 Emits 声明

与 defineModel() 不同，使用 useModel() 时需要手动声明：

• props 数组或对象
• emits 数组或对象

️ 类型安全

在 TypeScript 项目中，建议为 props 和 emits 提供完整的类型定义：

interface Props {
count: number;
}
interface Emits {
"update:count": [value: number];
}
export default {
props: ["count"] as PropType,
emits: ["update:count"] as Emits,
setup(props: Props) {
const count = useModel(props, "count");
return { count };
},
};

最佳实践

1️⃣ 优先使用 defineModel

在 <script setup> 中，应当优先使用 defineModel()，代码更简洁易读。 只有在以下情况下才考虑使用 useModel()：

• 使用传统的 setup() 函数
• ⚙️ 需要更精细的控制和自定义转换逻辑
• 开发复杂的组件库

2️⃣ 合理使用自定义转换

只在确实需要数据转换时使用 options 参数，避免过度复杂化。

3️⃣ 保持一致性

在同一个项目中，保持双向绑定的实现方式一致。

4️⃣ 类型安全

在 TypeScript 项目中，始终提供完整的类型定义。

❓ 常见问题

Q: 什么时候使用 useModel 而不是 defineModel？

A: 在 <script setup> 中，应当优先使用 defineModel()。 只有在以下情况下才使用 useModel()：

• 使用传统的 setup() 函数而不是 <script setup>
• ⚙️ 需要自定义 getter/setter 进行复杂的数据转换
• ️ 需要更精细的控制逻辑

Q: useModel 是否支持多个双向绑定？

A: 是的，可以多次调用 useModel() 来创建多个双向绑定。

Q: 如何处理复杂的验证逻辑？

A: 可以在 options.set 中添加验证逻辑，如果验证失败可以抛出错误或返回原值。

总结

useModel() 是 Vue 3.4+ 中实现双向数据绑定的强大工具，特别适用于非单文件组件。重要原则：在 <script setup> 中，应当优先使用 defineModel()，代码更简洁易读。 只有在使用传统的 setup() 函数或需要更精细控制时，才考虑使用 useModel()。理解这两个 API 的使用场景和差异，有助于在 Vue 3 项目中更好地实现组件间的数据通信。

Vue 3 useModel vs defineModel：选择正确的双向绑定方案 - 高质量源码分享平台-免费下载各类网站源码与模板及前沿技术分享