跳至主要內容

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 進行 linting。
  • 對於無序列表，請使用星號而不是破折號。

選詞​

  • 描述結果時，請使用「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.

模組方法和事件​

對於非類別的模組，其方法和事件必須列在 ## 方法 和 ## 事件 章節下。

以 autoUpdater 為例

# autoUpdater

## Events

### Event: 'error'

## Methods

### `autoUpdater.setFeedURL(url[, requestHeaders])`

類別​

  • API 類別或屬於模組一部分的類別必須列在 ## 類別：TheClassName 章節下。
  • 一個頁面可以有多個類別。
  • 建構函式必須使用 ### 層級標題列出。
  • 靜態方法 必須列在 ### 靜態方法 章節下。
  • 實例方法 必須列在 ### 實例方法 章節下。
  • 所有具有回傳值的方法都必須以「回傳 [TYPE] - [回傳描述]」開始其描述。
    • 如果方法回傳 Object，可以使用冒號後接換行符，然後以與函式參數相同的樣式列出屬性的無序列表來指定其結構。
  • 實例事件必須列在 ### 實例事件 章節下。
  • 實例屬性必須列在 ### 實例屬性 章節下。
    • 實例屬性必須以「一個 [屬性類型] ...」開頭。

以 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 歷史」區塊是一個 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 Schema (api-history.schema.json)，您可以在 docs 資料夾中找到。 API 歷史 Schema RFC 包含範例用法和架構每個方面的詳細說明。

API 歷史區塊的目的是描述 API 何時/何地/如何/為何

  • 新增
  • 變更（通常是重大變更）
  • 已棄用

區塊中列出的每個 API 變更都應包含一個指向進行該變更的 PR 的連結，以及該變更的可選簡短描述。如果適用，請包含 重大變更文件中該變更的 標題 ID。

API 歷史 linting 腳本 (lint:api-history) 會根據架構驗證 Electron 文件中的 API 歷史區塊，並執行其他一些檢查。您可以查看其 測試 以了解更多詳細資訊。

有一些樣式指南未包含在 linting 腳本中

格式​

始終遵循此格式

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