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 文件。
以下是一些代码检查器规则未涵盖的样式指南
- 在代码块中使用
sh而不是cmd(由于语法高亮器)。 - 如果可能，为了可读性，将行长度保持在 80 到 100 个字符之间。
- 列表嵌套不超过 2 层 (由于 Markdown 渲染器)。
- 所有
js和javascript代码块都使用 standard-markdown 进行检查。 - 对于无序列表，使用星号 (*) 而不是破折号 (-)。
用词选择
- 描述结果时，优先使用 "will" 而非 "would"。
- 优先使用 "in the ___ process" 而非 "on the ___ process"。
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章节下。 - 所有有返回值的方法的描述必须以 "Returns
[类型]- [返回值的描述]" 开头- 如果方法返回一个
Object，其结构可以用冒号后跟一个换行符，然后是一个无序列表来指定，列表中的属性样式与函数参数相同。
- 如果方法返回一个
- 实例事件 (Instance Events) 必须列在
### Instance Events章节下。 - 实例属性 (Instance Properties) 必须列在
### 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)、Electron 自定义 API 结构 (例如 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](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 History Schema RFC 包含示例用法以及模式各方面的详细解释。
API 历史块的目的是描述 API 是何时/何地/如何/为何被
- 添加
- 更改 (通常是破坏性更改)
- 弃用
块中列出的每个 API 更改都应包含指向进行该更改的 PR 的链接以及一个可选的简短更改描述。如果适用，请包含来自破坏性更改文档的该更改的标题 ID。
API 历史代码检查脚本 (lint:api-history) 根据 schema 验证 Electron 文档中的 API 历史块并执行一些其他检查。您可以查看其测试以了解更多详细信息。
以下是一些代码检查脚本未涵盖的样式指南
格式
始终遵循此格式
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") 包围描述。
- 以与应用开发者相关的方式描述更改，并使用首字母大写、标点符号和过去时。
- 参考 Clerk 查看示例。
- 保持描述简洁。
- 理想情况下，描述应与其在破坏性更改文档中的对应标题一致。
- 尽可能优先使用相关 PR 中的发行说明。
- 开发者可以随时查看破坏性更改文档或链接的 pull request 获取更多详细信息。
位置
通常，您应该将 API History 块直接放置在已更改的类或方法的 Markdown 标题之后。但是，在某些情况下这会比较模糊
Chromium 版本升级
有时，破坏性更改与任何现有 API 都不相关。在这种情况下，不添加 API History 是可以的。
影响多个 API 的更改
有时，破坏性更改涉及多个 API。在这种情况下，将 API History 块放置在每个相关 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 History 块没有添加到
contextBridge.exposeInMainWorld(apiKey, api)
因为该函数本身没有改变，只是其使用方式发生了变化
contextBridge.exposeInMainWorld('app', {
- ipcRenderer,
+ onEvent: (cb) => ipcRenderer.on('foo', (e, ...args) => cb(args))
})
文档翻译
请参阅 electron/i18n