Electron 文档风格指南¶

以下是编写 Electron 文档的指南。

标题¶

每个页面顶部必须有且只有一个 # 级标题。
同一页面中的章节必须使用 ## 级标题。
子章节需要根据其嵌套深度增加标题中 # 的数量。
页面标题必须遵循 APA 标题大小写。
所有章节都必须遵循 APA 句子大小写。

以 Quick Start 为例：

# Quick Start

...

## Main process

...

## Renderer process

...

## Run your app

...

### Run as a distribution

...

### Manually downloaded Electron binary

...

对于 API 参考文档，此规则存在例外情况。

Markdown 规则¶

本仓库使用 markdownlint 包来强制保持一致的 Markdown 样式。有关具体规则，请参阅根文件夹中的 .markdownlint.json 文件。

以下是一些未被 linter 规则覆盖的样式指南：

在代码块中使用 sh 而不是 cmd（由于语法高亮器）。
为了便于阅读，尽可能将行长度保持在 80 到 100 个字符之间。
列表嵌套不要超过 2 层（由于 Markdown 渲染器）。
所有 js 和 javascript 代码块都使用 standard-markdown 进行 lint。
对于无序列表，请使用星号而不是破折号。

用词选择¶

在描述结果时，优先使用 “will” 而不是 “would”。
优先使用 “in the ___ process” 而不是 “on”。

API 参考¶

以下规则仅适用于 API 的文档。

标题和描述¶

每个模块的 API 文档必须使用 require('electron') 返回的实际对象名称作为其标题（例如 BrowserWindow、autoUpdater 和 session）。

在页面标题正下方，添加一行模块描述，作为 Markdown 引用块（以 > 开头）。

以 session 模块为例：

# session

> Manage browser sessions, cookies, cache, proxy settings, etc.

模块方法和事件¶

对于不是类的模块，其方法和事件必须列在 ## Methods 和 ## Events 章节下。

以 autoUpdater 为例：

# autoUpdater

## Events

### Event: 'error'

## Methods

### `autoUpdater.setFeedURL(options)`

类¶

API 类或作为模块一部分的类必须列在 ## Class: TheClassName 章节下。
一个页面可以有多个类。
构造函数必须使用 ### 级标题列出。
静态方法必须列在 ### Static Methods 章节下。
实例方法必须列在 ### Instance Methods 章节下。
所有有返回值的方法，其描述必须以 “Returns [TYPE] - [Return description]” 开头。
如果方法返回 Object，可以使用冒号加换行，然后用与函数参数相同风格的无序列表来指定其结构。
实例事件必须列在 ### Instance Events 章节下。
实例属性必须列在 ### Instance Properties 章节下。
实例属性的描述必须以 “A [Property Type] ...” 开头。

以 Session 和 Cookies 类为例：

# session

## Methods

### session.fromPartition(partition)

## Static Properties

### session.defaultSession

## Class: Session

### Instance Events

#### Event: 'will-download'

### Instance Methods

#### `ses.getCacheSize()`

### Instance Properties

#### `ses.cookies`

## Class: Cookies

### Instance Methods

#### `cookies.get(filter, callback)`

方法及其参数¶

方法章节必须采用以下形式：

### `objectName.methodName(required[, optional]))`

* `required` string - A parameter description.
* `optional` Integer (optional) - Another parameter description.

...

标题层级¶

根据方法是属于模块还是类，标题可以是 ### 级或 #### 级。

函数签名¶

对于模块，objectName 是模块的名称。对于类，它必须是该类实例的名称，并且不能与模块名称相同。

例如，session 模块下的 Session 类的方法必须使用 ses 作为 objectName。

可选参数使用方括号 [] 括起来表示，如果该可选参数跟在另一个参数后面，则还需要包含逗号：

required[, optional]

参数描述¶

关于每个参数的更详细信息在方法下方的无序列表中注明。参数类型可以是 JavaScript 原始类型（例如 string、Promise 或 Object）、类似于 Electron 的 Cookie 的自定义 API 结构，或通配符 any。

如果参数是 Array 类型，请使用 [] 缩写，并在数组内注明值的类型（例如 any[] 或 string[]）。

如果参数是 Promise 类型，请使用 promise 解析后的类型作为参数化类型（例如 Promise<void> 或 Promise<string>）。

如果参数可以是多种类型，请使用 | 分隔这些类型。

对于 Function 类型的参数，其描述应明确说明如何调用，并列出将传递给它的参数类型。

平台特定功能¶

如果某个参数或方法仅适用于特定平台，则这些平台应使用数据类型后的空格分隔斜体列表来表示。可用值为 macOS、Windows 或 Linux。

* `animate` boolean (optional) _macOS_ _Windows_ - Animate the thing.

