webContents

渲染與控制網頁。

程序：主程序

webContents 是 EventEmitter。它負責渲染和控制網頁，並且是 BrowserWindow 物件的屬性。存取 webContents 物件的範例

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ width: 800, height: 1500 })
win.loadURL('https://github.com')

const contents = win.webContents
console.log(contents)

導航事件

多個事件可用於監控 webContents 內發生的導航。

文件導航

當 webContents 導航到另一個頁面時（相對於頁內導航），將觸發以下事件。

• did-start-navigation
• will-frame-navigate
• will-navigate (僅在主框架導航時觸發)
• will-redirect (僅在導航期間發生重新導向時觸發)
• did-redirect-navigation (僅在導航期間發生重新導向時觸發)
• did-frame-navigate
• did-navigate (僅在主框架導航時觸發)

如果在任何可取消的事件上呼叫 event.preventDefault()，後續事件將不會觸發。

頁內導航

頁內導航不會導致頁面重新載入，而是導航到目前頁面內的某個位置。這些事件不可取消。對於頁內導航，將依序觸發以下事件

• did-start-navigation
• did-navigate-in-page

框架導航

will-navigate 和 did-navigate 事件僅在 主框架 導航時觸發。如果您也想觀察 <iframe> 中的導航，請使用 will-frame-navigate 和 did-frame-navigate 事件。

方法

這些方法可以從 webContents 模組存取

const { webContents } = require('electron')
console.log(webContents)

webContents.getAllWebContents()

返回 WebContents[] - 所有 WebContents 實例的陣列。這將包含所有視窗、webview、已開啟的開發人員工具和開發人員工具擴充功能背景頁面的 web contents。

webContents.getFocusedWebContents()

返回 WebContents | null - 此應用程式中聚焦的 web contents，否則返回 null。

webContents.fromId(id)

• id Integer

返回 WebContents | undefined - 具有給定 ID 的 WebContents 實例，如果沒有與給定 ID 關聯的 WebContents，則返回 undefined。

webContents.fromFrame(frame)

• frame WebFrameMain

返回 WebContents | undefined - 具有給定 WebFrameMain 的 WebContents 實例，如果沒有與給定 WebFrameMain 關聯的 WebContents，則返回 undefined。

webContents.fromDevToolsTargetId(targetId)

• targetId string - 與 WebContents 實例關聯的 Chrome DevTools Protocol TargetID。

返回 WebContents | undefined - 具有給定 TargetID 的 WebContents 實例，如果沒有與給定 TargetID 關聯的 WebContents，則返回 undefined。

當與 Chrome DevTools Protocol 通訊時，根據其分配的 TargetID 查找 WebContents 實例可能很有用。

async function lookupTargetId (browserWindow) {
  const wc = browserWindow.webContents
  await wc.debugger.attach('1.3')
  const { targetInfo } = await wc.debugger.sendCommand('Target.getTargetInfo')
  const { targetId } = targetInfo
  const targetWebContents = await wc.fromDevToolsTargetId(targetId)
}

類別：WebContents

渲染與控制 BrowserWindow 實例的內容。

程序：主程序
此類別未從 'electron' 模組匯出。它僅作為 Electron API 中其他方法的傳回值提供。

實例事件

事件：'did-finish-load'

當導航完成時發出，即標籤頁的旋轉圖示已停止旋轉，並且已分派 onload 事件。

事件：'did-fail-load'

返回

• event Event
• errorCode Integer
• errorDescription string
• validatedURL string
• isMainFrame boolean
• frameProcessId Integer
• frameRoutingId Integer

此事件類似於 did-finish-load，但在載入失敗時發出。錯誤代碼的完整列表及其含義可在此處找到。

事件：'did-fail-provisional-load'

返回

• event Event
• errorCode Integer
• errorDescription string
• validatedURL string
• isMainFrame boolean
• frameProcessId Integer
• frameRoutingId Integer

此事件類似於 did-fail-load，但在載入被取消時發出（例如，調用了 window.stop()）。

事件：'did-frame-finish-load'

返回

• event Event
• isMainFrame boolean
• frameProcessId Integer
• frameRoutingId Integer

當框架完成導航時發出。

事件：'did-start-loading'

對應於標籤頁的旋轉圖示開始旋轉的時間點。

事件：'did-stop-loading'

對應於標籤頁的旋轉圖示停止旋轉的時間點。

事件：'dom-ready'

當頂層框架中的文件載入時發出。

事件：'page-title-updated'

返回

• event Event
• title string
• explicitSet boolean

當在導航期間設定頁面標題時觸發。當標題是從檔案 URL 合成時，explicitSet 為 false。

事件：'page-favicon-updated'

返回

• event Event
• favicons string[] - URL 陣列。

當頁面收到 favicon URL 時發出。

事件：'content-bounds-updated'

返回

• event Event
• bounds Rectangle - 請求的新內容邊界

當頁面調用 window.moveTo、window.resizeTo 或相關 API 時發出。

預設情況下，這將移動視窗。要防止這種行為，請調用 event.preventDefault()。

事件：'did-create-window'

返回

• window BrowserWindow
• details Object
  • url string - 建立視窗的 URL。
  • frameName string - 在 window.open() 調用中給予建立視窗的名稱。
  • options BrowserWindowConstructorOptions - 用於建立 BrowserWindow 的選項。它們以遞增的優先順序合併：從 window.open() 的 features 字串中解析的選項、從父項繼承的與安全性相關的 webPreferences，以及 webContents.setWindowOpenHandler 給予的選項。未識別的選項不會被篩選掉。
  • referrer Referrer - 將傳遞到新視窗的引用網址。可能會或可能不會導致發送 Referer 標頭，具體取決於引用網址政策。
  • postBody PostBody (可選) - 將與適當的標頭一起發送到新視窗的 post data。如果沒有要發送的 post data，則值將為 null。僅在視窗是由設定 target=_blank 的表單建立時定義。
  • disposition string - 可以是 default、foreground-tab、background-tab、new-window 或 other。

在渲染器中透過 window.open 成功建立視窗之後發出。如果視窗的建立從 webContents.setWindowOpenHandler 取消，則不會發出。

請參閱 window.open() 以取得更多詳細資訊，以及如何將其與 webContents.setWindowOpenHandler 結合使用。

事件：'will-navigate'

返回

• details Event<>
  • url string - 框架將導航到的 URL。
  • isSameDocument boolean - 此事件不會針對使用 window.history api 和參考片段導航的相同文件導航觸發。此屬性對於此事件始終設定為 false。
  • isMainFrame boolean - 如果導航發生在主框架中，則為 True。
  • frame WebFrameMain | null - 要導航的框架。如果在框架導航或被銷毀後存取，可能為 null。
  • initiator WebFrameMain | null (可選) - 啟動導航的框架，可以是父框架（例如，透過具有框架名稱的 window.open），如果導航不是由框架啟動，則為 null。如果啟動框架在事件發出之前被刪除，也可能為 null。
• url string Deprecated
• isInPlace boolean Deprecated
• isMainFrame boolean Deprecated
• frameProcessId Integer Deprecated
• frameRoutingId Integer Deprecated

當使用者或頁面想要在主框架上開始導航時發出。當 window.location 物件被更改或使用者點擊頁面中的連結時，可能會發生這種情況。

當使用 webContents.loadURL 和 webContents.back 等 API 以程式方式啟動導航時，此事件不會發出。

它也不會針對頁內導航發出，例如點擊錨點連結或更新 window.location.hash。請為此目的使用 did-navigate-in-page 事件。

調用 event.preventDefault() 將阻止導航。

事件：'will-frame-navigate'

返回

• details Event<>
  • url string - 框架將導航到的 URL。
  • isSameDocument boolean - 此事件不會針對使用 window.history api 和參考片段導航的相同文件導航觸發。此屬性對於此事件始終設定為 false。
  • isMainFrame boolean - 如果導航發生在主框架中，則為 True。
  • frame WebFrameMain | null - 要導航的框架。如果在框架導航或被銷毀後存取，可能為 null。
  • initiator WebFrameMain | null (可選) - 啟動導航的框架，可以是父框架（例如，透過具有框架名稱的 window.open），如果導航不是由框架啟動，則為 null。如果啟動框架在事件發出之前被刪除，也可能為 null。

當使用者或頁面想要在任何框架中開始導航時發出。當 window.location 物件被更改或使用者點擊頁面中的連結時，可能會發生這種情況。

與 will-navigate 不同，當主框架或其任何子框架嘗試導航時，會觸發 will-frame-navigate。當導航事件來自主框架時，isMainFrame 將為 true。

當使用 webContents.loadURL 和 webContents.back 等 API 以程式方式啟動導航時，此事件不會發出。

它也不會針對頁內導航發出，例如點擊錨點連結或更新 window.location.hash。請為此目的使用 did-navigate-in-page 事件。

調用 event.preventDefault() 將阻止導航。

事件：'did-start-navigation'

返回

