Electron 文档风格指南

🌐 Electron Documentation Style Guide

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

🌐 These are the guidelines for writing Electron documentation.

标题

🌐 Headings

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

以 Quick Start 为例：

🌐 Using Quick Start as example:

# Quick Start

...

## Main process

...

## Renderer process

...

## Run your app

...

### Run as a distribution

...

### Manually downloaded Electron binary

...

对于 API 参考，此规则也有例外。

🌐 For API references, there are exceptions to this rule.

Markdown 规则

🌐 Markdown rules

该代码库使用 markdownlint 包来强制统一 Markdown 样式。有关具体规则，请参见根目录下的 .markdownlint.json 文件。

🌐 This repository uses the markdownlint package to enforce consistent Markdown styling. For the exact rules, see the .markdownlint.json file in the root folder.

linter 规则未涵盖一些样式指南：

🌐 There are a few style guidelines that aren't covered by the linter rules:

在代码块中使用 sh 替代 cmd（由于语法高亮）。
尽量将每行长度保持在 80 到 100 个字符，以提高可读性。
没有嵌套列出超过 2 层（由于 Markdown 渲染器）。
所有 js 和 javascript 代码块都使用 standard-markdown 进行 lint 检查。
对于无序列表，请使用星号而不是破折号。

选词

🌐 Picking words

在描述结果时，使用“will”而不是“would”。
更倾向于使用“in the ___ process”而不是“on”。

API 参考

🌐 API references

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

🌐 The following rules only apply to the documentation of APIs.

标题和描述

🌐 Title and description

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

🌐 Each module's API doc must use the actual object name returned by require('electron') as its title (such as BrowserWindow, autoUpdater, and session).

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

🌐 Directly under the page title, add a one-line description of the module as a markdown quote (beginning with >).

以 session 模块为例：

🌐 Using the session module as an example:

# session

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

模块方法和事件

🌐 Module methods and events

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

🌐 For modules that are not classes, their methods and events must be listed under the ## Methods and ## Events chapters.

以 autoUpdater 为例：

🌐 Using autoUpdater as an example:

# autoUpdater

## Events

### Event: 'error'

## Methods

### `autoUpdater.setFeedURL(options)`

类

🌐 Classes

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

以 Session 和 Cookies 类为例：

🌐 Using the Session and Cookies classes as an example:

# 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)`

方法及其参数

🌐 Methods and their arguments

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

🌐 The methods chapter must be in the following form:

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

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

...

标题级别

🌐 Heading level

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

🌐 The heading can be ### or ####-levels depending on whether the method belongs to a module or a class.

函数签名

🌐 Function signature

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

🌐 For modules, the objectName is the module's name. For classes, it must be the name of the instance of the class, and must not be the same as the module's name.

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

🌐 For example, the methods of the Session class under the session module must use ses as the objectName.

可选参数用方括号 [] 标记，可选参数前后如果有其他参数，需要加逗号分隔：

🌐 Optional arguments are notated by square brackets [] surrounding the optional argument as well as the comma required if this optional argument follows another argument:

required[, optional]

参数说明

🌐 Argument descriptions

每个参数的更详细信息在方法下方的无序列表中进行了说明。参数的类型由 JavaScript 原始类型（例如 string、Promise 或 Object）、像 Electron 的 Cookie 这样的自定义 API 结构，或通配符 `any`` 来表示。

🌐 More detailed information on each of the arguments is noted in an unordered list below the method. The type of argument is notated by either JavaScript primitives (e.g. string, Promise, or Object), a custom API structure like Electron's Cookie, or the wildcard any.

如果参数类型为 Array，使用 [] 简写，并指定数组中值的类型（例如，any[] 或 string[]）。

🌐 If the argument is of type Array, use [] shorthand with the type of value inside the array (for example,any[] or string[]).

如果参数的类型是 Promise，请将类型参数化为 promise 最终解析的类型（例如 Promise<void> 或 Promise<string>）。

🌐 If the argument is of type Promise, parametrize the type with what the promise resolves to (for example, Promise<void> or Promise<string>).

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

🌐 If an argument can be of multiple types, separate the types with |.

Function 类型参数的描述应清楚说明它如何被调用，并列出将传递给它的参数类型。

🌐 The description for Function type arguments should make it clear how it may be called and list the types of the parameters that will be passed to it.

特定于平台的功能

🌐 Platform-specific functionality

如果某个参数或方法是某些平台特有的，这些平台会在数据类型后用以空格分隔的斜体列表表示。值可以是 macOS、Windows 或 Linux。

🌐 If an argument or a method is unique to certain platforms, those platforms are denoted using a space-delimited italicized list following the datatype. Values can be macOS, Windows or Linux.

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

事件

🌐 Events

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

🌐 The events chapter must be in following form:

### Event: 'wake-up'

Returns:

* `time` string

...

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

🌐 The heading can be ### or ####-levels depending on whether the event belongs to a module or a class.

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

🌐 The arguments of an event follow the same rules as methods.

属性

🌐 Properties

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

🌐 The properties chapter must be in following form:

### session.defaultSession

...

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

🌐 The heading can be ### or ####-levels depending on whether the property belongs to a module or a class.

API 历史记录

🌐 API History

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

🌐 An "API History" block is a YAML code block encapsulated by an HTML comment that should be placed directly after the Markdown header for a class or method, like so:

#### `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](structures/point.md)

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

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

