跳到主要內容

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 檔案。

有一些風格指南未包含在 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.

模組方法和事件​

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

以 autoUpdater 作為範例

# autoUpdater

## Events

### Event: 'error'

## Methods

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

類別​

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

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

  • 縮排使用兩個空格。
  • 請勿使用註解。

描述​

  • 始終用雙引號括住描述（即「example」）。
  • 以與應用程式開發人員相關的方式描述變更，並使其大寫、標點符號和過去式。
    • 請參閱 Clerk 以獲取範例。
  • 保持描述簡潔。
    • 理想情況下，描述將與其在重大變更文件中的對應標題相符。
    • 盡可能優先使用來自相關 PR 的發行說明。
    • 開發人員隨時可以查看重大變更文件或連結的 pull request 以獲取更多詳細資訊。

放置位置​

通常，您應將 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