• details Event<>
  • url string - 框架將導航到的 URL。
  • isSameDocument boolean - 導航是否在不更改文件的情況下發生。相同文件導航的範例包括參考片段導航、pushState/replaceState 和相同頁面歷史記錄導航。
  • isMainFrame boolean - 如果導航發生在主框架中，則為 True。
  • frame WebFrameMain | null - 要導航的框架。如果在框架導航或被銷毀後存取，可能為 null。
  • initiator WebFrameMain | null (可選) - 啟動導航的框架，可以是父框架（例如，透過具有框架名稱的 window.open），如果導航不是由框架啟動，則為 null。如果啟動框架在事件發出之前被刪除，也可能為 null。
• url string Deprecated
• isInPlace boolean Deprecated
• isMainFrame boolean Deprecated
• frameProcessId Integer Deprecated
• frameRoutingId Integer Deprecated

當任何框架（包括主框架）開始導航時發出。

事件：'will-redirect'

返回

• details Event<>
  • url string - 框架將導航到的 URL。
  • isSameDocument boolean - 導航是否在不更改文件的情況下發生。相同文件導航的範例包括參考片段導航、pushState/replaceState 和相同頁面歷史記錄導航。
  • isMainFrame boolean - 如果導航發生在主框架中，則為 True。
  • frame WebFrameMain | null - 要導航的框架。如果在框架導航或被銷毀後存取，可能為 null。
  • initiator WebFrameMain | null (可選) - 啟動導航的框架，可以是父框架（例如，透過具有框架名稱的 window.open），如果導航不是由框架啟動，則為 null。如果啟動框架在事件發出之前被刪除，也可能為 null。
• url string Deprecated
• isInPlace boolean Deprecated
• isMainFrame boolean Deprecated
• frameProcessId Integer Deprecated
• frameRoutingId Integer Deprecated

當導航期間發生伺服器端重新導向時發出。例如 302 重新導向。

此事件將在 did-start-navigation 之後發出，並且始終在同一導航的 did-redirect-navigation 事件之前發出。

調用 event.preventDefault() 將阻止導航（而不僅僅是重新導向）。

事件：'did-redirect-navigation'

返回

• details Event<>
  • url string - 框架將導航到的 URL。
  • isSameDocument boolean - 導航是否在不更改文件的情況下發生。相同文件導航的範例包括參考片段導航、pushState/replaceState 和相同頁面歷史記錄導航。
  • isMainFrame boolean - 如果導航發生在主框架中，則為 True。
  • frame WebFrameMain | null - 要導航的框架。如果在框架導航或被銷毀後存取，可能為 null。
  • initiator WebFrameMain | null (可選) - 啟動導航的框架，可以是父框架（例如，透過具有框架名稱的 window.open），如果導航不是由框架啟動，則為 null。如果啟動框架在事件發出之前被刪除，也可能為 null。
• url string Deprecated
• isInPlace boolean Deprecated
• isMainFrame boolean Deprecated
• frameProcessId Integer Deprecated
• frameRoutingId Integer Deprecated

當導航期間發生伺服器端重新導向後發出。例如 302 重新導向。

此事件無法阻止，如果您想阻止重新導向，您應該查看上面的 will-redirect 事件。

事件：'did-navigate'

返回

• event Event
• url string
• httpResponseCode Integer - 非 HTTP 導航為 -1
• httpStatusText string - 非 HTTP 導航為空

當主框架導航完成時發出。

此事件不會針對頁內導航發出，例如點擊錨點連結或更新 window.location.hash。請為此目的使用 did-navigate-in-page 事件。

事件：'did-frame-navigate'

返回

• event Event
• url string
• httpResponseCode Integer - 非 HTTP 導航為 -1
• httpStatusText string - 非 HTTP 導航為空，
• isMainFrame boolean
• frameProcessId Integer
• frameRoutingId Integer

當任何框架導航完成時發出。

此事件不會針對頁內導航發出，例如點擊錨點連結或更新 window.location.hash。請為此目的使用 did-navigate-in-page 事件。

事件：'did-navigate-in-page'

返回

• event Event
• url string
• isMainFrame boolean
• frameProcessId Integer
• frameRoutingId Integer

當任何框架中發生頁內導航時發出。

當發生頁內導航時，頁面 URL 會更改，但不會導致頁面外的導航。發生這種情況的範例是當點擊錨點連結或觸發 DOM hashchange 事件時。

事件：'will-prevent-unload'

返回

• event Event

當 beforeunload 事件處理程序嘗試取消頁面卸載時發出。

調用 event.preventDefault() 將忽略 beforeunload 事件處理程序，並允許卸載頁面。

const { BrowserWindow, dialog } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
win.webContents.on('will-prevent-unload', (event) => {
  const choice = dialog.showMessageBoxSync(win, {
    type: 'question',
    buttons: ['Leave', 'Stay'],
    title: 'Do you want to leave this site?',
    message: 'Changes you made may not be saved.',
    defaultId: 0,
    cancelId: 1
  })
  const leave = (choice === 0)
  if (leave) {
    event.preventDefault()
  }
})

注意： 這將針對 BrowserViews 發出，但*不會*被尊重 - 這是因為我們選擇不將 BrowserView 生命周期與其擁有的 BrowserWindow 綁定，如果根據 規範 存在的話。

事件：'render-process-gone'

返回

• event Event
• details RenderProcessGoneDetails

當渲染器程序意外消失時發出。這通常是因為它崩潰或被終止。

事件：'unresponsive'

當網頁變得無回應時發出。

事件：'responsive'

當無回應的網頁再次變得回應時發出。

事件：'plugin-crashed'

返回

• event Event
• name string
• version string

當插件程序崩潰時發出。

事件：'destroyed'

當 webContents 被銷毀時發出。

事件：'input-event'

返回

• event Event
• inputEvent InputEvent

當輸入事件發送到 WebContents 時發出。有關詳細資訊，請參閱 InputEvent。

事件：'before-input-event'

返回

• event Event
• input Object - 輸入屬性。
  • type string - keyUp 或 keyDown。
  • key string - 相當於 KeyboardEvent.key。
  • code string - 相當於 KeyboardEvent.code。
  • isAutoRepeat boolean - 相當於 KeyboardEvent.repeat。
  • isComposing boolean - 相當於 KeyboardEvent.isComposing。
  • shift boolean - 相當於 KeyboardEvent.shiftKey。
  • control boolean - 相當於 KeyboardEvent.controlKey。
  • alt boolean - 相當於 KeyboardEvent.altKey。
  • meta boolean - 相當於 KeyboardEvent.metaKey。
  • location number - 相當於 KeyboardEvent.location。
  • modifiers string[] - 請參閱 InputEvent.modifiers。

在分派頁面中的 keydown 和 keyup 事件之前發出。調用 event.preventDefault 將阻止頁面 keydown/keyup 事件和菜單快捷鍵。

若僅阻止菜單快捷鍵，請使用 setIgnoreMenuShortcuts

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ width: 800, height: 600 })

win.webContents.on('before-input-event', (event, input) => {
  // For example, only enable application menu keyboard shortcuts when
  // Ctrl/Cmd are down.
  win.webContents.setIgnoreMenuShortcuts(!input.control && !input.meta)
})

事件：'enter-html-full-screen'

當視窗進入由 HTML API 觸發的全螢幕狀態時發出。

事件：'leave-html-full-screen'

當視窗離開由 HTML API 觸發的全螢幕狀態時發出。

事件：'zoom-changed'

返回

• event Event
• zoomDirection string - 可以是 in 或 out。

當使用者請求使用滑鼠滾輪更改縮放級別時發出。

事件：'blur'

當 WebContents 失去焦點時發出。

事件：'focus'

當 WebContents 獲得焦點時發出。

請注意，在 macOS 上，擁有焦點表示 WebContents 是視窗的第一響應者，因此在視窗之間切換焦點不會觸發 WebContents 的 focus 和 blur 事件，因為每個視窗的第一響應者沒有更改。

WebContents 的 focus 和 blur 事件應僅用於檢測同一視窗中不同 WebContents 和 BrowserView 之間的焦點變化。

事件：'devtools-open-url'

返回

• event Event
• url string - 點擊或選取連結的 URL。

當在開發人員工具中點擊連結，或在其上下文菜單中為連結選擇「在新分頁中開啟」時發出。

事件：'devtools-search-query'

返回

• event Event
• query string - 要查詢的文字。

當在其上下文菜單中為文字選擇「搜尋」時發出。

事件：'devtools-opened'

當開發人員工具開啟時發出。

事件：'devtools-closed'

當開發人員工具關閉時發出。

事件：'devtools-focused'

當開發人員工具被聚焦/開啟時發出。

事件：'certificate-error'

返回

• event Event
• url string
• error string - 錯誤代碼。
• certificate Certificate
• callback Function
  • isTrusted boolean - 指示憑證是否可以被視為受信任。
• isMainFrame boolean

當驗證 url 的 certificate 失敗時發出。

其用法與 app 的 certificate-error 事件 相同。

事件：'select-client-certificate'

返回

• event Event
• url URL
• certificateList Certificate[]
• callback Function
  • certificate Certificate - 必須是給定列表中的憑證。

當請求客戶端憑證時發出。

其用法與 app 的 select-client-certificate 事件 相同。

事件：'login'

返回

• event Event
• authenticationResponseDetails Object
  • url URL
• authInfo Object
  • isProxy boolean
  • scheme string
  • host string
  • port Integer
  • realm string
• callback Function
  • username string (可選)
  • password string (可選)

當 webContents 想要執行基本身份驗證時發出。

