创建新的 Electron 浏览器模块

欢迎阅读 Electron API指南！ 如果您对在 browser 目录内创建一个新的 Electron API 模块不太熟悉，本指南可作为您需要实施的一些必要步骤的清单。

这不是创建Electron Browser API的全面指南，而是记录一些更晦涩的步骤的大纲。

将您的文件添加到 Electron 的项目配置中

Electron使用 GN 作为元构建系统为其编译器 Ninja 生成文件。 这意味着，为了让Electron编译您的代码，我们必须将您的API的代码和头文件名添加到 filenames.gni。

您需要按字母顺序将 API 文件名追加到相应的文件中，如下所示：

filenames.gni

  1. lib_sources = [
  2.     "path/to/api/api_name.cc",
  3.     "path/to/api/api_name.h",
  4. ]
  6. lib_sources_mac = [
  7.     "path/to/api/api_name_mac.h",
  8.     "path/to/api/api_name_mac.mm",
  9. ]
  11. lib_sources_win = [
  12.     "path/to/api/api_name_win.cc",
  13.     "path/to/api/api_name_win.h",
  14. ]
  16. lib_sources_linux = [
  17.     "path/to/api/api_name_linux.cc",
  18.     "path/to/api/api_name_linux.h",
  19. ]

请注意，Windows、 macOS 和 Linux 数组添加是可选的，只有当您的 API 有具体的平台实现时才应被添加。

创建 API 文档

类型定义由 Electron 使用 @electron/docs-parser 和 @electron/typescript-definitions生成。 这个步骤对于确保Electron的 API 文档的一致性是必要的。 这意味着，要使 API 类型定义显示在 electron.d.ts 文件中，我们必须创建一个 .md 文件。 示例可以在此文件夹中找到。

设置 ObjectTemplateBuilder 和 Wrappable

Electron使用 object_template_builder构建其模块。

wrappable 是具有相应 v8 包装器对象C++对象的基类。

下面是您可能需要添加的代码的基本示例，以便将 object_template_builder 和 wrappable 合并到 API 中。 如需进一步参考，您可以在此处找到更多实现。

在 api_name.h 文件中：

api_name.h

  2. #ifndef ELECTRON_SHELL_BROWSER_API_ELECTRON_API_{API_NAME}_H_
  3. #define ELECTRON_SHELL_BROWSER_API_ELECTRON_API_{API_NAME}_H_
  5. #include "gin/handle.h"
  6. #include "gin/wrappable.h"
  8. namespace electron {
  10. namespace api {
  12. class ApiName : public gin::Wrappable<ApiName>  {
  13.  public:
  14.   static gin::Handle<ApiName> Create(v8::Isolate* isolate);
  16.   // gin::Wrappable
  17.   static gin::WrapperInfo kWrapperInfo;
  18.   gin::ObjectTemplateBuilder GetObjectTemplateBuilder(
  19.       v8::Isolate* isolate) override;
  20.   const char* GetTypeName() override;
  21. } // namespace api
  22. } // namespace electron

在 api_name.cc 文件中：

api_name.cc

  1. #include "shell/browser/api/electron_api_safe_storage.h"
  3. #include "shell/browser/browser.h"
  4. #include "shell/common/gin_converters/base_converter.h"
  5. #include "shell/common/gin_converters/callback_converter.h"
  6. #include "shell/common/gin_helper/dictionary.h"
  7. #include "shell/common/gin_helper/object_template_builder.h"
  8. #include "shell/common/node_includes.h"
  9. #include "shell/common/platform_util.h"
  11. namespace electron {
  13. namespace api {
  15. gin::WrapperInfo ApiName::kWrapperInfo = {gin::kEmbedderNativeGin};
  17. gin::ObjectTemplateBuilder ApiName::GetObjectTemplateBuilder(
  18.     v8::Isolate* isolate) {
  19.   return gin::ObjectTemplateBuilder(isolate)
  20.       .SetMethod("methodName", &ApiName::methodName);
  21. }
  23. const char* ApiName::GetTypeName() {
  24.   return "ApiName";
  25. }
  27. // static
  28. gin::Handle<ApiName> ApiName::Create(v8::Isolate* isolate) {
  29.   return gin::CreateHandle(isolate, new ApiName());
  30. }
  32. } // namespace api
  34. } // namespace electron
  36. namespace {
  38. void Initialize(v8::Local<v8::Object> exports,
  39.                 v8::Local<v8::Value> unused,
  40.                 v8::Local<v8::Context> context,
  41.                 void* priv) {
  42.   v8::Isolate* isolate = context->GetIsolate();
  43.   gin_helper::Dictionary dict(isolate, exports);
  44.   dict.Set("apiName", electron::api::ApiName::Create(isolate));
  45. }
  47. }  // namespace

In the typings/internal-ambient.d.ts file, we need to append a new property onto the Process interface like so:

typings/internal-ambient.d.ts

  1. interface Process {
  2.     _linkedBinding(name: 'electron_browser_{api_name}', Electron.ApiName);
  3. }

At the very bottom of your api_name.cc file:

api_name.cc

  1. NODE_LINKED_MODULE_CONTEXT_AWARE(electron_browser_{api_name},Initialize)

In your shell/common/node_bindings.cc file, add your node binding name to Electron’s built-in modules.

shell/common/node_bindings.cc

  1. #define ELECTRON_BROWSER_MODULES(V)      \
  2.   V(electron_browser_{api_name})

Note: More technical details on how Node links with Electron can be found on our blog.

向 TypeScript 公开你的 API

将 API 导出为模块

我们需要在以下路径中创建一个新的 TypeScript 文件：

"lib/browser/api/{electron_browser_{api_name}}.ts"

此文件的内容示例可在这里找到。

向 TypeScript 公开你的模块

Add your module to the module list found at "lib/browser/api/module-list.ts" like so:

lib/browser/api/module-list.ts

  1. export const browserModuleList: ElectronInternal.ModuleEntry[] = [
  2.   { name: 'apiName', loader: () => require('./api-name') },
  3. ];