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()显式获取透传属性：
<scriptsetup>import{useAttrs}from'vue';// 接收所有未声明为 props 的透传属性constattrs=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><scriptsetup>import{useAttrs}from'vue';// 无类型注解，接收所有透传属性constattrs=useAttrs();</script>VuReact 输出（React/TSX）
import{memo}from'react';// 无声明 props，自动生成 Record<string, unknown> 类型constComp=memo((props:Record<string,unknown>)=>{// 转换 useAttrs() 为 props 引用constattrs=propsasRecord<string,unknown>;return(<div className={attrs.class}style={attrs.style}>{attrs.title}</div>);});exportdefaultComp;示例 2：TypeScript 类型增强（推荐）
Vue 输入
<template><div:class="attrs.class":style="attrs.style"data-id="container">{{ attrs.customTitle }}</div></template><scriptsetuplang="ts">import{useAttrs}from'vue';// 1. 声明透传属性的类型interfaceCustomAttrs{class?:string;style?:React.CSSProperties;// 适配 React style 类型customTitle?:string;[key:string]:unknown;// 兼容其他未声明属性}// 2. 声明组件自有 propsconstprops=defineProps<{id:string;// 组件核心属性}>();// 3. 显式获取透传属性并绑定类型constattrs=useAttrs()asCustomAttrs;</script>VuReact 输出（React/TSX）
import{memo}from'react';// 1. 保留自定义透传属性类型interfaceCustomAttrs{class?:string;style?:React.CSSProperties;customTitle?:string;[key:string]:unknown;}// 2. 自有 props 类型typeICompProps={id:string;};// 3. 组件定义：透传属性类型交叉合并，既支持 id，又支持任意透传属性constComp=memo((props:ICompProps&Record<string,unknown>)=>{// 4. 转换 useAttrs() 为带类型的 props 引用constattrs=propsasCustomAttrs;return(<div className={attrs.class}style={attrs.style}data-id="container">{attrs.customTitle}</div>);});exportdefaultComp;示例 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><scriptsetuplang="ts">import{useAttrs}from'vue';interfaceAttrs{class?:string;xx?:{class?:string};'custom-class'?:string;'dynamic-class'?:string;xxx?:{content?:string};}constattrs=useAttrs()asAttrs;</script>VuReact 输出（React/TSX）
import{memo}from'react';import{dir}from'@vureact/runtime-core';interfaceAttrs{class?:string;xx?:{class?:string};'custom-class'?:string;'dynamic-class'?:string;xxx?:{content?:string};}constComp=memo((props:Record<string,unknown>)=>{constattrs=propsasAttrs;return(<div className={dir.cls(['base-class',attrs.class,attrs.xx?.class,attrs['custom-class'],attrs?.['dynamic-class']])}>{attrs?.xxx?.['content']}</div>);});exportdefaultComp;四、VuReact 转换的注意事项（避坑指南）
必须显式使用
useAttrs()
禁止使用$attrs隐式访问——VuReact 编译器无法分析运行时变量，会导致转换失败或属性丢失。类型安全：优先添加注解
即使不需要严格类型，也建议声明interface约束常用属性（如class、style），避免访问不存在的属性导致运行时错误。React 特有的属性适配
- Vue 中的
class会转换为 React 的className，style会适配 React.CSSProperties 类型； - 事件透传（如
@click）会转换为 React 事件（onClick），需在类型中声明对应的事件处理函数。
- Vue 中的
与
defineProps配合的类型合并
若组件已通过defineProps声明 props，VuReact 会自动将声明类型与Record<string, unknown>交叉合并，无需手动处理。纯 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 可控混写迁移指南