其用法與 app 的 login 事件 相同。

事件：'found-in-page'

返回

• event Event
• result Object
  • requestId Integer
  • activeMatchOrdinal Integer - 活動匹配的位置。
  • matches Integer - 匹配數。
  • selectionArea Rectangle - 第一個匹配區域的坐標。
  • finalUpdate boolean

當 webContents.findInPage 請求的結果可用時發出。

事件：'media-started-playing'

當媒體開始播放時發出。

事件：'media-paused'

當媒體暫停或播放完成時發出。

事件：'audio-state-changed'

返回

• event Event<>
  • audible boolean - 如果一個或多個框架或子 webContents 發出音訊，則為 True。

當媒體變得可聽或不可聽時發出。

事件：'did-change-theme-color'

返回

• event Event
• color (string | null) - 主題顏色格式為 '#rrggbb'。當未設定主題顏色時，為 null。

當頁面的主題顏色更改時發出。這通常是由於遇到 meta 標籤

<meta name='theme-color' content='#ff0000'>

事件：'update-target-url'

返回

• event Event
• url string

當滑鼠移動到連結上方或鍵盤將焦點移動到連結時發出。

事件：'cursor-changed'

返回

• event Event
• type string
• image NativeImage (可選)
• scale Float (可選) - 自訂游標的縮放比例。
• size Size (可選) - image 的大小。
• hotspot Point (可選) - 自訂游標熱點的坐標。

當游標類型更改時發出。type 參數可以是 pointer、crosshair、hand、text、wait、help、e-resize、n-resize、ne-resize、nw-resize、s-resize、se-resize、sw-resize、w-resize、ns-resize、ew-resize、nesw-resize、nwse-resize、col-resize、row-resize、m-panning、m-panning-vertical、m-panning-horizontal、e-panning、n-panning、ne-panning、nw-panning、s-panning、se-panning、sw-panning、w-panning、move、vertical-text、cell、context-menu、alias、progress、nodrop、copy、none、not-allowed、zoom-in、zoom-out、grab、grabbing、custom、null、drag-drop-none、drag-drop-move、drag-drop-copy、drag-drop-link、ns-no-resize、ew-no-resize、nesw-no-resize、nwse-no-resize 或 default。

如果 type 參數為 custom，則 image 參數將在 NativeImage 中保存自訂游標圖像，而 scale、size 和 hotspot 將保存有關自訂游標的其他資訊。

事件：'context-menu'

返回

• event Event
• params Object
  • x Integer - x 坐標。
  • y Integer - y 坐標。
  • frame WebFrameMain | null - 從中調用上下文菜單的框架。如果在框架導航或被銷毀後存取，可能為 null。
  • linkURL string - 封閉調用上下文菜單節點的連結 URL。
  • linkText string - 與連結關聯的文字。如果連結的內容是圖像，則可能為空字串。
  • pageURL string - 調用上下文菜單的頂層頁面的 URL。
  • frameURL string - 調用上下文菜單的子框架的 URL。
  • srcURL string - 調用上下文菜單元素的來源 URL。具有來源 URL 的元素是圖像、音訊和視訊。
  • mediaType string - 調用上下文菜單節點的類型。可以是 none、image、audio、video、canvas、file 或 plugin。
  • hasImageContents boolean - 上下文菜單是否在具有非空內容的圖像上調用。
  • isEditable boolean - 上下文是否可編輯。
  • selectionText string - 調用上下文菜單選取範圍的文字。
  • titleText string - 調用上下文菜單選取範圍的標題文字。
  • altText string - 調用上下文菜單選取範圍的替代文字。
  • suggestedFilename string - 透過上下文菜單的「連結另存為」選項儲存檔案時，建議使用的檔案名稱。
  • selectionRect Rectangle - 代表選取範圍在文件空間中座標的矩形。
  • selectionStartOffset number - 選取文字的起始位置。
  • referrerPolicy Referrer - 叫用選單之框架的 referrer 政策。
  • misspelledWord string - 游標下的拼錯字詞 (若有)。
  • dictionarySuggestions string[] - 建議替換 misspelledWord 給使用者的字詞陣列。僅在有拼錯字詞且拼字檢查已啟用時可用。
  • frameCharset string - 叫用選單之框架的字元編碼。
  • formControlType string - 呼叫內容選單的來源。可能的值包括 none、button-button、field-set、input-button、input-checkbox、input-color、input-date、input-datetime-local、input-email、input-file、input-hidden、input-image、input-month、input-number、input-password、input-radio、input-range、input-reset、input-search、input-submit、input-telephone、input-text、input-time、input-url、input-week、output、reset-button、select-list、select-list、select-multiple、select-one、submit-button 和 text-area。
  • spellcheckEnabled boolean - 如果上下文是可編輯的，拼字檢查是否已啟用。
  • menuSourceType string - 呼叫內容選單的輸入來源。可以是 none、mouse、keyboard、touch、touchMenu、longPress、longTap、touchHandle、stylus、adjustSelection 或 adjustSelectionReset。
  • mediaFlags Object - 內容選單在其上被呼叫之媒體元素的旗標。
    • inError boolean - 媒體元素是否已崩潰。
    • isPaused boolean - 媒體元素是否已暫停。
    • isMuted boolean - 媒體元素是否已靜音。
    • hasAudio boolean - 媒體元素是否有音訊。
    • isLooping boolean - 媒體元素是否正在循環播放。
    • isControlsVisible boolean - 媒體元素的控制項是否可見。
    • canToggleControls boolean - 媒體元素的控制項是否可切換。
    • canPrint boolean - 媒體元素是否可以列印。
    • canSave boolean - 媒體元素是否可以下載。
    • canShowPictureInPicture boolean - 媒體元素是否可以顯示子母畫面。
    • isShowingPictureInPicture boolean - 媒體元素目前是否正在顯示子母畫面。
    • canRotate boolean - 媒體元素是否可以旋轉。
    • canLoop boolean - 媒體元素是否可以循環播放。
  • editFlags Object - 這些旗標指示渲染器是否認為它可以執行相應的操作。
    • canUndo boolean - 渲染器是否認為它可以復原。
    • canRedo boolean - 渲染器是否認為它可以重做。
    • canCut boolean - 渲染器是否認為它可以剪下。
    • canCopy boolean - 渲染器是否認為它可以複製。
    • canPaste boolean - 渲染器是否認為它可以貼上。
    • canDelete boolean - 渲染器是否認為它可以刪除。
    • canSelectAll boolean - 渲染器是否認為它可以全選。
    • canEditRichly boolean - 渲染器是否認為它可以豐富地編輯文字。

當有新的內容選單需要處理時發出。

事件：'select-bluetooth-device'

返回

• event Event
• devices BluetoothDevice[]
• callback Function
  • deviceId string

當呼叫 navigator.bluetooth.requestDevice 時，需要選取藍牙裝置時發出。callback 應使用要選取裝置的 deviceId 呼叫。傳遞空字串給 callback 將會取消請求。

如果沒有為此事件新增事件監聽器，或者在處理此事件時未呼叫 event.preventDefault，則會自動選取第一個可用的裝置。

由於藍牙的性質，當呼叫 navigator.bluetooth.requestDevice 時掃描裝置可能需要時間，並且會導致 select-bluetooth-device 多次觸發，直到使用裝置 ID 或空字串呼叫 callback 以取消請求。

main.js

const { app, BrowserWindow } = require('electron')

let win = null

app.whenReady().then(() => {
  win = new BrowserWindow({ width: 800, height: 600 })
  win.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {
    event.preventDefault()
    const result = deviceList.find((device) => {
      return device.deviceName === 'test'
    })
    if (!result) {
      // The device wasn't found so we need to either wait longer (eg until the
      // device is turned on) or cancel the request by calling the callback
      // with an empty string.
      callback('')
    } else {
      callback(result.deviceId)
    }
  })
})

事件：'paint'

返回

• details Event<>
  • texture OffscreenSharedTexture (選用) 實驗性質 - 框架的 GPU 共用紋理，當 webPreferences.offscreen.useSharedTexture 為 true 時。
• dirtyRect Rectangle
• image NativeImage - 整個框架的影像資料。

當產生新框架時發出。只有髒區域會傳遞到緩衝區中。

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ webPreferences: { offscreen: true } })
win.webContents.on('paint', (event, dirty, image) => {
  // updateBitmap(dirty, image.getBitmap())
})
win.loadURL('https://github.com')

當使用共用紋理功能 (將 webPreferences.offscreen.useSharedTexture 設定為 true) 時，您可以將紋理控制代碼傳遞到外部渲染管線，而無需在 CPU 和 GPU 記憶體之間複製資料的額外負擔，並具有 Chromium 的硬體加速支援。此功能對於高效能渲染場景很有幫助。