事件¶

事件章节必须采用以下形式：

### Event: 'wake-up'

Returns:

* `time` string

...

标题可以是 ### 或 #### 级别，具体取决于事件属于模块还是类。

事件的参数遵循与方法相同的规则。

属性¶

属性章节必须采用以下形式：

### session.defaultSession

...

标题可以是 ### 或 #### 级别，具体取决于属性属于模块还是类。

API 历史记录¶

“API 历史记录”块是一个由 HTML 注释包裹的 YAML 代码块，应直接放置在类或方法的 Markdown 标题之后，如下所示：

#### `win.setTrafficLightPosition(position)` _macOS_

<!--
```YAML history
added:
  - pr-url: https://github.com/electron/electron/pull/22533
changes:
  - pr-url: https://github.com/electron/electron/pull/26789
    description: "Made `trafficLightPosition` option work for `customButtonOnHover` window."
deprecated:
  - pr-url: https://github.com/electron/electron/pull/37094
    breaking-changes-header: deprecated-browserwindowsettrafficlightpositionposition
```
-->

* `position` Point

Set a custom position for the traffic light buttons. Can only be used with `titleBarStyle` set to `hidden`.

它应遵循 API 历史记录 JSON Schema（api-history.schema.json），你可以在 docs 文件夹中找到该文件。 API 历史记录架构 RFC 包含示例用法以及对架构各方面的详细说明。

API 历史记录块的目的是描述某个 API 何时/何地/如何/为何被：

新增
变更（通常是破坏性变更）
已弃用

块中列出的每个 API 变更都应包含指向做出该变更的 PR 的链接，以及可选的简短变更描述。如适用，请包含来自破坏性变更文档的该变更的标题 id。

API 历史记录 lint 脚本（lint:api-history）会根据架构验证 Electron 文档中的 API 历史记录块，并执行一些其他检查。你可以查看其测试以获取更多细节。

还有一些 lint 脚本未涵盖的风格指南：

格式¶

请始终遵循以下格式：

API HEADER                  |  #### `win.flashFrame(flag)`
BLANK LINE                  | 
HTML COMMENT OPENING TAG    |  <!--
API HISTORY OPENING TAG     |  ```YAML history
API HISTORY                 |  added:
                            |    - pr-url: https://github.com/electron/electron/pull/22533
API HISTORY CLOSING TAG     |  ```
HTML COMMENT CLOSING TAG    |  -->
BLANK LINE                  |

YAML¶

使用两个空格进行缩进。
不要使用注释。

描述¶

始终使用双引号包裹描述（例如 "example"）。
某些特殊字符（例如 [、]）可能会破坏 YAML 解析。
以与应用开发者相关的方式描述变更，并采用首字母大写、带标点且过去时态的表达。
示例可参考 Clerk。
保持描述简洁。
理想情况下，描述应与破坏性变更文档中对应的标题一致。
尽可能优先使用关联 PR 的发布说明。
开发者始终可以查看破坏性变更文档或关联 PR 以获取更多细节。

放置位置¶

通常，应将 API 历史记录块直接放置在发生变更的类或方法的 Markdown 标题之后。但有些情况下这样做存在歧义：

Chromium 版本升级¶

有时，破坏性变更与任何现有 API 都无关。在这种情况下，可以不在任何地方添加 API 历史记录。

影响多个 API 的变更¶

有时，破坏性变更涉及多个 API。在这种情况下，请将 API 历史记录块放置在每个相关 API 的顶级 Markdown 标题之下。

# contextBridge

<!--
```YAML history
changes:
  - pr-url: https://github.com/electron/electron/pull/40330
    description: "`ipcRenderer` can no longer be sent over the `contextBridge`"
    breaking-changes-header: behavior-changed-ipcrenderer-can-no-longer-be-sent-over-the-contextbridge
```
-->

> Create a safe, bi-directional, synchronous bridge across isolated contexts

# ipcRenderer

<!--
```YAML history
changes:
  - pr-url: https://github.com/electron/electron/pull/40330
    description: "`ipcRenderer` can no longer be sent over the `contextBridge`"
    breaking-changes-header: behavior-changed-ipcrenderer-can-no-longer-be-sent-over-the-contextbridge
```
-->

Process: [Renderer](../glossary.md#renderer-process)

注意，以下位置没有添加 API 历史记录块：

contextBridge.exposeInMainWorld(apiKey, api)

因为该函数本身没有变更，只有其可能的使用方式发生了变化：

  contextBridge.exposeInMainWorld('app', {
-   ipcRenderer,
+   onEvent: (cb) => ipcRenderer.on('foo', (e, ...args) => cb(args))
  })

文档翻译¶

参见 electron/i18n

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 el/electron