跳至主要內容

Electron 的 API 文件作為結構化資料

·3 分鐘閱讀
zeke
zeke

今天，我們要宣布 Electron 文件的一些改進。現在，每個新版本都包含一個 JSON 檔案，其中詳細描述了 Electron 的所有公開 API。我們建立這個檔案是為了讓開發人員能夠以有趣的新方式使用 Electron 的 API 文件。

架構概述​

每個 API 都是一個物件，具有名稱、描述、類型等屬性。諸如 BrowserWindow 和 Menu 之類的類別還具有其他屬性，描述它們的實例方法、實例屬性、實例事件等等。

以下是架構中描述 BrowserWindow 類別的摘錄

{
  name: 'BrowserWindow',
  description: 'Create and control browser windows.',
  process: {
    main: true,
    renderer: false
  },
  type: 'Class',
  instanceName: 'win',
  slug: 'browser-window',
  websiteUrl: 'https://electron.dev.org.tw/docs/api/browser-window',
  repoUrl: 'https://github.com/electron/electron/blob/v1.4.0/docs/api/browser-window.md',
  staticMethods: [...],
  instanceMethods: [...],
  instanceProperties: [...],
  instanceEvents: [...]
}

以下是一個方法描述的範例，在本例中是 apis.BrowserWindow.instanceMethods.setMaximumSize 實例方法

{
  name: 'setMaximumSize',
  signature: '(width, height)',
  description: 'Sets the maximum size of window to width and height.',
  parameters: [{
    name: 'width',
    type: 'Integer'
  }, {
    name: 'height',
    type: 'Integer'
  }]
}

使用新資料​

為了讓開發人員能夠輕鬆地在其專案中使用這種結構化資料，我們建立了 electron-docs-api，這是一個小型 npm 套件，每次發布新的 Electron 版本時都會自動發布。

npm install electron-api-docs --save

為了即時獲得滿足感，請在您的 Node.js REPL 中嘗試使用該模組

npm i -g trymodule && trymodule electron-api-docs=apis

資料的收集方式​

Electron 的 API 文件遵循 Electron 編碼風格和 Electron 風格指南，因此其內容可以透過程式碼進行剖析。

electron-docs-linter 是 electron/electron 存放庫的新開發依賴項。它是一個命令列工具，會檢查所有 markdown 檔案並強制執行風格指南的規則。如果發現錯誤，它們會被列出並且發布過程會停止。如果 API 文件有效，則會建立 electron-json.api 檔案，並作為 Electron 版本的一部分 上傳到 GitHub。

標準 JavaScript 和標準 Markdown​

今年稍早，Electron 的程式碼庫已更新為對所有 JavaScript 使用 standard 檢查工具。Standard 的 README 總結了這個選擇背後的原因

採用標準風格意味著將程式碼清晰度和社群慣例的重要性置於個人風格之上。這可能不適用於 100% 的專案和開發文化，但開放原始碼對於新手來說可能是一個充滿敵意的地方。設定明確的、自動化的貢獻者期望可以使專案更健康。

我們最近還建立了 standard-markdown 來驗證我們文件中所有 JavaScript 程式碼片段是否有效且與程式碼庫本身的風格一致。

這些工具一起幫助我們使用持續整合 (CI) 來自動尋找提取請求中的錯誤。這減少了人類進行程式碼審查的負擔，並使我們對文件準確性更有信心。

社群努力​

Electron 的文件不斷改進，我們要感謝我們出色的開放原始碼社群。在撰寫本文時，已有近 300 人為文件做出了貢獻。

我們很高興看到人們如何使用這種新的結構化資料。可能的用途包括