同時只能存在有限數量的紋理，因此在完成紋理後立即呼叫 texture.release() 很重要。透過自行管理紋理生命週期，您可以安全地透過 IPC 將 texture.textureInfo 傳遞給其他程序。

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ webPreferences: { offscreen: { useSharedTexture: true } } })
win.webContents.on('paint', async (e, dirty, image) => {
  if (e.texture) {
    // By managing lifecycle yourself, you can handle the event in async handler or pass the `e.texture.textureInfo`
    // to other processes (not `e.texture`, the `e.texture.release` function is not passable through IPC).
    await new Promise(resolve => setTimeout(resolve, 50))

    // You can send the native texture handle to native code for importing into your rendering pipeline.
    // For example: https://github.com/electron/electron/tree/main/spec/fixtures/native-addon/osr-gpu
    // importTextureHandle(dirty, e.texture.textureInfo)

    // You must call `e.texture.release()` as soon as possible, before the underlying frame pool is drained.
    e.texture.release()
  }
})
win.loadURL('https://github.com')

事件：'devtools-reload-page'

當開發人員工具視窗指示 webContents 重新載入時發出

事件：'will-attach-webview'

返回

• event Event
• webPreferences WebPreferences - 客戶頁面將使用的網頁偏好設定。可以修改此物件以調整客戶頁面的偏好設定。
• params Record<string, string> - 其他 <webview> 參數，例如 src URL。可以修改此物件以調整客戶頁面的參數。

當 <webview> 的網頁內容正在附加到此網頁內容時發出。呼叫 event.preventDefault() 將會銷毀客戶頁面。

此事件可用於在載入 <webview> 的 webContents 之前，為其設定 webPreferences，並提供設定無法透過 <webview> 屬性設定之設定的功能。

事件：'did-attach-webview'

返回

• event Event
• webContents WebContents - <webview> 使用的客戶網頁內容。

當 <webview> 已附加到此網頁內容時發出。

事件：'console-message'

返回

• details Event<>
  • message string - 訊息文字
  • level string - 訊息嚴重性。可能的值包括 info、warning、error 和 debug。
  • lineNumber Integer - 日誌來源中的行號
  • sourceId string - 日誌來源的 URL
  • frame WebFrameMain - 記錄訊息的框架
• level Integer 已棄用 - 日誌層級，從 0 到 3。依序對應到 verbose、info、warning 和 error。
• message string 已棄用 - 實際的控制台訊息
• line Integer 已棄用 - 觸發此控制台訊息之來源的行號
• sourceId string 已棄用

當關聯的視窗記錄控制台訊息時發出。

事件：'preload-error'

返回

• event Event
• preloadPath string
• error Error

當預載腳本 preloadPath 擲出未處理的例外狀況 error 時發出。

事件：'ipc-message'

返回

• event IpcMainEvent
• channel string - 頻道
• ...args any[]

當渲染器程序透過 ipcRenderer.send() 傳送非同步訊息時發出。

另請參閱 webContents.ipc，它提供一個類似 IpcMain 的介面，用於回應來自此 WebContents 的 IPC 訊息。

事件：'ipc-message-sync'

返回

• event IpcMainEvent
• channel string - 頻道
• ...args any[]

當渲染器程序透過 ipcRenderer.sendSync() 傳送同步訊息時發出。

另請參閱 webContents.ipc，它提供一個類似 IpcMain 的介面，用於回應來自此 WebContents 的 IPC 訊息。

事件：'preferred-size-changed'

返回

• event Event
• preferredSize Size - 包含文件版面配置所需的最小尺寸，而無需捲動。

當 WebContents 的偏好尺寸已變更時發出。

只有在 webPreferences 中將 enablePreferredSizeMode 設定為 true 時，才會發出此事件。

事件：'frame-created'

返回

• event Event
• details Object
  • frame WebFrameMain | null - 建立的框架。如果在框架導航或被銷毀後存取，則可能為 null。

當 mainFrame、<iframe> 或巢狀 <iframe> 在頁面中載入時發出。

實例方法

contents.loadURL(url[, options])

• url string
• options Object (選用)
  • httpReferrer (string | Referrer) (選用) - HTTP Referrer URL。
  • userAgent string (選用) - 發起請求的使用者代理程式。
  • extraHeaders string (選用) - 以 "\n" 分隔的額外標頭。
  • postData (UploadRawData | UploadFile)[] (選用)
  • baseURLForDataURL string (選用) - 資料 URL 要載入之檔案的基礎 URL (帶有尾隨路徑分隔符號)。只有在指定的 url 是資料 URL 且需要載入其他檔案時才需要此項。

傳回 Promise<void> - 當頁面完成載入時 (請參閱 did-finish-load)，promise 將會解析，如果頁面載入失敗 (請參閱 did-fail-load)，promise 將會拒絕。已附加 noop 拒絕處理常式，以避免未處理的拒絕錯誤。

在視窗中載入 url。url 必須包含協定前綴，例如 http:// 或 file://。如果載入應繞過 HTTP 快取，則使用 pragma 標頭來達成。

const win = new BrowserWindow()
const options = { extraHeaders: 'pragma: no-cache\n' }
win.webContents.loadURL('https://github.com', options)

contents.loadFile(filePath[, options])

• filePath string
• options Object (選用)
  • query Record<string, string> (選用) - 傳遞至 url.format()。
  • search string (選用) - 傳遞至 url.format()。
  • hash string (選用) - 傳遞至 url.format()。

傳回 Promise<void> - 當頁面完成載入時 (請參閱 did-finish-load)，promise 將會解析，如果頁面載入失敗 (請參閱 did-fail-load)，promise 將會拒絕。

在視窗中載入給定的檔案，filePath 應該是相對於應用程式根目錄之 HTML 檔案的路徑。例如，像這樣的應用程式結構

| root
| - package.json
| - src
|   - main.js
|   - index.html

將需要像這樣的程式碼

const win = new BrowserWindow()
win.loadFile('src/index.html')

contents.downloadURL(url[, options])

• url string
• options Object (選用)
  • headers Record<string, string> (選用) - HTTP 請求標頭。

啟動下載 url 的資源，而無需導航。將會觸發 session 的 will-download 事件。

contents.getURL()

傳回 string - 目前網頁的 URL。

const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('https://github.com').then(() => {
  const currentURL = win.webContents.getURL()
  console.log(currentURL)
})

contents.getTitle()

傳回 string - 目前網頁的標題。

contents.isDestroyed()

傳回 boolean - 網頁是否已銷毀。

contents.close([opts])

• opts Object (選用)
  • waitForBeforeUnload boolean - 若為 true，則在關閉頁面之前觸發 beforeunload 事件。如果頁面阻止卸載，則 WebContents 將不會關閉。如果頁面請求阻止卸載，則會觸發 will-prevent-unload。

關閉頁面，如同網頁內容已呼叫 window.close()。

如果頁面已成功關閉 (即，頁面未阻止卸載，或 waitForBeforeUnload 為 false 或未指定)，則 WebContents 將會被銷毀且不再可用。將會發出 destroyed 事件。

contents.focus()

聚焦網頁。

contents.isFocused()

傳回 boolean - 網頁是否已聚焦。

contents.isLoading()

傳回 boolean - 網頁是否仍在載入資源。

contents.isLoadingMainFrame()

傳回 boolean - 主要框架 (而不僅僅是 iframes 或其中的框架) 是否仍在載入。

contents.isWaitingForResponse()

傳回 boolean - 網頁是否正在等待來自頁面主要資源的首次回應。

contents.stop()

停止任何擱置中的導航。

contents.reload()

重新載入目前的網頁。

contents.reloadIgnoringCache()

重新載入目前頁面並忽略快取。

contents.canGoBack() 已棄用

歷史記錄

版本	變更
>=32.0.0	API DEPRECATED

傳回 boolean - 瀏覽器是否可以返回上一個網頁。

已棄用： 應使用新的 contents.navigationHistory.canGoBack API。

contents.canGoForward() 已棄用

歷史記錄

版本	變更
>=32.0.0	API DEPRECATED

傳回 boolean - 瀏覽器是否可以前進到下一個網頁。

已棄用： 應使用新的 contents.navigationHistory.canGoForward API。

contents.canGoToOffset(offset) 已棄用

歷史記錄

版本	變更
>=32.0.0	API DEPRECATED

• offset Integer

傳回 boolean - 網頁是否可以前往 offset。

已棄用： 應使用新的 contents.navigationHistory.canGoToOffset API。

contents.clearHistory() 已棄用

歷史記錄

版本	變更
>=32.0.0	API DEPRECATED

清除導航歷史記錄。

已棄用： 應使用新的 contents.navigationHistory.clear API。

contents.goBack() 已棄用

歷史記錄

版本	變更
>=32.0.0	API DEPRECATED

使瀏覽器返回一個網頁。

已棄用： 應使用新的 contents.navigationHistory.goBack API。

contents.goForward() 已棄用

歷史記錄

版本	變更
>=32.0.0	API DEPRECATED

使瀏覽器前進一個網頁。

已棄用： 應使用新的 contents.navigationHistory.goForward API。

