Vue+TypeScript使用Floating UI时出现[RefSymbol]缺失类型错误

问题场景 #

在 Vue + TypeScript 项目中使用 Floating UI 的 useFloating 时，传递普通 ref 实例会触发如下类型错误：

代码示例：

import { ref } from 'vue';
import { ReferenceElement, useFloating } from '@floating-ui/vue';

const reference = ref<ReferenceElement>();
const floating = ref<HTMLElement>();
  
useFloating(reference, floating);

错误提示：

Argument of type 'Ref<ReferenceElement | undefined>' is not assignable to parameter of type 'Readonly<Ref<MaybeElement<ReferenceElement>>>'.
  Property '[RefSymbol]' is missing in type 'Ref<ReferenceElement | undefined>' but required in type 'Readonly<Ref<MaybeElement<ReferenceElement>>>'.ts(2345)
reactivity.d.ts(384, 5): '[RefSymbol]' is declared here.

错误原因 #

Floating UI 的 useFloating 类型定义要求参数为 Readonly<Ref<MaybeElement<T>>>，但 Vue 的 Ref 接口中用于类型区分的 [RefSymbol] 是私有符号属性。当依赖版本不兼容或类型推导严格时，TypeScript 无法确认该属性存在，从而抛出错误。

可行解决方案（非错误抑制） #

1. 升级依赖版本（优先推荐）

这个错误大多源于 Floating UI 与 Vue 的类型定义版本不匹配。直接升级到两者的最新稳定版通常能解决问题：

# npm
npm update @floating-ui/vue vue

# yarn
yarn upgrade @floating-ui/vue vue

2. 显式断言 ref 类型

通过类型断言让 TypeScript 确认 ref 符合 Readonly<Ref> 要求：

import { ref, Ref } from 'vue';
import { ReferenceElement, useFloating } from '@floating-ui/vue';

const reference = ref<ReferenceElement>() as Readonly<Ref<ReferenceElement | undefined>>;
const floating = ref<HTMLElement>() as Readonly<Ref<HTMLElement | undefined>>;

useFloating(reference, floating);

3. 使用 shallowRef 替代 ref

如果不需要深度响应式，shallowRef 的类型声明更简洁，可绕过符号属性的校验问题：

import { shallowRef } from 'vue';
import { ReferenceElement, useFloating } from '@floating-ui/vue';

const reference = shallowRef<ReferenceElement>();
const floating = shallowRef<HTMLElement>();

useFloating(reference, floating);

4. 覆盖 Floating UI 类型声明

创建类型声明文件（如 src/types/floating-ui-fix.d.ts），修改 useFloating 的参数类型要求：

import type { Ref } from 'vue';
import type { ReferenceElement, FloatingElement, UseFloatingOptions, UseFloatingReturn } from '@floating-ui/vue';

declare module '@floating-ui/vue' {
  export function useFloating<T extends ReferenceElement = ReferenceElement>(
    reference: Ref<ReferenceElement | undefined>,
    floating: Ref<FloatingElement | undefined>,
    options?: UseFloatingOptions<T>
  ): UseFloatingReturn;
}

此方法移除了对 Readonly 和 MaybeElement 的严格约束，让普通 Ref 可以正常传入。

内容的提问来源于stack exchange，提问作者Matt Bryson