Electron 文档风格指南

这些是编写 Electron 文档的指南。

标题

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

以 快速入门 为例

# 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 处理。
对于无序列表，使用星号而不是破折号。

选择单词

在描述结果时，使用“将”而不是“会”。
优先使用“在 ___ 过程中”而不是“在”。

API 参考

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

标题和描述

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

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

以 session 模块为例

# session

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

模块方法和事件

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

以 autoUpdater 为例

# autoUpdater

## Events

### Event: 'error'

## Methods

### `autoUpdater.setFeedURL(url[, requestHeaders])`

类

API 类或模块的一部分的类必须列在 ## 类：TheClassName 章节下。
一个页面可以有多个类。
构造函数必须使用 ### 级标题列出。
静态方法必须列在 ### 静态方法 章节下。
实例方法必须列在 ### 实例方法 章节下。
所有具有返回值的方法必须以“返回 [TYPE] - [返回值描述]”开头其描述。
- 如果方法返回一个 Object，则可以使用冒号后跟换行符，然后是与函数参数相同样式的无序属性列表来指定其结构。
实例事件必须列在 ### 实例事件 章节下。
实例属性必须列在 ### 实例属性 章节下。
- 实例属性必须以“一个 [属性类型] ...”开头。

以 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）、自定义 API 结构（如 Electron 的 Cookie）或通配符 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](latest/api/structures/point.md)

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 历史 Schema RFC 包含示例用法和对 schema 每个方面的详细解释。

API 历史块的目的是描述 API 何时/何地/如何/为何

添加
更改（通常是重大更改）
弃用

块中列出的每个 API 更改都应包含指向进行该更改的 PR 的链接，以及对更改的可选简短描述。如果适用，请包含来自重大更改文档的该更改的标题 ID。

API 历史 lint 脚本（lint:api-history）根据 schema 验证 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 的发布说明。
- 开发人员始终可以查看重大更改文档或链接的拉取请求以获取更多详细信息。

放置

通常，您应该将 API 历史块放在已更改的类或方法的 Markdown 标题之后。但是，在某些情况下，这很模棱两可

Chromium 升级

chore: 将 chromium 升级到 122.0.6194.0（main）
- 行为更改：跨域 iframe 现在使用权限策略来访问功能

有时，重大更改与任何现有 API 都无关。在这种情况下，可以不添加 API 历史记录。

影响多个 API 的变更

重构：确保 IpcRenderer 不可桥接
- 行为变更：ipcRenderer 无法再通过 contextBridge 发送

有时，一个重大变更会涉及多个 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](latest/glossary.md#renderer-process)

注意，在

contextBridge.exposeInMainWorld(apiKey, api)

下没有添加 API 历史记录块，因为该函数没有更改，只有它的使用方法可能有所不同。

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

文档翻译

参见 electron/i18n

标题​

Markdown 规则​

选择单词​

API 参考​

标题和描述​

模块方法和事件​

类​

方法及其参数​

标题级别​

函数签名​

参数描述​

特定于平台的功能​

事件​

属性​

API 历史​

格式​

YAML​

描述​

放置​

Chromium 升级​

影响多个 API 的变更​

文档翻译​

标题