contents.goToIndex(index)` 已棄用

歷史記錄

版本	變更
>=32.0.0	API DEPRECATED

• index Integer

將瀏覽器導航到指定的絕對網頁索引。

已棄用： 應使用新的 contents.navigationHistory.goToIndex API。

contents.goToOffset(offset) 已棄用

歷史記錄

版本	變更
>=32.0.0	API DEPRECATED

• offset Integer

從「目前項目」導航到指定的偏移量。

已棄用： 應使用新的 contents.navigationHistory.goToOffset API。

contents.isCrashed()

傳回 boolean - 渲染器程序是否已崩潰。

contents.forcefullyCrashRenderer()

強制終止目前託管此 webContents 的渲染器程序。這將導致發出 render-process-gone 事件，且 reason=killed || reason=crashed。請注意，某些 webContents 共用渲染器程序，因此呼叫此方法也可能會使其他 webContents 的主機程序崩潰。

在呼叫此方法後立即呼叫 reload() 將強制重新載入發生在新的程序中。當此程序不穩定或無法使用時，應使用此方法，例如為了從 unresponsive 事件中恢復。

const win = new BrowserWindow()

win.webContents.on('unresponsive', async () => {
  const { response } = await dialog.showMessageBox({
    message: 'App X has become unresponsive',
    title: 'Do you want to try forcefully reloading the app?',
    buttons: ['OK', 'Cancel'],
    cancelId: 1
  })
  if (response === 0) {
    win.webContents.forcefullyCrashRenderer()
    win.webContents.reload()
  }
})

contents.setUserAgent(userAgent)

• userAgent string - 使用者代理程式

覆寫此網頁的使用者代理程式。

contents.getUserAgent()

傳回 string - 此網頁的使用者代理程式。

contents.insertCSS(css[, options])

• css string
• options Object (選用)
  • cssOrigin string (選用) - 可以是 'user' 或 'author'。設定插入樣式表的 級聯來源。預設值為 'author'。

傳回 Promise<string> - 一個 promise，它會解析為已插入 CSS 的金鑰，該金鑰稍後可用於透過 contents.removeInsertedCSS(key) 移除 CSS。

將 CSS 注入到目前的網頁中，並傳回插入樣式表的唯一金鑰。

const win = new BrowserWindow()
win.webContents.on('did-finish-load', () => {
  win.webContents.insertCSS('html, body { background-color: #f00; }')
})

contents.removeInsertedCSS(key)`

• key string - 金鑰

傳回 Promise<void> - 如果移除成功，則解析。

從目前的網頁中移除插入的 CSS。樣式表由其金鑰識別，該金鑰從 contents.insertCSS(css) 傳回。

const win = new BrowserWindow()

win.webContents.on('did-finish-load', async () => {
  const key = await win.webContents.insertCSS('html, body { background-color: #f00; }')
  win.webContents.removeInsertedCSS(key)
})

contents.executeJavaScript(code[, userGesture])

• code string - 程式碼
• userGesture boolean (選用) - 預設值為 false。

傳回 Promise<any> - 一個 promise，它會解析為已執行程式碼的結果，如果程式碼的結果是被拒絕的 promise，則會拒絕。

在頁面中評估 code。

在瀏覽器視窗中，某些 HTML API (例如 requestFullScreen) 只能由使用者的手勢呼叫。將 userGesture 設定為 true 將會移除此限制。

程式碼執行將會暫停，直到網頁停止載入。

const win = new BrowserWindow()

win.webContents.executeJavaScript('fetch("https://jsonplaceholder.typicode.com/users/1").then(resp => resp.json())', true)
  .then((result) => {
    console.log(result) // Will be the JSON object from the fetch call
  })

contents.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture])

• worldId Integer - 要在其中執行 javascript 的世界 ID，0 是預設世界，999 是 Electron 的 contextIsolation 功能使用的世界。您可以在此處提供任何整數。
• scripts WebSource[] - 腳本
• userGesture boolean (選用) - 預設值為 false。

傳回 Promise<any> - 一個 promise，它會解析為已執行程式碼的結果，如果程式碼的結果是被拒絕的 promise，則會拒絕。

運作方式與 executeJavaScript 類似，但在隔離的上下文中評估 scripts。

contents.setIgnoreMenuShortcuts(ignore)

• ignore boolean - 忽略

當此網頁內容處於聚焦狀態時，忽略應用程式選單捷徑。

contents.setWindowOpenHandler(handler)

• handler Function<WindowOpenHandlerResponse> - 處理常式

  • details Object
    • url string - 傳遞至 window.open() 之 URL 的已解析版本。例如，使用 window.open('foo') 開啟視窗將產生類似 https://the-origin/the/current/path/foo 的結果。
    • frameName string - window.open() 中提供的視窗名稱
    • features string - 提供給 window.open() 的視窗功能之逗號分隔清單。
    • disposition string - 可以是 default、foreground-tab、background-tab、new-window 或 other。
    • referrer Referrer - 將傳遞到新視窗的引用網址。可能會或可能不會導致發送 Referer 標頭，具體取決於引用網址政策。
    • postBody PostBody (可選) - 將與適當的標頭一起發送到新視窗的 post data。如果沒有要發送的 post data，則值將為 null。僅在視窗是由設定 target=_blank 的表單建立時定義。

  傳回 WindowOpenHandlerResponse - 當設定為 { action: 'deny' } 時，取消建立新視窗。{ action: 'allow' } 將允許建立新視窗。傳回無法辨識的值 (例如 null、undefined 或沒有可辨識 'action' 值的物件) 將導致控制台錯誤，並具有與傳回 {action: 'deny'} 相同的效果。

在渲染器請求建立新視窗之前呼叫，例如透過 window.open()、具有 target="_blank" 的連結、按住 Shift 鍵並點擊連結，或提交具有 <form target="_blank"> 的表單。請參閱 window.open() 以取得更多詳細資訊，以及如何將其與 did-create-window 結合使用。

一個範例，示範如何自訂新的 BrowserWindow 建立程序，使其成為附加到主視窗的 BrowserView

const { BrowserView, BrowserWindow } = require('electron')

const mainWindow = new BrowserWindow()

mainWindow.webContents.setWindowOpenHandler((details) => {
  return {
    action: 'allow',
    createWindow: (options) => {
      const browserView = new BrowserView(options)
      mainWindow.addBrowserView(browserView)
      browserView.setBounds({ x: 0, y: 0, width: 640, height: 480 })
      return browserView.webContents
    }
  }
})

contents.setAudioMuted(muted)

• muted boolean - 已靜音

將目前網頁上的音訊靜音。

contents.isAudioMuted()

傳回 boolean - 此頁面是否已靜音。

contents.isCurrentlyAudible()

傳回 boolean - 目前是否正在播放音訊。

contents.setZoomFactor(factor)

• factor Double - 縮放比例；預設值為 1.0。

將縮放比例變更為指定的比例。縮放比例是縮放百分比除以 100，因此 300% = 3.0。

比例必須大於 0.0。

contents.getZoomFactor()

傳回 number - 目前的縮放比例。

contents.setZoomLevel(level)

• level number - 縮放層級。

將縮放層級變更為指定的層級。原始大小為 0，且每個高於或低於 0 的增量分別表示縮放 20% 更大或更小到原始大小的預設限制 300% 和 50%。此公式為 scale := 1.2 ^ level。

注意：Chromium 層級的縮放政策是同源，這表示特定網域的縮放層級會跨越所有具有相同網域的視窗實例傳播。區分視窗 URL 將使縮放功能適用於每個視窗。

contents.getZoomLevel()

傳回 number - 目前的縮放層級。

contents.setVisualZoomLevelLimits(minimumLevel, maximumLevel)

• minimumLevel number - 最小層級
• maximumLevel number - 最大層級

傳回 Promise<void>

設定最大和最小捏合縮放層級。

注意：視覺縮放預設在 Electron 中停用。若要重新啟用，請呼叫

const win = new BrowserWindow()
win.webContents.setVisualZoomLevelLimits(1, 3)

contents.undo()

在網頁中執行編輯命令 undo。

contents.redo()

在網頁中執行編輯命令 redo。

contents.cut()

在網頁中執行編輯命令 cut。

contents.copy()

在網頁中執行編輯命令 copy。

contents.centerSelection()

在網頁中置中目前的文字選取範圍。

contents.copyImageAt(x, y)

• x Integer
• y Integer

將給定位置的影像複製到剪貼簿。

contents.paste()

在網頁中執行編輯命令 paste。

contents.pasteAndMatchStyle()

在網頁中執行編輯命令 pasteAndMatchStyle。

contents.delete()

在網頁中執行編輯命令 delete。

contents.selectAll()

在網頁中執行編輯命令 selectAll。

contents.unselect()

在網頁中執行編輯命令 unselect。

contents.scrollToTop()

捲動到目前 webContents 的頂端。

contents.scrollToBottom()

捲動到目前 webContents 的底部。

contents.adjustSelection(options)

• options Object - 選項
  • start Number (選用) - 位移目前選取範圍開始索引的量。
  • end Number (選用) - 位移目前選取範圍結束索引的量。

依據給定的量調整聚焦框架中目前文字選取範圍的起點和終點。負量會將選取範圍移向文件開頭，正量會將選取範圍移向文件結尾。

範例

const win = new BrowserWindow()

// Adjusts the beginning of the selection 1 letter forward,
// and the end of the selection 5 letters forward.
win.webContents.adjustSelection({ start: 1, end: 5 })

// Adjusts the beginning of the selection 2 letters forward,
// and the end of the selection 3 letters backward.
win.webContents.adjustSelection({ start: 2, end: -3 })

對於呼叫 win.webContents.adjustSelection({ start: 1, end: 5 })

之前

之後

contents.replace(text)

• text string - 文字

在網頁中執行編輯命令 replace。

contents.replaceMisspelling(text)

• text string - 文字

