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。 - 对于无序列表，请使用星号而不是破折号。
选词
- 在描述结果时，使用 “will” 而不是 “would”。
- 优先选择 “在 ___ 进程中” 而不是 “在”。
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(url[, requestHeaders])`
类
- API 类或模块的一部分的类必须列在
## Class: TheClassName章节下。 - 一个页面可以有多个类。
- 构造函数必须使用
###级标题列出。 - 静态方法 必须列在
### Static Methods章节下。 - 实例方法 必须列在
### Instance Methods章节下。 - 所有具有返回值的方法都必须以“返回
[TYPE]- [返回描述]”开头其描述。- 如果该方法返回一个
Object，则可以使用冒号后跟一个新行，然后在与函数参数相同的样式中使用属性的无序列表来指定其结构。
- 如果该方法返回一个
- 实例事件必须列在
### Instance Events章节下。 - 实例属性必须列在
### Instance Properties章节下。- 实例属性必须以 “一个 [属性类型] …” 开头。
使用 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 历史”块是一个 YAML 代码块，用 HTML 注释封装，应直接放在类或方法的 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](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 包含了示例用法和对模式每个方面的详细说明。
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
- 使用两个空格进行缩进。
- 不要使用注释。
描述
- 始终使用双引号包裹描述（例如，“示例”）。
- 以与应用程序开发人员相关的方式描述更改，并使用大写、标点符号和过去时。
- 参考 Clerk 查看示例。
- 保持描述简洁。
- 理想情况下，描述应与其在重大更改文档中的相应标题匹配。
- 尽可能优先使用相关 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