Vue3组合式函数返回的ref值在v-if中无法自动解包问题求助

问题现象 #

创建了包含响应式布尔值的组合式函数useToggle，但该函数返回的ref布尔值在模板的v-if指令中无法自动解包，必须使用.value才能生效；而组件内直接定义的ref布尔值却可以正常自动解包。相关代码如下：

useToggle.ts 文件 #

import { ref } from "vue";

const visible = ref(true);

export function useToggle() {
  function toggle() {
    visible.value = !visible.value;
  }

  function close() {
    visible.value = false;
  }

  return {
    visible,
    toggle,
    close,
  };
}

App.vue 文件 #

<script setup lang="ts">
import { ref } from "vue";
import { useToggle } from "./useToggle";

const visible = ref(true);
const t = useToggle();
</script>

<template>
  <button @click="visible = !visible">toggle local</button>
  <div v-if="visible">local</div>

  <button @click="t.toggle">toggle global without value</button>
  <div v-if="t.visible">global (this doesn't work)</div>
  <div v-if="t.visible.value">global (this doesn't work)</div>

  {{t.visible}} (but this, updates)
</template>

原因分析 #

1. 模板自动解包规则限制：Vue模板仅会对组件上下文的顶级ref属性自动解包。你返回的visible是挂载在t对象下的嵌套属性，不属于组件顶级属性，因此无法自动解包。
2. 模块级变量的副作用：visible被定义在useToggle函数外部，属于模块级变量——多个组件调用useToggle时会共享同一个visible实例，这不仅不符合组合式函数的状态隔离原则，还可能引发意外的状态污染。

解决方案 #

步骤1：修正组合式函数的状态定义 #

将visible移到useToggle函数内部，确保每次调用组合式函数都创建独立的响应式状态：

import { ref } from "vue";

export function useToggle() {
  // 将visible移至函数内部，实现状态隔离
  const visible = ref(true);

  function toggle() {
    visible.value = !visible.value;
  }

  function close() {
    visible.value = false;
  }

  return {
    visible,
    toggle,
    close,
  };
}

步骤2：解构返回值，让ref成为组件顶级属性 #

在组件中解构useToggle的返回值，使visible成为组件的顶级属性，符合Vue的自动解包规则：

<script setup lang="ts">
import { ref } from "vue";
import { useToggle } from "./useToggle";

const visible = ref(true);
// 解构返回值，将组合式函数的visible重命名为toggleVisible避免冲突
const { visible: toggleVisible, toggle, close } = useToggle();
</script>

<template>
  <button @click="visible = !visible">toggle local</button>
  <div v-if="visible">local</div>

  <button @click="toggle">toggle global</button>
  <div v-if="toggleVisible">global (now works)</div>

  {{ toggleVisible }}
</template>

替代方案（Vue 3.3+）：使用$ref()显式解包 #

如果不想解构，也可以在模板中用$ref()API显式解包嵌套的ref：

<div v-if="$ref(t.visible)">global</div>

但解构的方式更符合组合式函数的最佳实践，代码可读性更高。

内容的提问来源于stack exchange，提问作者Artur Carvalho