在網頁中執行編輯命令 replaceMisspelling。

contents.insertText(text)

• text string - 文字

傳回 Promise<void>

將 text 插入到聚焦的元素。

contents.findInPage(text[, options])

• text string - 要搜尋的內容，不得為空。
• options Object (選用)
  • forward boolean (選用) - 是否向前或向後搜尋，預設值為 true。
  • findNext boolean (選用) - 是否以此請求開始新的文字搜尋會期。初始請求應為 true，後續請求應為 false。預設值為 false。
  • matchCase boolean (選用) - 搜尋是否應區分大小寫，預設值為 false。

傳回 Integer - 用於請求的請求 ID。

開始請求以尋找網頁中 text 的所有符合項目。請求結果可以透過訂閱 found-in-page 事件取得。

contents.stopFindInPage(action)

• action 字串 - 指定結束 webContents.findInPage 請求時要執行的動作。
  • clearSelection - 清除選取範圍。
  • keepSelection - 將選取範圍轉換為一般選取範圍。
  • activateSelection - 聚焦並點擊選取節點。

停止任何針對 webContents 且具有提供 action 的 findInPage 請求。

const win = new BrowserWindow()
win.webContents.on('found-in-page', (event, result) => {
  if (result.finalUpdate) win.webContents.stopFindInPage('clearSelection')
})

const requestId = win.webContents.findInPage('api')
console.log(requestId)

contents.capturePage([rect, opts])

• rect Rectangle (選用) - 要擷取的頁面區域。
• opts Object (選用)
  • stayHidden boolean (選用) - 保持頁面隱藏而非顯示。預設值為 false。
  • stayAwake boolean (選用) - 保持系統喚醒而非允許進入睡眠。預設值為 false。

回傳 Promise<NativeImage> - 以 NativeImage 解析。

擷取 rect 內頁面的快照。省略 rect 將擷取整個可見頁面。當頁面的瀏覽器視窗為隱藏且擷取器計數為非零時，該頁面被視為可見。如果您希望頁面保持隱藏，應確保將 stayHidden 設定為 true。

contents.isBeingCaptured()

回傳 boolean - 此頁面是否正在被擷取。當擷取器計數大於 0 時，回傳 true。

contents.getPrintersAsync()

取得系統印表機列表。

回傳 Promise<PrinterInfo[]> - 以 PrinterInfo[] 解析。

contents.print([options], [callback])

• options Object (選用)
  • silent boolean (選用) - 不詢問使用者列印設定。預設值為 false。
  • printBackground boolean (選用) - 列印網頁的背景顏色和圖片。預設值為 false。
  • deviceName 字串 (選用) - 設定要使用的印表機裝置名稱。必須是系統定義的名稱，而不是「友善」名稱，例如 'Brother_QL_820NWB' 而不是 'Brother QL-820NWB'。
  • color boolean (選用) - 設定列印的網頁是否為彩色或灰階。預設值為 true。
  • margins 物件 (選用)
    • marginType 字串 (選用) - 可以是 default、none、printableArea 或 custom。如果選擇 custom，您還需要指定 top、bottom、left 和 right。
    • top 數字 (選用) - 列印網頁的頂部邊界，以像素為單位。
    • bottom 數字 (選用) - 列印網頁的底部邊界，以像素為單位。
    • left 數字 (選用) - 列印網頁的左側邊界，以像素為單位。
    • right 數字 (選用) - 列印網頁的右側邊界，以像素為單位。
  • landscape boolean (選用) - 網頁是否應以橫向模式列印。預設值為 false。
  • scaleFactor 數字 (選用) - 網頁的縮放比例。
  • pagesPerSheet 數字 (選用) - 每張紙要列印的頁數。
  • collate boolean (選用) - 網頁是否應整理分套。
  • copies 數字 (選用) - 要列印的網頁份數。
  • pageRanges 物件陣列 (選用) - 要列印的頁面範圍。在 macOS 上，僅接受一個範圍。
    • from 數字 - 要列印的第一頁索引 (從 0 開始)。
    • to 數字 - 要列印的最後一頁索引 (包含) (從 0 開始)。
  • duplexMode 字串 (選用) - 設定列印網頁的雙面列印模式。可以是 simplex、shortEdge 或 longEdge。
  • dpi Record<string, number> (選用)
    • horizontal 數字 (選用) - 水平 dpi。
    • vertical 數字 (選用) - 垂直 dpi。
  • header 字串 (選用) - 要列印為頁首的字串。
  • footer 字串 (選用) - 要列印為頁尾的字串。
  • pageSize 字串 | Size (選用) - 指定列印文件的頁面尺寸。可以是 A0、A1、A2、A3、A4、A5、A6、Legal、Letter、Tabloid 或包含 height 和 width 的物件。
• callback 函數 (選用)
  • success boolean - 指示列印呼叫是否成功。
  • failureReason 字串 - 列印失敗時回呼的錯誤描述。

當傳遞自訂 pageSize 時，Chromium 會嘗試驗證平台特定的 width_microns 和 height_microns 最小值。寬度和高度都必須至少為 353 微米，但在某些作業系統上可能會更高。

列印視窗的網頁。當 silent 設定為 true 時，如果 deviceName 為空且使用預設列印設定，Electron 將選擇系統的預設印表機。

使用 page-break-before: always; CSS 樣式強制列印到新頁面。

使用範例

const win = new BrowserWindow()
const options = {
  silent: true,
  deviceName: 'My-Printer',
  pageRanges: [{
    from: 0,
    to: 1
  }]
}
win.webContents.print(options, (success, errorType) => {
  if (!success) console.log(errorType)
})

contents.printToPDF(options)

• options Object - 選項
  • landscape boolean (選用) - 紙張方向。true 為橫向，false 為直向。預設為 false。
  • displayHeaderFooter boolean (選用) - 是否顯示頁首和頁尾。預設為 false。
  • printBackground boolean (選用) - 是否列印背景圖形。預設為 false。
  • scale 數字 (選用) - 網頁渲染的縮放比例。預設為 1。
  • pageSize 字串 | Size (選用) - 指定產生的 PDF 頁面尺寸。可以是 A0、A1、A2、A3、A4、A5、A6、Legal、Letter、Tabloid、Ledger 或包含英吋為單位的 height 和 width 的物件。預設為 Letter。
  • margins 物件 (選用)
    • top 數字 (選用) - 頂部邊界，單位為英吋。預設為 1 公分 (~0.4 英吋)。
    • bottom 數字 (選用) - 底部邊界，單位為英吋。預設為 1 公分 (~0.4 英吋)。
    • left 數字 (選用) - 左側邊界，單位為英吋。預設為 1 公分 (~0.4 英吋)。
    • right 數字 (選用) - 右側邊界，單位為英吋。預設為 1 公分 (~0.4 英吋)。
  • pageRanges 字串 (選用) - 要列印的頁面範圍，例如 '1-5, 8, 11-13'。預設為空字串，表示列印所有頁面。
  • headerTemplate 字串 (選用) - 列印頁首的 HTML 範本。應為有效的 HTML 標記，並使用以下類別將列印值注入其中：date (格式化的列印日期)、title (文件標題)、url (文件位置)、pageNumber (目前頁碼) 和 totalPages (文件中的總頁數)。例如，<span class=title></span> 將產生包含標題的 span。
  • footerTemplate 字串 (選用) - 列印頁尾的 HTML 範本。應使用與 headerTemplate 相同的格式。
  • preferCSSPageSize boolean (選用) - 是否優先使用 css 定義的頁面尺寸。預設為 false，在這種情況下，內容將縮放以符合紙張尺寸。
  • generateTaggedPDF boolean (選用) Experimental - 是否產生標記 (可存取) 的 PDF。預設為 false。由於此屬性為實驗性質，因此產生的 PDF 可能無法完全符合 PDF/UA 和 WCAG 標準。
  • generateDocumentOutline boolean (選用) Experimental - 是否從內容標題產生 PDF 文件大綱。預設為 false。

回傳 Promise<Buffer> - 以產生的 PDF 資料解析。

將視窗的網頁列印為 PDF。

如果在網頁中使用 @page CSS at-rule，則會忽略 landscape。

webContents.printToPDF 的範例

const { app, BrowserWindow } = require('electron')
const fs = require('node:fs')
const path = require('node:path')
const os = require('node:os')

app.whenReady().then(() => {
  const win = new BrowserWindow()
  win.loadURL('https://github.com')

  win.webContents.on('did-finish-load', () => {
    // Use default printing options
    const pdfPath = path.join(os.homedir(), 'Desktop', 'temp.pdf')
    win.webContents.printToPDF({}).then(data => {
      fs.writeFile(pdfPath, data, (error) => {
        if (error) throw error
        console.log(`Wrote PDF successfully to ${pdfPath}`)
      })
    }).catch(error => {
      console.log(`Failed to write PDF to ${pdfPath}: `, error)
    })
  })
})

有關更多資訊，請參閱 Page.printToPdf。

contents.addWorkSpace(path)

• path 字串

將指定的路徑新增至 DevTools 工作區。必須在 DevTools 建立後使用。

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.webContents.on('devtools-opened', () => {
  win.webContents.addWorkSpace(__dirname)
})

contents.removeWorkSpace(path)

• path 字串

從 DevTools 工作區移除指定的路徑。

