Electron 文档风格指南
¥Electron Documentation Style Guide
这些是编写 Electron 文档的指南。
¥These are the guidelines for writing Electron documentation.
标题
¥Headings
-
每页顶部必须有一个
#级标题。¥Each page must have a single
#-level title at the top. -
同一页中的章节必须有
##级标题。¥Chapters in the same page must have
##-level headings. -
子章节需要根据嵌套深度增加标题中
#的数量。¥Sub-chapters need to increase the number of
#in the heading according to their nesting depth. -
页面标题必须位于 APA 标题案例 之后。
¥The page's title must follow APA title case.
-
所有章节必须遵循 APA 判决案例。
¥All chapters must follow APA sentence case.
以 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（由于语法高亮）。¥Use
shinstead ofcmdin code blocks (due to the syntax highlighter). -
出于可读性目的，如果可能，请将行长度保持在 80 到 100 个字符之间。
¥Keep line lengths between 80 and 100 characters if possible for readability purposes.
-
没有嵌套列出超过 2 层（由于 Markdown 渲染器）。
¥No nesting lists more than 2 levels (due to the markdown renderer).
-
所有
js和javascript代码块都带有 standard-markdown。¥All
jsandjavascriptcode blocks are linted with standard-markdown. -
对于无序列表，请使用星号而不是破折号。
¥For unordered lists, use asterisks instead of dashes.
选词
¥Picking words
-
描述结果时使用 "will" 而不是 "would"。
¥Use "will" over "would" when describing outcomes.
-
比起 "on" 更喜欢 "正在进行中"。
¥Prefer "in the ___ process" over "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(url[, requestHeaders])`
类
¥Classes
-
API 类或属于模块一部分的类必须列在
## Class: TheClassName章下。¥API classes or classes that are part of modules must be listed under a
## Class: TheClassNamechapter. -
一个页面可以有多个类。
¥One page can have multiple classes.
-
构造函数必须以
###级标题列出。¥Constructors must be listed with
###-level headings. -
静态方法 必须列在
### Static Methods章节下。¥Static Methods must be listed under a
### Static Methodschapter. -
实例方法 必须列在
### Instance Methods章节下。¥Instance Methods must be listed under an
### Instance Methodschapter. -
所有具有返回值的方法都必须以“Returns
[TYPE]- 【返回说明】”¥All methods that have a return value must start their description with "Returns
[TYPE]- [Return description]"-
如果该方法返回
Object，则可以使用冒号后跟换行符，然后是与函数参数相同样式的无序列属性列表来指定其结构。¥If the method returns an
Object, its structure can be specified using a colon followed by a newline then an unordered list of properties in the same style as function parameters.
-
-
实例事件必须列在
### Instance Events章下。¥Instance Events must be listed under an
### Instance Eventschapter. -
实例属性必须列在
### Instance Properties章下。¥Instance Properties must be listed under an
### Instance Propertieschapter.-
实例属性必须以 "A [Property Type] ..." 开头
¥Instance Properties must start with "A [Property Type] ..."
-
以 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）、自定义 API 结构（如 Electron 的 Cookie）或通配符 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 Schema（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:
-
已添加
¥Added
-
已更改（通常是重大更改）
¥Changed (usually breaking changes)
-
已弃用
¥Deprecated
块中列出的每个 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 历史记录 linting 脚本（lint:api-history）根据架构验证 Electron 文档中的 API History 块并执行其他一些检查。你可以查看其 tests 以了解更多详细信息。
¥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
-
使用两个空格进行缩进。
¥Use two spaces for indentation.
-
请勿使用注释。
¥Do not use comments.
说明
¥Descriptions
-
始终用双引号括住描述（即 "example"）。
¥Always wrap descriptions with double quotation marks (i.e. "example").
-
以与应用开发者相关的方式描述更改，并使其大写、标点和使用过去时。
¥Describe the change in a way relevant to app developers and make it capitalized, punctuated, and past tense.
-
保持描述简洁。
¥Keep descriptions concise.
-
理想情况下，描述将与重大更改文档中其对应的标题相匹配。
¥Ideally, a description will match its corresponding header in the breaking changes document.
-
尽可能使用相关 PR 中的发行说明。
¥Favor using the release notes from the associated PR whenever possible.
-
开发者始终可以查看重大更改文档或链接的拉取请求以了解更多详细信息。
¥Developers can always view the breaking changes document or linked pull request for more details.
-
位置
¥Placement
通常，你应该将 API History 块直接放在已更改的类或方法的 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
有时，重大更改与任何现有 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
有时，重大更改涉及多个 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
¥See electron/i18n