原生代码与 Electron | Electron

Electron 最强大的功能之一，就是能够将 Web 技术与原生代码相结合 - 能在需要时用于计算密集型逻辑，亦或是少量的原生用户界面。
Electron 是通过在“原生 Node.js 插件”之上构建来实现的。你很有可能已经遇到了几个了 - 比如著名的 sqlite 就是使用原生代码将 JavaScript 与原生技术结合到了一起。你可以使用这个特性扩展你的 Electron 应用程序，使其能做到原生应用程序能完成的任何事：
原生 Node.js 插件是动态链接的共享对象（在类 Unix 系统上）或者 DLL 文件（在 Windows 上），可以使用 require() 或 import 函数加载到 Node.js 或 Electron 里。它们的行为就像是普通的 JavaScript 模块，但为用 C++，Rust，或其他可以编译成原生代码的语言编写的代码提供了一个接口。
本教程将带你构建一个能够在 Electron 应用程序内使用的基础 Node.js 原生插件。我们会聚焦于所有平台都共通的概念，使用 C++ 作为实现语言。一旦你完成了对所有原生 Node.js 插件都适用的本教程，你就可以移步到我们的平台限定教程的其中一个。
本教程假定你已经安装了 Node.js 和 npm，以及在你的平台上编译代码所需的必要基础工具（比如 Windows 上的 Visual Studio，macOS 上的 Xcode，Linux 上的 GCC/Clang）。你可以在 node-gyp readme 里找到详细说明。
要在 macOS 上构建原生 Node.js 插件，你需要安装 Xcode 命令行工具。其提供了必要的编译器和构建工具（即 clang、clang++ 以及 make）。下列命令会在你尚未安装命令行工具时指引你安装。
官方的 Node.js 安装程序提供了安装“适用于原生模块的工具”的可选项，其会安装编译基础 C++ 模块所需的一切工具 - 具体来说是 Python 3 和 “Visual Studio 使用 C++ 的桌面开发” 工作负荷。又或者，你可以使用 chocolatey，winget，或 Windows 商店。
首先，创建一个将会包含你的原生插件的 Node.js 包：
这会创建一个基础的 package.json 文件。接下来，我们安装必要的依赖：
现在，我们更新 package.json，加入适当的构建脚本。我们会在下文解释这些具体是做什么的。
Node.js 插件使用叫做 node-gyp 的构建系统，这是一个用 Node.js 编写的跨平台命令行工具。它在后台使用平台特定的构建工具编译 Node.js 的原生插件模块：
binding.gyp 文件是一个类 JSON 的配置文件，告诉 node-gyp 如何构建你的原生插件。它类似于 makefile 或工程文件，但采用的是独立于平台的格式。我们创建一个基础的 binding.gyp 文件：
先从在头文件里定义我们的 C++ 接口起步。创建 include/cpp_code.h：
#pragma once 指令是一个头文件防护指令，能够避免文件在相同的编译单元内被多次包含。实际的函数声明放在一个命名空间里面，以避免潜在的命名冲突。
接下来，我们在 src/cpp_code.cc 里实现这个函数：
这是个简单的实现，只是向输入字符串添加一些文本然后返回它。
现在，让我们编写将 C++ 代码与 Node.js/JavaScript 世界连接起来的插件代码。创建 src/my_addon.cc：
现在，我们创建一个 JavaScript 包装层，让插件更容易使用。创建 js/index.js：
这会运行 node-gyp configure 和 node-gyp build 将我们的 C++ 代码编译为一个 .node 文件。让我们创建一个简单的测试脚本来验证一切是否正常工作。在项目根目录创建 test.js：
要在一个 Electron 应用程序里使用这个插件，你需要：
原生插件开发可以使用 C++ 以外的几种语言编写。 Rust 可以使用像 napi-rs，neon，或 node-bindgen 之类的 Crate 来开发。在 macOS 上可以通过 Objective-C++ 使用 Objective-C/Swift。
具体的实现细节因平台差异而有很大的不同，尤其是访问平台特定的 API 或者 UI 框架的时候，比如 Windows 的 Win32 API、COM 组件、UWP/WinRT - 或者 macOS 的 Cocoa、AppKit、ObjectiveC 运行时。
这就意味着你编写原生代码时很可能需要两组参考资料：首先，在 Node.js 侧，使用 N-API 文档来学习如何创建并向 JavaScript 暴露复杂的结构体 - 比如异步线程安全函数的调用或者创建 JavaScript 原生对象（error、promise 等）。其次，在你所使用的技术侧，你很可能需要查阅它们的底层文档：
OpenJS Foundation | 使用条款 | 隐私政策 | 章程 | 行为准则 | 商标政策 | 商标列表 | Cookie 政策