contents.setDevToolsWebContents(devToolsWebContents)

• devToolsWebContents WebContents

使用 devToolsWebContents 作為目標 WebContents 以顯示 devtools。

devToolsWebContents 不得執行任何導覽，且在呼叫後不應將其用於其他用途。

預設情況下，Electron 透過建立具有原生檢視的內部 WebContents 來管理 devtools，開發人員對其控制非常有限。透過 setDevToolsWebContents 方法，開發人員可以使用任何 WebContents 在其中顯示 devtools，包括 BrowserWindow、BrowserView 和 <webview> 標籤。

請注意，關閉 devtools 不會銷毀 devToolsWebContents，銷毀 devToolsWebContents 是呼叫者的責任。

在 <webview> 標籤中顯示 devtools 的範例

<html>
<head>
  <style type="text/css">
    * { margin: 0; }
    #browser { height: 70%; }
    #devtools { height: 30%; }
  </style>
</head>
<body>
  <webview id="browser" src="https://github.com"></webview>
  <webview id="devtools" src="about:blank"></webview>
  <script>
    const { ipcRenderer } = require('electron')
    const emittedOnce = (element, eventName) => new Promise(resolve => {
      element.addEventListener(eventName, event => resolve(event), { once: true })
    })
    const browserView = document.getElementById('browser')
    const devtoolsView = document.getElementById('devtools')
    const browserReady = emittedOnce(browserView, 'dom-ready')
    const devtoolsReady = emittedOnce(devtoolsView, 'dom-ready')
    Promise.all([browserReady, devtoolsReady]).then(() => {
      const targetId = browserView.getWebContentsId()
      const devtoolsId = devtoolsView.getWebContentsId()
      ipcRenderer.send('open-devtools', targetId, devtoolsId)
    })
  </script>
</body>
</html>

// Main process
const { ipcMain, webContents } = require('electron')
ipcMain.on('open-devtools', (event, targetContentsId, devtoolsContentsId) => {
  const target = webContents.fromId(targetContentsId)
  const devtools = webContents.fromId(devtoolsContentsId)
  target.setDevToolsWebContents(devtools)
  target.openDevTools()
})

在 BrowserWindow 中顯示 devtools 的範例

main.js

const { app, BrowserWindow } = require('electron')

let win = null
let devtools = null

app.whenReady().then(() => {
  win = new BrowserWindow()
  devtools = new BrowserWindow()
  win.loadURL('https://github.com')
  win.webContents.setDevToolsWebContents(devtools.webContents)
  win.webContents.openDevTools({ mode: 'detach' })
})

contents.openDevTools([options])

• options Object (選用)
  • mode 字串 - 以指定的停駐狀態開啟 devtools，可以是 left、right、bottom、undocked、detach。預設為上次使用的停駐狀態。在 undocked 模式下，可以停駐回去。在 detach 模式下則否。
  • activate boolean (選用) - 是否將開啟的 devtools 視窗帶到前景。預設值為 true。
  • title 字串 (選用) - DevTools 視窗的標題 (僅在 undocked 或 detach 模式下)。

開啟 devtools。

當 contents 是 <webview> 標籤時，mode 預設為 detach，明確傳遞空 mode 可以強制使用上次使用的停駐狀態。

在 Windows 上，如果啟用 Windows 控制項覆疊，Devtools 將以 mode: 'detach' 開啟。

contents.closeDevTools()

關閉 devtools。

contents.isDevToolsOpened()

回傳 boolean - devtools 是否已開啟。

contents.isDevToolsFocused()

回傳 boolean - devtools 視窗是否已聚焦。

contents.getDevToolsTitle()

回傳 string - DevTools 視窗的目前標題。這僅在 DevTools 以 undocked 或 detach 模式開啟時可見。

contents.setDevToolsTitle(title)

• title string

將 DevTools 視窗的標題變更為 title。這僅在 DevTools 以 undocked 或 detach 模式開啟時可見。

contents.toggleDevTools()

切換開發人員工具。

contents.inspectElement(x, y)

• x Integer
• y Integer

開始檢查位置 (x, y) 的元素。

contents.inspectSharedWorker()

為共享 worker 內容開啟開發人員工具。

contents.inspectSharedWorkerById(workerId)

• workerId 字串

根據 ID 檢查共享 worker。

contents.getAllSharedWorkers()

回傳 SharedWorkerInfo[] - 關於所有共享 Worker 的資訊。

contents.inspectServiceWorker()

為 service worker 內容開啟開發人員工具。

contents.send(channel, ...args)

• channel string - 頻道
• ...args any[]

透過 channel 將非同步訊息連同引數傳送至渲染器程序。引數將使用 結構化複製演算法 序列化，就像 postMessage 一樣，因此不會包含原型鏈。傳送函數、Promise、符號、WeakMap 或 WeakSet 將會擲出例外。

警告

傳送非標準 JavaScript 類型 (例如 DOM 物件或特殊的 Electron 物件) 將會擲出例外。

如需額外閱讀資料，請參閱 Electron 的 IPC 指南。

contents.sendToFrame(frameId, channel, ...args)

• frameId 整數 | [number, number] - 要傳送至的框架 ID，或一對 [processId, frameId] (如果框架與主框架位於不同的程序中)。
• channel string - 頻道
• ...args any[]

透過 channel 將非同步訊息連同引數傳送至渲染器程序中的特定框架。引數將使用 結構化複製演算法 序列化，就像 postMessage 一樣，因此不會包含原型鏈。傳送函數、Promise、符號、WeakMap 或 WeakSet 將會擲出例外。

注意： 傳送非標準 JavaScript 類型 (例如 DOM 物件或特殊的 Electron 物件) 將會擲出例外。

渲染器程序可以透過使用 ipcRenderer 模組監聽 channel 來處理訊息。

如果您想要取得給定渲染器內容的 frameId，您應該使用 webFrame.routingId 值。例如：

// In a renderer process
console.log('My frameId is:', require('electron').webFrame.routingId)

您也可以從主程序中所有傳入的 IPC 訊息讀取 frameId。

// In the main process
ipcMain.on('ping', (event) => {
  console.info('Message came from frameId:', event.frameId)
})

contents.postMessage(channel, message, [transfer])

• channel string - 頻道
• message 任何
• transfer MessagePortMain[] (選用)

傳送訊息至渲染器程序，可選擇性地轉移零或多個 MessagePortMain 物件的所有權。

轉移的 MessagePortMain 物件將在渲染器程序中透過存取發射事件的 ports 屬性來使用。當它們到達渲染器時，它們將會是原生 DOM MessagePort 物件。

例如

// Main process
const win = new BrowserWindow()
const { port1, port2 } = new MessageChannelMain()
win.webContents.postMessage('port', { message: 'hello' }, [port1])

// Renderer process
ipcRenderer.on('port', (e, msg) => {
  const [port] = e.ports
  // ...
})

contents.enableDeviceEmulation(parameters)

• parameters 物件
  • screenPosition 字串 - 指定要模擬的螢幕類型 (預設值：desktop)
    • desktop - 桌面螢幕類型。
    • mobile - 行動螢幕類型。
  • screenSize Size - 設定模擬的螢幕尺寸 (screenPosition == mobile)。
  • viewPosition Point - 將檢視畫面定位在螢幕上 (screenPosition == mobile) (預設值：{ x: 0, y: 0 })。
  • deviceScaleFactor 整數 - 設定裝置縮放比例 (如果為零，則預設為原始裝置縮放比例) (預設值：0)。
  • viewSize Size - 設定模擬的檢視畫面尺寸 (空白表示不覆寫)
  • scale 浮點數 - 模擬檢視畫面在可用空間內的縮放比例 (不在符合檢視模式中) (預設值：1)。

使用給定的參數啟用裝置模擬。

contents.disableDeviceEmulation()

停用由 webContents.enableDeviceEmulation 啟用的裝置模擬。

contents.sendInputEvent(inputEvent)

• inputEvent MouseInputEvent | MouseWheelInputEvent | KeyboardInputEvent

將輸入 event 傳送至頁面。注意： 包含內容的 BrowserWindow 需要聚焦，sendInputEvent() 才能運作。

contents.beginFrameSubscription([onlyDirty ,]callback)

• onlyDirty boolean (選用) - 預設值為 false。
• callback Function
  • image NativeImage
  • dirtyRect Rectangle

開始訂閱呈現事件和擷取的影格，當有呈現事件時，將使用 callback(image, dirtyRect) 呼叫 callback。

image 是 NativeImage 的執行個體，用於儲存擷取的影格。

dirtyRect 是一個具有 x, y, width, height 屬性的物件，用於描述頁面重新繪製的部分。如果 onlyDirty 設定為 true，則 image 將僅包含重新繪製的區域。onlyDirty 預設為 false。

contents.endFrameSubscription()

結束訂閱影格呈現事件。

contents.startDrag(item)

• item 物件
  • file 字串 - 要拖曳的檔案路徑。
  • files 字串陣列 (選用) - 要拖曳的檔案路徑。(files 將覆寫 file 欄位)
  • icon NativeImage | 字串 - 在 macOS 上，圖片必須為非空白。

將 item 設定為目前拖放操作的拖曳項目，file 是要拖曳檔案的絕對路徑，而 icon 是拖曳時在游標下方顯示的圖片。

