跳到主要內容

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 linter。Standard 的 README 總結了此選擇背後的原因

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

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

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

社群共同努力​

Electron 的文件不斷改進，我們必須感謝我們出色的開源社群。截至撰寫本文時，已有近 300 人為文件做出了貢獻。

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