Skip to main content

Electron 的结构化 API 文档

· 7 min read
zeke

今天，我们宣布对 Electron 的文档进行一些改进。现在每个新版本都包含一个 JSON 文件，详细描述 Electron 的所有公共 API。我们创建此文件是为了让开发者能够以有趣的新方式使用 Electron 的 API 文档。

¥Today we're announcing some improvements to Electron's documentation. Every new release now includes a JSON file that describes all of Electron's public APIs in detail. We created this file to enable developers to use Electron's API documentation in interesting new ways.

架构概述​

¥Schema overview

每个 API 都是一个对象，具有名称、描述、类型等属性。诸如 BrowserWindow 和 Menu 之类的类具有描述其实例方法、实例属性、实例事件等的附加属性。

¥Each API is an object with properties like name, description, type, etc. Classes such as BrowserWindow and Menu have additional properties describing their instance methods, instance properties, instance events, etc.

以下是描述 BrowserWindow 类的架构摘录：

¥Here's an excerpt from the schema that describes the BrowserWindow class:

{
  name: 'BrowserWindow',
  description: 'Create and control browser windows.',
  process: {
    main: true,
    renderer: false
  },
  type: 'Class',
  instanceName: 'win',
  slug: 'browser-window',
  websiteUrl: 'https://electron.nodejs.cn/docs/api/browser-window',
  repoUrl: 'https://github.com/electron/electron/blob/v1.4.0/docs/api/browser-window.md',
  staticMethods: [...],
  instanceMethods: [...],
  instanceProperties: [...],
  instanceEvents: [...]
}

这是一个方法描述的示例，在本例中是 apis.BrowserWindow.instanceMethods.setMaximumSize 实例方法：

¥And here's an example of a method description, in this case the apis.BrowserWindow.instanceMethods.setMaximumSize instance method:

{
  name: 'setMaximumSize',
  signature: '(width, height)',
  description: 'Sets the maximum size of window to width and height.',
  parameters: [{
    name: 'width',
    type: 'Integer'
  }, {
    name: 'height',
    type: 'Integer'
  }]
}

使用新数据​

¥Using the new data

为了方便开发者在他们的项目中使用这些结构化数据，我们创建了 electron-docs-api，这是一个小型 npm 包，每当有新的 Electron 版本发布时都会自动发布。

¥To make it easy for developers to use this structured data in their projects, we've created electron-docs-api, a small npm package that is published automatically whenever there's a new Electron release.

npm install electron-api-docs --save

为了立即获得满足，请在你的 Node.js REPL 中试用该模块：

¥For instant gratification, try out the module in your Node.js REPL:

npm i -g trymodule && trymodule electron-api-docs=apis

数据如何收集​

¥How the data is collected

Electron 的 API 文档遵循 ​​Electron 编码风格 和 Electron 代码规范，因此其内容可以通过编程方式解析。

¥Electron's API documentation adheres to Electron Coding Style and the Electron Styleguide, so its content can be programmatically parsed.

electron-docs-linter 是 electron/electron 存储库的新开发依赖。它是一个命令行工具，可以检查所有 Markdown 文件并强制执行样式指南的规则。如果发现错误，则会列出错误并停止发布流程。如果 API 文档有效，则会创建 electron-json.api 文件，并且 已上传至 GitHub 将作为 Electron 版本的一部分。

¥The electron-docs-linter is a new development dependency of the electron/electron repository. It is a command-line tool that lints all the markdown files and enforces the rules of the styleguide. If errors are found, they are listed and the release process is halted. If the API docs are valid, the electron-json.api file is created and uploaded to GitHub as part of the Electron release.

标准 Javascript 和标准 Markdown​

¥Standard Javascript and Standard Markdown

今年早些时候，Electron 的代码库已更新，所有 JavaScript 代码均使用 standard 语法检查器。Standard 的 README 总结了这一选择背后的原因：

¥Earlier this year, Electron's codebase was updated to use the standard linter for all JavaScript. Standard's README sums up the reasoning behind this choice:

采用标准风格意味着将代码清晰度和社区约定的重要性置于个人风格之上。这可能并不适用于所有项目和开发文化，但开源对新手来说可能并不友好。设置清晰、自动化的贡献者期望值，使项目更健康。

¥Adopting standard style means ranking the importance of code clarity and community conventions higher than personal style. This might not make sense for 100% of projects and development cultures, however open source can be a hostile place for newbies. Setting up clear, automated contributor expectations makes a project healthier.

我们最近还创建了 standard-markdown，用于验证文档中的所有 JavaScript 代码片段是否有效，并与代码库本身的样式一致。

¥We also recently created standard-markdown to verify that all the JavaScript code snippets in our documentation are valid and consistent with the style in the codebase itself.

这些工具共同帮助我们使用持续集成 (CI) 自动查找拉取请求中的错误。这减轻了人工代码审查的负担，并使我们对文档的准确性更有信心。

¥Together these tools help us use continuous integration (CI) to automatically find errors in pull requests. This reduces the burden placed on humans doing code review, and gives us more confidence about the accuracy of our documentation.

社区成果​

¥A community effort

Electron 的文档在不断改进，这要感谢我们优秀的开源社区。截至撰写本文时，已有近 300 人为文档做出了贡献。

¥Electron's documentation is constantly improving, and we have our awesome open-source community to thank for it. As of this writing, nearly 300 people have contributed to the docs.

我们很期待看到人们如何使用这些新的结构化数据。可能的用途包括：

¥We're excited to see what people do with this new structured data. Possible uses include: