vuact

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vuact

Vuact is a React runtime compatibility layer for Vue 3. It enables seamless usage of the React component ecosystem inside Vue 3 projects, with two-way interoperability between Vue and React for components, events, reactivity, Context, Ref, and more.

Key value:

Seamlessly use React components in Vue apps
Support bidirectional migration: Vue ↔ React
Use Vue and React in the same application
Build cross-stack component libraries in a React-like way

Vuact 是面向Vue 3的React运行时兼容层。它允许在Vue 3项目中无缝使用React组件生态，实现Vue与React之间组件、事件、响应式、Context、Ref等的双向互操作。

核心价值:

在Vue应用中无缝使用React组件
支持双向迁移：Vue ↔ React
在同一应用中同时使用Vue和React
以类React的方式构建跨栈组件库

Quick Start

快速开始

For the full configuration and initialization flow, see setup-config.md.

完整的配置与初始化流程，请查看setup-config.md。

Core Capabilities

核心功能

1. Component Conversion

1. 组件转换

Vuact provides two core functions to convert components between Vue and React:

r2v (react-to-vue): Convert a React component into a Vue component
v2r (vue-to-react): Convert a Vue component into a React component

Examples:

r2v Basics
v2r Basics

Vuact 提供两个核心函数用于在Vue与React之间转换组件：

r2v (react-to-vue)：将React组件转换为Vue组件
v2r (vue-to-react)：将Vue组件转换为React组件

示例:

r2v 基础用法
v2r 基础用法

2. Slots and Render Props

2. 插槽与渲染属性

Vuact provides a flexible slots and render-props transformation mechanism:

On the Vue side, you can pass children, element props, or render props to React components via slots
On the React side, you can pass slots to Vue components via props prefixed with
```
slot:
```
r2v Render Props and Slots
v2r Slots

Vuact 提供灵活的插槽与渲染属性转换机制：

在Vue端，可通过插槽向React组件传递子元素、元素属性或渲染属性
在React端，可通过前缀为
```
slot:
```
的属性向Vue组件传递插槽
r2v 渲染属性与插槽
v2r 插槽

3. Events and Props Interop

3. 事件与属性互操作

Vuact automatically transforms props and events between Vue and React:

Vue
```
class
```
→ React
```
className
```
Vue
```
style
```
(string or object) → React
```
style
```
(object)
React
```
className
```
→ Vue
```
class
```
React
```
style
```
(object; auto-add
```
px
```
for unitless values) → Vue
```
style
```
Vue
```
v-model
```
update events → React
```
onUpdate:xxx
```

Examples:

r2v Event Callbacks
v2r Event Callbacks

Vuact 会自动在Vue与React之间转换属性和事件：

Vue
```
class
```
→ React
```
className
```
Vue
```
style
```
（字符串或对象）→ React
```
style
```
（对象）
React
```
className
```
→ Vue
```
class
```
React
```
style
```
（对象；为无单位值自动添加
```
px
```
）→ Vue
```
style
```
Vue
```
v-model
```
更新事件 → React
```
onUpdate:xxx
```

示例:

r2v 事件回调
v2r 事件回调

4. Context Interop

4. Context互操作

Vuact supports two-way Context passing between Vue and React:

On the Vue side, you can provide React Context to React components via
```
provideContext
```
On the React side, you can provide Vue Context to Vue components via
```
VueContextProvider
```
Context can pass through both frameworks

Examples:

r2v React Context
r2v Vue Context
v2r React Context
v2r Vue Context

Vuact 支持Vue与React之间的双向Context传递：

在Vue端，可通过
```
provideContext
```
向React组件提供React Context
在React端，可通过
```
VueContextProvider
```
向Vue组件提供Vue Context
Context可在两个框架间传递

示例:

r2v React Context
r2v Vue Context
v2r React Context
v2r Vue Context

5. Ref Interop

5. Ref互操作

Vuact supports passing refs between Vue and React components:

On the Vue side, use
```
ref
```
to get a React component instance
On the React side, use
```
ref
```
to get a Vue component instance
For function components, expose methods via
```
useImperativeHandle
```

Examples:

r2v Component Ref
v2r Component Ref

Vuact 支持在Vue与React组件之间传递Ref：

在Vue端，使用
```
ref
```
获取React组件实例
在React端，使用
```
ref
```
获取Vue组件实例
对于函数组件，通过
```
useImperativeHandle
```
暴露方法

示例:

r2v 组件Ref
v2r 组件Ref

6. Use Vue Hooks in React Components

6. 在React组件中使用Vue Hooks

Vuact lets you use Vue reactivity directly inside React components:

Create a Vue reactive scope via
```
useVueEffectScope
```
Use Vue hooks like
```
ref
```
,
```
watch
```
,
```
computed
```
, etc. within that scope
Combine the reactivity systems from both frameworks

Examples:

r2v Vue Hooks
r2v Hybrid Components

Vuact 允许在React组件中直接使用Vue响应式功能：

通过
```
useVueEffectScope
```
创建Vue响应式作用域
在该作用域内使用Vue Hooks，如
```
ref
```
、
```
watch
```
、
```
computed
```
等
结合两个框架的响应式系统

示例:

r2v Vue Hooks
r2v 混合组件

Compatibility and Limitations

兼容性与限制

Version Compatibility

版本兼容性

React: mainly compatible with React 16–18; React 19 support is in progress
Vue: requires Vue >= 3.5
Build tools: ESM-only; requires a modern bundler

React：主要兼容React 16–18；React 19支持正在开发中
Vue：要求Vue >= 3.5
构建工具：仅支持ESM；需要现代打包工具

Known Limitations

已知限制

Because Vuact is essentially based on Vue, some behaviors cannot fully match React:

Concurrent rendering: Vue renders recursively, so React concurrent rendering cannot be replicated
Commit phase: Vue mutates the DOM during recursive rendering; there is no explicit commit phase like React
- ```
useInsertionEffect
```
  timing differs from React
- ```
getSnapshotBeforeUpdate
```
  timing differs from React
Event system:
```
@vue/runtime-dom
```
cannot fully match
```
react-dom
```
- ```
react-dom
```
  's
```
SyntheticEvent
```
  differs from standard web events
- ```
react-dom
```
  applies special handling for some native DOM elements (e.g.
```
input
```
  ,
```
form
```
  , etc.)

由于Vuact本质上基于Vue，部分行为无法完全匹配React：

并发渲染：Vue采用递归渲染，无法复现React的并发渲染
提交阶段：Vue在递归渲染期间修改DOM，没有像React那样明确的提交阶段
- ```
useInsertionEffect
```
  的执行时机与React不同
- ```
getSnapshotBeforeUpdate
```
  的执行时机与React不同
事件系统：
```
@vue/runtime-dom
```
无法完全匹配
```
react-dom
```
- ```
react-dom
```
  的
```
SyntheticEvent
```
  与标准Web事件不同
- ```
react-dom
```
  对部分原生DOM元素（如
```
input
```
  、
```
form
```
  等）有特殊处理

Full Examples

完整示例

Load the relevant reference docs to get complete example code and detailed explanations.

加载相关参考文档获取完整示例代码与详细说明。

Vue → React (r2v)

r2v Basics - The most basic way to use React components from Vue
r2v Event Callbacks - Event passing between Vue and React components
r2v Hybrid Components - Mix Vue and React, using capabilities from both frameworks
r2v React Context - Provide React Context to React components from Vue
r2v Component Ref - Get React component refs from Vue
r2v Render Props and Slots - Render props and element props usage for React components
r2v Vue Context - Provide Vue Context to React components from Vue
r2v Vue Hooks - Use Vue hooks inside React components

r2v 基础用法 - 在Vue中使用React组件的最基础方式
r2v 事件回调 - Vue与React组件之间的事件传递
r2v 混合组件 - 混合使用Vue与React，结合两者的能力
r2v React Context - 在Vue中为React组件提供React Context
r2v 组件Ref - 在Vue中获取React组件的Ref
r2v 渲染属性与插槽 - React组件的渲染属性与元素属性用法
r2v Vue Context - 在Vue中为React组件提供Vue Context
r2v Vue Hooks - 在React组件中使用Vue Hooks

React → Vue (v2r)

v2r Basics - The most basic way to use Vue components from React
v2r Event Callbacks - Event passing between React and Vue components
v2r React Context - Provide React Context to Vue components from React
v2r Component Ref - Get Vue component refs from React
v2r Slots - Pass slots to Vue components from React
v2r Vue Context - Provide Vue Context to Vue components from React

v2r 基础用法 - 在React中使用Vue组件的最基础方式
v2r 事件回调 - React与Vue组件之间的事件传递
v2r React Context - 在React中为Vue组件提供React Context
v2r 组件Ref - 在React中获取Vue组件的Ref
v2r 插槽 - 在React中向Vue组件传递插槽
v2r Vue Context - 在React中为Vue组件提供Vue Context

Configuration and Initialization

配置与初始化

setup-config.md - Full configuration and initialization guide (more complete than the README)

setup-config.md - 完整的配置与初始化指南（比README更全面）