🌐 It should adhere to the API History JSON Schema (api-history.schema.json) which you can find in the docs folder. The API History Schema RFC includes example usage and detailed explanations for each aspect of the schema.

API History 块的目的是描述 API 何时/何地/如何/为何：

🌐 The purpose of the API History block is to describe when/where/how/why an API was:

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

块中列出的每个 API 更改都应包括指向该更改所在的 PR 的链接，以及可选的更改简短描述。如果适用，请包含该更改在破坏性更改文档中的标题 ID。

🌐 Each API change listed in the block should include a link to the PR where that change was made along with an optional short description of the change. If applicable, include the heading id for that change from the breaking changes documentation.

API 历史检查脚本（lint:api-history）根据模式验证 Electron 文档中的 API 历史块，并执行其他一些检查。你可以查看它的测试以获取更多详情。

🌐 The API History linting script (lint:api-history) validates API History blocks in the Electron documentation against the schema and performs some other checks. You can look at its tests for more details.

有一些样式指南未包含在 linting 脚本中：

🌐 There are a few style guidelines that aren't covered by the linting script:

格式

🌐 Format

始终遵循此格式：

🌐 Always adhere to this format:

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

使用两个空格进行缩进。
请勿使用注释。

说明

🌐 Descriptions

始终用双引号括起描述（例如“示例”）。
- 某些特殊字符（例如 [、]）可能会导致 YAML 解析失败。
以与应用开发者相关的方式描述更改，并使用大写字母、标点符号且采用过去时。
- 请参阅 Clerk 获取示例。
保持描述简洁。
- 理想情况下，描述应与《重大变更文档》中对应的标题相匹配。
- 尽可能使用相关 PR 中的发行说明。
- 开发者可以随时查看重大更改文档或相关的拉取请求以获取更多详情。

位置

🌐 Placement

一般来说，你应该将 API 历史块直接放在已更改类或方法的 Markdown 标题之后。然而，在某些情况下，这可能不太明确：

🌐 Generally, you should place the API History block directly after the Markdown header for a class or method that was changed. However, there are some instances where this is ambiguous:

Chromium 更新

🌐 Chromium bump

杂务：将 Chromium 升级到 122.0.6194.0（主版本）
- 行为更改：跨源 iframe 现在使用权限策略访问功能

有时候，重大变更与现有的任何 API 都无关。在这种情况下，不必在任何地方添加 API 历史记录。

🌐 Sometimes a breaking change doesn't relate to any of the existing APIs. In this case, it is ok not to add API History anywhere.

影响多个 API 的更改

🌐 Change affecting multiple APIs

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

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

🌐 Sometimes a breaking change involves multiple APIs. In this case, place the API History block under the top-level Markdown header for each of the involved APIs.

# 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 历史记录块未添加到：

🌐 Notice how an API History block wasn't added under:

contextBridge.exposeInMainWorld(apiKey, api)

由于该函数未更改，因此仅更改其使用方式：

🌐 since that function wasn't changed, only how it may be used:

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

文档翻译

🌐 Documentation translations

参见 electron/i18n

🌐 See electron/i18n

标题​

Markdown 规则​

选词​

API 参考​

标题和描述​

模块方法和事件​

类​

方法及其参数​

标题级别​

函数签名​

参数说明​

特定于平台的功能​

事件​

属性​

API 历史记录​

格式​

YAML​

说明​

位置​

Chromium 更新​

影响多个 API 的更改​

文档翻译​

标题