contents.savePage(fullPath, saveType)

• fullPath 字串 - 絕對檔案路徑。
• saveType 字串 - 指定儲存類型。
  • HTMLOnly - 僅儲存頁面的 HTML。
  • HTMLComplete - 儲存完整 HTML 頁面。
  • MHTML - 將完整 HTML 頁面儲存為 MHTML。

回傳 Promise<void> - 如果頁面已儲存，則解析。

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()

win.loadURL('https://github.com')

win.webContents.on('did-finish-load', async () => {
  win.webContents.savePage('/tmp/test.html', 'HTMLComplete').then(() => {
    console.log('Page was saved successfully.')
  }).catch(err => {
    console.log(err)
  })
})

contents.showDefinitionForSelection() macOS

顯示彈出式字典，搜尋頁面上選取的單字。

contents.isOffscreen()

回傳 boolean - 指示是否啟用離螢幕渲染。

contents.startPainting()

如果啟用離螢幕渲染且未繪製，則開始繪製。

contents.stopPainting()

如果啟用離螢幕渲染且正在繪製，則停止繪製。

contents.isPainting()

回傳 boolean - 如果啟用離螢幕渲染，則回傳目前是否正在繪製。

contents.setFrameRate(fps)

• fps 整數

如果啟用離螢幕渲染，則將影格速率設定為指定的數字。僅接受介於 1 到 240 之間的值。

contents.getFrameRate()

回傳 Integer - 如果啟用離螢幕渲染，則回傳目前的影格速率。

contents.invalidate()

排定此網頁內容所在視窗的完整重新繪製。

如果啟用離螢幕渲染，則使影格失效並透過 'paint' 事件產生新的影格。

contents.getWebRTCIPHandlingPolicy()

回傳 string - 回傳 WebRTC IP 處理原則。

contents.setWebRTCIPHandlingPolicy(policy)

• policy 字串 - 指定 WebRTC IP 處理原則。
  • default - 暴露使用者的公開和本機 IP。這是預設行為。當使用此原則時，WebRTC 有權列舉所有介面並將其繫結以探索公開介面。
  • default_public_interface_only - 暴露使用者的公開 IP，但不暴露使用者的本機 IP。當使用此原則時，WebRTC 應僅使用 http 使用的預設路由。這不會暴露任何本機位址。
  • default_public_and_private_interfaces - 暴露使用者的公開和本機 IP。當使用此原則時，WebRTC 應僅使用 http 使用的預設路由。這也會暴露相關聯的預設私有位址。預設路由是 OS 在多宿主端點上選擇的路由。
  • disable_non_proxied_udp - 不暴露公開或本機 IP。當使用此原則時，WebRTC 應僅使用 TCP 連接對等點或伺服器，除非 Proxy 伺服器支援 UDP。

設定 WebRTC IP 處理原則可讓您控制透過 WebRTC 暴露哪些 IP。如需更多詳細資訊，請參閱 BrowserLeaks。

contents.getWebRTCUDPPortRange()

回傳 Object

• min 整數 - WebRTC 應使用的最小 UDP 通訊埠號碼。
• max 整數 - WebRTC 應使用的最大 UDP 通訊埠號碼。

預設情況下，此值為 { min: 0, max: 0 }，這表示對 udp 通訊埠範圍沒有限制。

contents.setWebRTCUDPPortRange(udpPortRange)

• udpPortRange 物件
  • min 整數 - WebRTC 應使用的最小 UDP 通訊埠號碼。
  • max 整數 - WebRTC 應使用的最大 UDP 通訊埠號碼。

設定 WebRTC UDP 通訊埠範圍可讓您限制 WebRTC 使用的 udp 通訊埠範圍。預設情況下，通訊埠範圍不受限制。注意： 若要重設為不受限制的通訊埠範圍，此值應設定為 { min: 0, max: 0 }。

contents.getMediaSourceId(requestWebContents)

• requestWebContents WebContents - 將註冊 ID 的網頁內容。

回傳 string - WebContents 串流的識別碼。此識別碼可以與 navigator.mediaDevices.getUserMedia 搭配使用，並使用 tab 的 chromeMediaSource。此識別碼僅限於註冊它的網頁內容，且僅在 10 秒內有效。

contents.getOSProcessId()

回傳 Integer - 相關聯的渲染器程序的作業系統 pid。

contents.getProcessId()

回傳 Integer - 相關聯的渲染器的 Chromium 內部 pid。可以與框架特定導覽事件 (例如 did-frame-navigate) 傳遞的 frameProcessId 進行比較。

contents.takeHeapSnapshot(filePath)

• filePath 字串 - 輸出檔案的路徑。

回傳 Promise<void> - 指示是否已成功建立快照。

擷取 V8 堆積快照並將其儲存到 filePath。

contents.getBackgroundThrottling()

回傳 boolean - 當頁面進入背景時，此 WebContents 是否會節流動畫和計時器。這也會影響 Page Visibility API。

contents.setBackgroundThrottling(allowed)

歷史記錄

版本	變更
>=28.0.0	WebContents.backgroundThrottling 設定為 false 會影響主機 BrowserWindow 中的所有 WebContents。

• allowed boolean

控制當頁面進入背景時，此 WebContents 是否會節流動畫和計時器。這也會影響 Page Visibility API。

contents.getType()

回傳 string - webContent 的類型。可以是 backgroundPage、window、browserView、remote、webview 或 offscreen。

contents.setImageAnimationPolicy(policy)

• policy 字串 - 可以是 animate、animateOnce 或 noAnimation。

設定此 webContents 的圖片動畫原則。此原則僅影響新的圖片，目前正在動畫的現有圖片不受影響。這是 Chromium 中的已知限制，您可以使用 img.src = img.src 強制重新計算圖片動畫，這不會產生網路流量，但會更新動畫原則。

這對應於 Chromium 中的 animationPolicy 無障礙功能。

執行個體屬性

contents.ipc 唯讀

一個 IpcMain，其範圍僅限於從此 WebContents 傳送的 IPC 訊息。

使用 ipcRenderer.send、ipcRenderer.sendSync 或 ipcRenderer.postMessage 傳送的 IPC 訊息將依以下順序傳遞

1. contents.on('ipc-message')
2. contents.mainFrame.on(channel)
3. contents.ipc.on(channel)
4. ipcMain.on(channel)

使用 invoke 註冊的處理常式將依以下順序檢查。將呼叫第一個定義的處理常式，其餘的將被忽略。

1. contents.mainFrame.handle(channel)
2. contents.handle(channel)
3. ipcMain.handle(channel)

在 WebContents 上註冊的處理常式或事件監聽器將接收從任何框架 (包括子框架) 傳送的 IPC 訊息。在大多數情況下，只有主框架可以傳送 IPC 訊息。但是，如果啟用 nodeIntegrationInSubFrames 選項，子框架也可能傳送 IPC 訊息。在這種情況下，處理常式應檢查 IPC 事件的 senderFrame 屬性，以確保訊息來自預期的框架。或者，使用 WebFrameMain.ipc 介面直接在適當的框架上註冊處理常式。

contents.audioMuted

一個 boolean 屬性，用於判斷此頁面是否靜音。

contents.userAgent

一個 string 屬性，用於判斷此網頁的使用者代理程式。

contents.zoomLevel

一個 number 屬性，用於判斷此網頁內容的縮放層級。

原始大小為 0，而高於或低於 0 的每個增量分別表示放大或縮小 20%，達到原始大小的 300% 和 50% 的預設限制。此公式為 scale := 1.2 ^ level。

contents.zoomFactor

一個 number 屬性，決定此網頁內容的縮放比例。

縮放比例是縮放百分比除以 100，因此 300% = 3.0。

contents.frameRate

一個 Integer 屬性，設定網頁內容的影格率為指定的數字。僅接受介於 1 到 240 之間的值。

僅在啟用離螢幕渲染時適用。

contents.id 唯讀

一個 Integer，代表此 WebContents 的唯一 ID。每個 ID 在整個 Electron 應用程式的所有 WebContents 實例中都是唯一的。

contents.session 唯讀

此 webContents 使用的 Session。

contents.navigationHistory 唯讀

此 webContents 使用的 NavigationHistory。

contents.hostWebContents 唯讀

可能擁有此 WebContents 的 WebContents 實例。

contents.devToolsWebContents 唯讀

一個 WebContents | null 屬性，代表與給定 WebContents 相關聯的 DevTools WebContents。

注意： 使用者永遠不應儲存此物件，因為當 DevTools 關閉時，它可能會變成 null。

contents.debugger 唯讀

此 webContents 的 Debugger 實例。

contents.backgroundThrottling

歷史記錄

版本	變更
>=28.0.0	WebContents.backgroundThrottling 設定為 false 會影響主機 BrowserWindow 中的所有 WebContents。

一個 boolean 屬性，決定當頁面變成背景時，此 WebContents 是否會節流動畫和計時器。這也會影響 Page Visibility API。

contents.mainFrame 唯讀

一個 WebFrameMain 屬性，代表頁面框架階層的頂層框架。

contents.opener 唯讀

一個 WebFrameMain 屬性，代表開啟此 WebContents 的框架，無論是透過 open() 或導航至具有 target 屬性的連結。