企业官网建设流程全解析

• 桌面应用
• 跨平台

React NodeGui 是一款面向桌面端的 React 渲染器：它不用 HTML、CSS 与浏览器，而是让 React 直接驱动由 Qt 创建的原生窗口与原生控件。本文以官方入门教程（website/docs/guides/tutorial.md）为核心脉络，带你从零理解 React NodeGui 应用的基本结构、Window等组件的底层原理，并跑通官方 starter 项目；读完你将能够独立搭建第一个原生桌面应用，并知道下一步如何深入样式与布局。

React NodeGui 开发，一句话概括

在开发层面，一个 React NodeGui 应用本质上就是一个Node.js 应用。它没有自己的包管理器、没有特殊的运行时要求，一切从一个与普通 Node.js 模块完全一致的package.json开始。一个最基础的 React NodeGui 应用只需要两个文件：

your-app/ ├── package.json ├── index.js

所有 React NodeGui 提供的 API 和功能，都通过@nodegui/react-nodegui与@nodegui/nodegui两个模块暴露，用法与require任何普通 Node.js 模块完全一致：

require("@nodegui/react-nodegui");

与此同时，整个 Node.js 标准库和 npm 生态中任意可用的 Node 模块，都可以直接在 React NodeGui 应用中使用——这一点在本教程的后面会再次强调。

在仓库中可以看到，@nodegui/react-nodegui的入口文件 src/index.ts 就是一张完整的“导出清单”，它把Window、View、Text、Button、CheckBox等组件以及Renderer、useEventHandler、热重载工具hot、appProxy全部按命名空间方式导出。也就是说，教程中所说的“@nodegui/react-nodegui模块在命名空间中导出组件和功能”，在源码层面有着清晰的一一对应。

第一个最小应用：用Window组件开一个窗口

教程给出的最简应用是一个函数式 React 组件，配合Renderer.render完成渲染：

const { Window, Renderer } = require("@nodegui/react-nodegui"); const App = () => { return <Window></Window>; }; Renderer.render(<App />);

这里的index.js（或main.js）职责很明确：创建窗口，并处理应用可能遇到的所有系统事件。

值得展开的是Renderer.render这一步。查看 src/renderer/index.ts 的实现可以发现，它内部做了两件事：

1. 通过reconciler.createContainer(containerInfo, isConcurrent, hydrate)创建 React 的根 Fiber 节点（当前实现开启了 concurrent 模式）；
2. 通过reconciler.updateContainer(element, Renderer.container, parentComponent, callback)启动协调（reconciliation）并真正渲染结果。

这正是 React NodeGui 之所以“是 React”的底层原因：它基于react-reconciler实现了一套自定义 host config。在 src/reconciler/index.ts 中可以看到完整的宿主配置，包括createInstance、appendChild、removeChild、commitUpdate等生命周期回调；组件则通过 src/components/config.ts 中的registerComponent注册进一个tagName → ComponentConfig映射表，由 reconciler 按标签名查表创建对应原生控件。这套机制与 React DOM、React Native 属于同一类架构，只是把“宿主环境”从浏览器换成了 Qt。

这里到底发生了什么？

教程用一节专门回答了“What's going on here”，核心结论有三点，值得逐条结合源码印证：

第一，你运行的是 Node.js 应用，而不是浏览器应用。因此 React NodeGui 应用里没有document、window（浏览器全局对象）等任何浏览器 API；你看到的窗口是 Qt 创建的原生窗口控件，而不是一个被浏览器包裹的 HTML 页面。

第二，Window组件本质上是一个轻量级 JavaScript 包装器。查看 src/components/Window/RNWindow.ts 可以看到，RNWindow类直接继承自 NodeGui 的QMainWindow，而QMainWindow内部就是 Qt 的QMainWindow：

export class RNWindow extends QMainWindow implements RNWidget { setProps(newProps: WindowProps, oldProps: WindowProps): void { setWindowProps(this, newProps, oldProps); } ... static tagName = "mainwindow"; }

这意味着你在 JSX 里给<Window>设置的每一个 prop（windowTitle、minSize、styleSheet、menuBar等），最终都会作用到那个真实的原生窗口控件上。setWindowProps中的 setter 会把 prop 映射为对应的 Qt 方法调用，例如menuBar对应window.setMenuBar(menubar)（见 src/components/Window/RNWindow.ts）。

第三，相比浏览器方案，它非常轻量，离操作系统更近。因为控件就是系统级的原生控件，没有 DOM、没有浏览器渲染引擎这一层间接成本。顺便一提，RNWindow对子节点有明确的约束：它只允许一个 central widget 和一个 menu bar，多子节点或第二个菜单栏会打印警告（见 src/components/Window/RNWindow.ts），这一点在写布局时值得留意。

在 React NodeGui 中，任何组件类的命名都遵循RN前缀（如RNView、RNText），并实现RNWidget接口（setProps、appendChild、removeChild等），static tagName则标明它在 JSX 中的标签名。

跑通官方 Starter 项目

