Vue3 转 React：组件透传 Attributes 与 useAttrs 使用详解｜VuReact 实战

在 Vue 转 React 的开发场景中，组件透传 Attributes（透传属性）是高频且易踩坑的知识点。Vue 与 React 对"透传属性"的设计理念、访问方式差异显著，而 VuReact 作为 Vue3 转 React 的核心工具，在处理这一特性时既保留 Vue 开发习惯，又贴合 React 生态规范。本文将从概念解析、API 适配、实战示例、类型安全等维度，详解 VuReact 中组件透传 Attributes 的使用方式。

一、先搞懂：透传 Attributes 是什么？

1. Vue 中的透传 Attributes

Vue 官方定义：透传 attribute 指传递给组件、但未被该组件声明为 props 或 emits 的 attribute（如 class、style、id）或 v-on 事件监听器。它是 Vue 内置的"运行时魔法"，默认会自动透传到组件的根元素上，也可通过 $attrs 或 useAttrs() 手动访问。

2. React 中的"透传属性"思维

React 中没有"透传属性"的专属概念------所有传入组件的属性都通过 props 接收，无论是否提前声明。但 React 对类型校验严格：若未显式定义 props 类型，TypeScript 会报错；若想支持"任意未声明属性"，需手动扩展类型，这也是 VuReact 适配的核心切入点。

3. VuReact 对透传 Attributes 的核心适配逻辑

VuReact 认为：透传 attribute 本质是无类型约束的 JavaScript 运行时对象，会与组件已声明的 props 合并，构成最终的属性集合。

• 若组件无声明 props：自动生成 props: Record<string, unknown>，允许传递任意属性；
• 若组件已声明 props：将声明类型与 Record<string, unknown> 交叉合并，既保留已声明 props 的类型提示，又支持任意透传属性。

二、关键：从 Vue $attrs 转向 useAttrs()

Vue 中访问透传属性有两种方式：$attrs（运行时隐式变量）和 useAttrs()（显式 API）。但对于 VuReact 编译器而言，$attrs 是"运行时魔法"------无静态声明、不可分析，无法精准转换为 React 代码；而 useAttrs() 是静态可分析的显式调用，也是 VuReact 推荐的唯一方式。

1. Vue 中 useAttrs() 的基础用法（必掌握）

按 Vue 官方规范，在 <script setup> 中通过 useAttrs() 显式获取透传属性：

<script setup>
import { useAttrs } from 'vue';

// 接收所有未声明为 props 的透传属性
const attrs = useAttrs();
</script>

该写法的核心优势：

• 静态可分析：VuReact 编译器能精准识别 attrs 变量的来源，确保转换逻辑可控；
• 类型可扩展：支持 TypeScript 类型注解，避免盲猜属性；
• 行为可预期：替代 $attrs 的隐式魔法，符合 React "显式传参"的设计理念。

2. VuReact 对 useAttrs() 的核心转换规则

VuReact 会将 useAttrs() 直接转换为 React 中对 props 的引用，并自动处理类型断言，核心规则如下：

Vue 中 useAttrs() 用法	VuReact 转换后的 React 代码逻辑
无类型注解（默认）	const attrs = props as Record<string, unknown>
带类型断言（如 useAttrs() as Attrs）	保留类型断言，转换为 const attrs = props as Attrs
变量带类型注解（如 const attrs: Attrs = useAttrs()）	自动将 props 断言为指定类型，转换为 const attrs = props as Attrs
组件已声明 props	将 props 类型与透传属性类型交叉合并（如 ICompProps & Record<string, unknown>）

三、实战：Vue 转 React 透传 Attributes 完整示例

示例 1：基础用法（无自定义类型）

Vue 输入

<template>
  <!-- 手动绑定透传的 class、style -->
  <div :class="attrs.class" :style="attrs.style">
    {{ attrs.title }}
  </div>
</template>

<script setup>
import { useAttrs } from 'vue';

// 无类型注解，接收所有透传属性
const attrs = useAttrs();
</script>

VuReact 输出（React/TSX）

import { memo } from 'react';

// 无声明 props，自动生成 Record<string, unknown> 类型
const Comp = memo((props: Record<string, unknown>) => {
  // 转换 useAttrs() 为 props 引用
  const attrs = props as Record<string, unknown>;

  return (
    <div className={attrs.class} style={attrs.style}>
      {attrs.title}
    </div>
  );
});

export default Comp;

示例 2：TypeScript 类型增强（推荐）

Vue 输入

<template>
  <div 
    :class="attrs.class" 
    :style="attrs.style"
    data-id="container"
  >
    {{ attrs.customTitle }}
  </div>
</template>

<script setup lang="ts">
import { useAttrs } from 'vue';

