企业官网建设流程全解析

二、3 步快速上手：安装与 Hello World

1. 安装依赖

react-ionize 依赖 React 16 的 alpha 版本（Fiber 架构），安装命令如下：

npm install --save electron npm install --save react@16.0.0-alpha.5 npm install --save react-ionize

2. 最小可运行示例

const React = require('react'); const Ionize = require('react-ionize'); Ionize.start( <app> <window show file={INDEX_HTML_PATH} /> </app> );

3. 理解Ionize.start(element, [callback])

Ionize.start是整个应用的入口，它会等待 Electron 的'ready'事件后再开始渲染元素。其内部实现可参考 IonizeFiber.js，它封装了ReactFiberReconciler并暴露出start、update、chain、reset四个方法。

所有元素都继承自统一的基类 BaseElement.js，元素类型与类的映射关系定义在 elements/index.js 的createElectronInstance函数中——这个文件是速查元素的"总目录"。

三、核心理念：元素即意图

理解 react-ionize 所有元素之前，先记住一个关键设计原则：

组件树中存在某个元素 = 你"想要"它存在。Ionize 会在渲染时确保它的存在。

这带来了与常规 React 不同的行为：如果你想让窗口真正消失，必须确保对应的<window/>元素被unmount（卸载）——仅仅隐藏是不够的，元素卸载时才会触发 finalizeBeforeRemoval 关闭窗口。

四、元素速查表（总览）

五、 ：应用级事件挂载点

<app>是整个组件树的顶层挂载点，用于注册与全局应用相关的事件处理器。它的子元素通常包括：浏览器窗口、对话框、托盘等（托盘等能力仍在规划中）。

可用 API

• onReady：组件挂载时立即触发。虽然 Ionize 内部在渲染前已经等待过ready事件，但为了 API 一致性仍提供了这个处理器。

实现细节：AppElement.js 中finalizeBeforeMount方法会把 props 中形如onXXX的事件通过app.on(eventKey, handler)挂载到 Electron 的app对象上，卸载时再统一移除，避免内存泄漏。

六、 ：用声明式语法管理窗口

<window>代表一个 ElectronBrowserWindow实例，是 react-ionize 中属性最丰富的元素。它内部在 WindowElement.js 中创建new BrowserWindow({ show: false, ... })，即默认先隐藏，由show属性控制显隐。

完整属性速查表

关键机制：受控属性 vs 非受控属性

这是使用<window>最容易踩坑的地方，官方在 WindowElement.js 的注释中专门解释了"受控属性"（Controlled Attributes）：

• size（受控）：单独提供size时，窗口会被设为resizable: false，用户无法调整大小——它必须"就是"这个尺寸。想让用户能调整，必须同时提供onResize，并在回调中更新size的值。这与 React 中<input>受控组件的行为完全一致。
• defaultSize（非受控）：如果你不想手动追踪大小，用它设置初始尺寸，之后用户爱怎么拖就怎么拖。

position/defaultPosition/onMove/onMoved的组合规则与size系列完全对称。⚠️ 多显示器环境下，位置坐标可能会出现"怪异"值。

三种典型窗口写法（对应官方示例）

// 写法一：固定尺寸，用户不可调整（受控） <window show file={...} size={[300, 300]} position={[120, 120]} /> // 写法二：初始尺寸 800x800，用户可自由调整（非受控） <window show file={...} defaultSize={[800, 800]} /> // 写法三：初始位置 [100,100]，用户可自由拖动 <window show file={...} defaultPosition={[100, 100]} />

这三种写法分别对应仓库中的示例文件 default-size.js、position.js、fixed-size.js，建议直接运行npm start查看效果（通过EXAMPLE_ENTRY环境变量切换示例入口）。

七、、 、 ：声明式菜单系统

Electron 原生的菜单 API 需要层层Menu.buildFromTemplate、MenuItem嵌套，而 react-ionize 让它回归声明式：

<menu> <submenu label="Edit"> <undo /> <redo /> <sep /> <copy /> <paste /> <selectall /> </submenu> <submenu label="Custom Menu"> <item label="Foo the bars" onClick={handleClick} /> </submenu> </menu>

定义整个应用菜单。挂载时会创建new Menu()并调用Menu.setApplicationMenu(menu)应用到全局，实现见 MenuElement.js 中的commitApplicationMenu函数。

及兄弟元素

Role 元素是 react-ionize 的隐藏福利：凡是 Electron 支持的role值，都可以直接当作元素名使用。完整支持列表定义在 MenuItemElement.js：

• 通用 role：undo、redo、cut、copy、paste、pasteandmatchstyle、selectall、delete、minimize、close、quit、reload、forcereload、toggledevtools、togglefullscreen、resetzoom、zoomin、zoomout
• macOS 专属 role：about、hide、hideothers、unhide、startspeaking、stopspeaking、front、zoom、window、help、services

动态菜单：状态驱动 UI

菜单同样遵循 React 数据流。官方示例 dynamic-menu.js 展示了菜单项随 state 变化而变化的完整写法：

render() { const { counter } = this.state; return ( <app> <menu> <submenu label="Custom Menu"> <item label={LABELS[counter % 5]} onClick={() => this.setState({ counter: counter + 1 })} /> </submenu> </menu> <window show file={...} position={[120, 120]} size={[300, 300]} /> </app> ); }

<item>的label和onClick都是支持的响应式属性（见 MenuItemElement.js 的SUPPORTED_PROPS），更新时会自动重建MenuItem。

八、进阶：chain 与 ref 的实用技巧

除了start，IonizeFiber.js 还提供Ionize.chain(element, callback, element2, callback2, ...)方法，用于按顺序依次更新组件树，适合需要在两次渲染之间插入逻辑的场景。

此外元素支持ref，通过getPublicInstance()可拿到真实的 Electron 对象（如BrowserWindow、MenuItem），在 test/menu.spec.js 的测试中可以看到用 ref 断言菜单项状态的实际用例。

九、新手避坑清单 📋

1. 窗口关不掉？检查<window>是否真正从组件树中移除，而非只改了show。
2. size固定后用户拖不动？这是受控属性的预期行为，需要配对onResize。
3. macOS 第一个菜单名改不掉？系统强制用应用名，把自定义菜单放第二个<submenu>。
4. acceptFirstMouse运行时修改无效并触发console.warn，它只在窗口首次渲染时生效。
5. 版本锁定：必须使用react@16.0.0-alpha.5，这是 peerDependencies 的唯一版本。

十、总结

react-ionize 把 Electron 主进程的繁琐 API 抽象成了熟悉的 React 元素：

• <app>—— 全局事件挂载点
• <window>—— 声明式窗口管理，核心是"受控属性 + 对应事件处理器"的组合
• <menu>/<submenu>/<item>—— 声明式菜单，role 元素直接映射系统功能

如果你已经熟悉 React 的组件与状态思维，react-ionize 会让 Electron 桌面应用的开发体验平滑许多。虽然它仍处于实验阶段，但其"用 React 管理一切状态"的设计思路，对理解 Fiber 自定义渲染器（参考 IonizeHostConfig.js 中的 Host Config 实现）也有很好的学习价值。