跳转到主内容

Electron 文档风格指南

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

标题​

  • 每个页面顶部必须有一个 # 级标题。
  • 同一页面中的各章节必须有 ## 级标题。
  • 各小节需要根据其嵌套层级在头部增加 # 的数量。
  • 页面标题必须按照 APA 标题大小写。
  • 所有章节都必须遵循 APA语句大小写。

举一个Quick Start的例子:

# 快速入门

...

## 主进程

## 渲染进程

...

## 运行应用程序

...

### 作为分发版本运行

...

### 手动下载二进制格式的 Electron

...

对于 API 参考, 可以例外于这些规则.

Markdown 规则​

这个仓库使用 markdownline 软件包来实行前后一致的 Markdown 风格。 有关确切规则，请参阅根文件夹中的 .markdownlint.json 文件。

有几个样式准则不在 linter 规则范围之内：

  • 在代码块中使用bash而不是cmd（由于语法高亮问题）.
  • 为了可读性，如果可能，保持一行长度在80到100个字符之间。
  • 列表嵌套不超出2级 (由于 Markdown 渲染问题).
  • 所有的 js 和javascript代码块均被标记为 standard-markdown.
  • 对于无序列表，请使用星号而不是破折号.

用词选择​

  • 在描述结果时，使用 “will” 而不是 “would”。
  • 首选 "in the ___ process" 而不是 "on".

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 [TYPE] - [Return description]”开始
    • 如果该方法返回一个 Object，其结构可以使用冒号后跟换行符的方式，然后使用与函数参数相同样式的无序属性列表。
  • 实例事件必须在 ### Instance Events 章节中列出.
  • 实例属性必须在 ### Instance Properties 章节中列出。
    • 实例属性必须以 "A [Property Type] ..." 开头。

这里用 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]

参数描述​

关于每个参数的更详细信息将在方法下面的无序列表中列出。 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[])。

如果参数类型为 Promise, 则将promise resolve时的类型作为参数(例如 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 History​

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`.

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. The purpose of the API History block is to describe when/where/how/why an API was:

  • 已添加
  • 已更改 (通常是重大更改)
  • 已废弃 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. 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. There are a few style guidelines that aren't covered by the linting script:

格式​

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​

  • 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.
    • Refer to Clerk for examples.
  • Keep descriptions concise.
    • Ideally, a description will match its corresponding header in the breaking changes document.
    • 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​

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 bump​

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.

Change affecting multiple APIs​

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)

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))
  })

文档翻译​

请参见 electron/i18n