// 1. 声明透传属性的类型
interface CustomAttrs {
  class?: string;
  style?: React.CSSProperties; // 适配 React style 类型
  customTitle?: string;
  [key: string]: unknown; // 兼容其他未声明属性
}

// 2. 声明组件自有 props
const props = defineProps<{
  id: string; // 组件核心属性
}>();

// 3. 显式获取透传属性并绑定类型
const attrs = useAttrs() as CustomAttrs;
</script>

VuReact 输出（React/TSX）

import { memo } from 'react';

// 1. 保留自定义透传属性类型
interface CustomAttrs {
  class?: string;
  style?: React.CSSProperties;
  customTitle?: string;
  [key: string]: unknown;
}

// 2. 自有 props 类型
type ICompProps = {
  id: string;
} ;

// 3. 组件定义：透传属性类型交叉合并，既支持 id，又支持任意透传属性
const Comp = memo((props: ICompProps & Record<string, unknown>) => {
  // 4. 转换 useAttrs() 为带类型的 props 引用
  const attrs = props as CustomAttrs;

  return (
    <div 
      className={attrs.class} 
      style={attrs.style}
      data-id="container"
    >
      {attrs.customTitle}
    </div>
  );
});

export default Comp;

示例 3：模板中动态访问透传属性

Vue 中支持的动态属性访问语法，VuReact 也能完整适配：

Vue 输入

<template>
  <div
    :class="[
      'base-class',
      attrs.class,
      attrs.xx?.class,
      attrs['custom-class'],
      attrs?.['dynamic-class']
    ]"
  >
    {{ attrs?.xxx?.['content'] }}
  </div>
</template>

<script setup lang="ts">
import { useAttrs } from 'vue';

interface Attrs {
  class?: string;
  xx?: { class?: string };
  'custom-class'?: string;
  'dynamic-class'?: string;
  xxx?: { content?: string };
}

const attrs = useAttrs() as Attrs;
</script>

VuReact 输出（React/TSX）

import { memo } from 'react';
import { dir } from '@vureact/runtime-core';

interface Attrs {
  class?: string;
  xx?: { class?: string };
  'custom-class'?: string;
  'dynamic-class'?: string;
  xxx?: { content?: string };
}

const Comp = memo((props: Record<string, unknown>) => {
  const attrs = props as Attrs;

  return (
    <div
      className={dir.cls([
        'base-class',
        attrs.class,
        attrs.xx?.class,
        attrs['custom-class'],
        attrs?.['dynamic-class']
      ])}
    >
      {attrs?.xxx?.['content']}
    </div>
  );
});

export default Comp;

四、VuReact 转换的注意事项（避坑指南）

1. 必须显式使用 useAttrs()

   禁止使用 $attrs 隐式访问------VuReact 编译器无法分析运行时变量，会导致转换失败或属性丢失。

2. 类型安全：优先添加注解

   即使不需要严格类型，也建议声明 interface 约束常用属性（如 class、style），避免访问不存在的属性导致运行时错误。

3. React 特有的属性适配

   • Vue 中的 class 会转换为 React 的 className，style 会适配 React.CSSProperties 类型；
   • 事件透传（如 @click）会转换为 React 事件（onClick），需在类型中声明对应的事件处理函数。

4. 与 defineProps 配合的类型合并

   若组件已通过 defineProps 声明 props，VuReact 会自动将声明类型与 Record<string, unknown> 交叉合并，无需手动处理。

5. 纯 JavaScript 环境的适配

   若未使用 TypeScript，useAttrs() 会直接转换为 const attrs = props，保留所有透传属性的访问能力。

五、总结

VuReact 处理 Vue3 透传 Attributes 的核心思路是：从 Vue 隐式的 $attrs 转向显式的 useAttrs()，再映射到 React 显式的 props 体系。

• 对开发者：只需遵循 Vue 官方的 useAttrs() 用法，即可无缝迁移到 React，无需重构属性访问逻辑；
• 对类型：支持 TypeScript 完整适配，既保留 Vue 的开发习惯，又满足 React 的类型校验要求；
• 对编译：通过静态分析 useAttrs() 调用，确保转换逻辑精准、可预期。

遵循本文的用法，你可以在 Vue 转 React 项目中优雅处理组件透传属性，兼顾开发效率与代码健壮性。

---

🔗 相关资源

• GitHub：https://github.com/vureact-js/core
• Gitee：https://gitee.com/vureact-js/core
• 章节文档：https://vureact.top/guide/conversion-script.html#_9-useattrs-透传属性处理
• NPM：https://www.npmjs.com/package/@vureact/compiler-core
• 在线演示：https://codesandbox.io/p/github/vureact-js/example-crm-admin-backend/master

---

推荐阅读

• Vue 语法写 React？VuReact 来了

• Vue转React实战：defineProps精准迁移实战

• Vue3转React实战：VuReact 可控混写迁移指南