最快体验 React NodeGui 的方式，是克隆并运行官方 starter 仓库nodegui/react-nodegui-starter。

前提条件：需要安装 Git 与 npm，并且本机已配置好 Node.js 与 npm 环境（node -v、npm -v能正常输出版本号）。

按以下步骤操作：

# 克隆仓库 $ git clone https://github.com/nodegui/react-nodegui-starter # 进入仓库目录 $ cd react-nodegui-starter # 安装依赖 $ npm install # 运行 dev server（负责编译与热更新） $ npm run dev # 在另一个终端标签页或窗口中启动应用 $ npm start

npm run dev与npm start的职责划分可以从当前仓库的 package.json 中看到同类脚本的影子：dev脚本执行tsc && qode ./dist/demo.js，即先编译 TypeScript，再用 NodeGui 专用运行时qode加载编译产物；而start则负责真正拉起应用进程。两个命令通常需要分开的终端窗口同时运行。

克隆下来后，你可以直接修改 starter 里的组件代码并观察窗口实时变化——这就完成了你的第一个 React NodeGui 应用。

除了基本窗口，还有什么？

React NodeGui 内置了一批与 Web 世界概念对应的基础组件。教程点名的有：

• View—— 类似 Web 中的div，用于包裹其他组件、组织结构。在 src/components/View/RNView.ts 中可以看到，RNView直接继承 Qt 的QWidget，并且会在添加第一个子节点时自动创建FlexLayout来管理布局——这是后面学习 布局指南 时的重要前提。
• CheckBox、PushButton（即Button）等交互控件。

完整列表见 src/index.ts 的导出项，包括：BoxView、GridView（含GridRow/GridColumn）、Slider、Text、Image、AnimatedImage、LineEdit、PlainTextEdit、Calendar、ProgressBar、RadioButton、Dial、SpinBox、ScrollArea、ComboBox、SystemTrayIcon、Tabs/TabItem、各类对话框（Dialog、ColorDialog、FileDialog、FontDialog、InputDialog、ProgressDialog、ErrorPrompt）、Table/TableItem、List/ListItem、Menu/MenuBar等 30 余个组件。

每个组件的可用 prop 定义在其对应接口中，例如View的完整 props（visible、styleSheet、style、geometry、id、mouseTracking、enabled、windowOpacity、windowTitle、windowState、cursor、minSize/maxSize/size、pos、on、ref、attributes、windowFlags）可以在 ViewProps 接口文档 中查阅；其他组件的 props 接口文档位于 website/docs/api/interfaces 目录下，例如 buttonprops.md、checkboxprops.md。

从 prop 到原生行为的映射，同样可以在源码中找到证据：setViewProps（见 src/components/View/RNView.ts）为id调用widget.setObjectName(id)、为visible调用widget.show()/hide()、为styleSheet调用widget.setStyleSheet(...)。也就是说，<View id="foo" />在底层就是把 Qt 控件的 objectName 设为foo，这与 Web 中id的作用方式神似但机制完全不同。

除此之外，正如教程强调的：React NodeGui 应用可以访问整个 Node.js 模块生态。任何你在 Node.js 中能用的模块，都可以直接在 React NodeGui 中使用——文件读写、网络请求、数据库驱动等能力开箱即用，这让桌面应用的能力边界被极大扩展。

一个稍完整的组合示例

把Window、View、Text、Button组合起来，就能得到一个带有样式和结构的真实界面。仓库自带的示例 src/demo.tsx 展示了这种组合方式：

import React from "react"; import { Text, Renderer, Window, Button, View } from "."; const App = () => { return ( <Window styleSheet={styleSheet}> <View id="container"> <View id="textContainer"> <Text>Hello</Text> </View> <View> <Button text="Click me"></Button> </View> </View> </Window> ); }; const styleSheet = ` #container { flex: 1; min-height: '100%'; justify-content: 'center'; } #textContainer { flex-direction: 'row'; justify-content: 'space-around'; align-items: 'center'; } `; Renderer.render(<App />);

注意两点：样式以 CSS 字符串形式通过styleSheetprop 传入，且支持flex、justify-content、align-items等 flexbox 属性；#container这样的选择器引用的正是组件上设置的id。

下一步：让界面更漂亮

“我只想要比原生控件更定制、更漂亮的界面，怎么办？”——答案是样式系统。React NodeGui 的样式基于 Qt Style Sheets（语法与 Web CSS 几乎一致），同时通过styleprop 支持内联样式，并通过 Facebook 的 Yoga 库提供 flexbox 布局支持。样式、选择器、伪状态（如:hover）、级联规则、qproperty-*高级用法等完整内容，请继续阅读 样式指南（Styling），随后可以接着学习 布局指南（Layout）。

至此，你已经掌握了 React NodeGui 应用的基本骨架：Node.js 工程结构、Renderer.render渲染入口、Window/View/Text等原生组件的使用与底层映射，以及如何跑通官方 starter。接下来就是边改代码边观察原生窗口反馈，开始构建属于你的桌面应用了。

• 桌面应用
• 跨平台