跳至主要內容

<webview> 標籤

警告​

Electron 的 webview 標籤基於 Chromium 的 webview，該標籤正在進行重大的架構變更。這會影響 webview 的穩定性，包括渲染、導覽和事件路由。目前我們建議不要使用 webview 標籤，並考慮替代方案，例如 iframe、WebContentsView，或完全避免嵌入內容的架構。

啟用​

預設情況下，webview 標籤在 Electron >= 5 中是停用的。您需要在建構 BrowserWindow 時，設定 webviewTag webPreferences 選項來啟用標籤。如需更多資訊，請參閱 BrowserWindow 建構函式文件。

概述​

在隔離的框架和程序中顯示外部網頁內容。

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

使用 webview 標籤在您的 Electron 應用程式中嵌入「訪客」內容 (例如網頁)。訪客內容包含在 webview 容器內。您應用程式中的嵌入式頁面會控制訪客內容的配置和渲染方式。

與 iframe 不同，webview 在與您的應用程式不同的程序中執行。它沒有與您的網頁相同的權限，並且您的應用程式與嵌入內容之間的所有互動都將是非同步的。這可確保您的應用程式免受嵌入內容的侵害。注意：從主機頁面呼叫 webview 的大多數方法都需要同步呼叫到主程序。

範例​

若要將網頁嵌入您的應用程式中，請將 webview 標籤新增至您應用程式的嵌入器頁面 (這是將顯示訪客內容的應用程式頁面)。在其最簡單的形式中，webview 標籤包含網頁的 src 和控制 webview 容器外觀的 css 樣式

<webview id="foo" src="https://www.github.com/" style="display:inline-flex; width:640px; height:480px"></webview>

如果您想要以任何方式控制訪客內容，您可以編寫 JavaScript 來監聽 webview 事件，並使用 webview 方法回應這些事件。以下是具有兩個事件監聽器的範例程式碼：一個監聽網頁開始載入，另一個監聽網頁停止載入，並在載入期間顯示「載入中...」訊息

<script>
  onload = () => {
    const webview = document.querySelector('webview')
    const indicator = document.querySelector('.indicator')

    const loadstart = () => {
      indicator.innerText = 'loading...'
    }

    const loadstop = () => {
      indicator.innerText = ''
    }

    webview.addEventListener('did-start-loading', loadstart)
    webview.addEventListener('did-stop-loading', loadstop)
  }
</script>

內部實作​

在底層，webview 使用 跨程序 iframe (OOPIF) 實作。webview 標籤本質上是一個自訂元素，使用 shadow DOM 包裝其中的 iframe 元素。

因此，webview 的行為與跨網域 iframe 非常相似，例如

  • 當點擊進入 webview 時，頁面焦點將從嵌入器框架移至 webview。
  • 您無法將鍵盤、滑鼠和捲軸事件監聽器新增至 webview。
  • 嵌入器框架和 webview 之間的所有反應都是非同步的。

CSS 樣式注意事項​

請注意，webview 標籤的樣式在內部使用 display:flex;，以確保子 iframe 元素在使用傳統和 flexbox 版面配置時，會填滿其 webview 容器的完整高度和寬度。除非為內嵌版面配置指定 display:inline-flex;，否則請勿覆寫預設的 display:flex; CSS 屬性。

標籤屬性​

webview 標籤具有以下屬性

src​

<webview src="https://www.github.com/"></webview>

代表可見 URL 的 string。寫入此屬性會啟動最上層導覽。

將 src 指派給自己的值將重新載入目前的頁面。

src 屬性也可以接受資料 URL，例如 data:text/plain,Hello, world!。

nodeintegration​

<webview src="https://www.google.com/" nodeintegration></webview>

boolean。當存在此屬性時，webview 中的訪客頁面將具有節點整合，並且可以使用像 require 和 process 的節點 API 來存取低階系統資源。預設情況下，在訪客頁面中停用節點整合。

nodeintegrationinsubframes​

<webview src="https://www.google.com/" nodeintegrationinsubframes></webview>

boolean，用於在子框架中啟用 NodeJS 支援的實驗性選項，例如 webview 內的 iframe。您的所有預載都會針對每個 iframe 載入，您可以使用 process.isMainFrame 來判斷您是否在主要框架中。預設情況下，在訪客頁面中停用此選項。

plugins​

<webview src="https://www.github.com/" plugins></webview>

boolean。當存在此屬性時，webview 中的訪客頁面將能夠使用瀏覽器外掛程式。預設情況下，停用外掛程式。

preload​

<!-- from a file -->
<webview src="https://www.github.com/" preload="./test.js"></webview>
<!-- or if you want to load from an asar archive -->
<webview src="https://www.github.com/" preload="./app.asar/test.js"></webview>

指定腳本的 string，該腳本將在訪客頁面中執行其他腳本之前載入。腳本的 URL 通訊協定必須是 file: (即使使用 asar: 封存)，因為它將由 Node 的 require 在底層載入，而後者將 asar: 封存視為虛擬目錄。

當訪客頁面沒有節點整合時，此腳本仍然可以存取所有節點 API，但是在此腳本完成執行後，由節點注入的全域物件將被刪除。

httpreferrer​

<webview src="https://www.github.com/" httpreferrer="https://example.com/"></webview>

設定訪客頁面的參照 URL 的 string。

useragent​

<webview src="https://www.github.com/" useragent="Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; AS; rv:11.0) like Gecko"></webview>

在瀏覽至頁面之前，設定訪客頁面使用者代理程式的 string。載入頁面後，使用 setUserAgent 方法來變更使用者代理程式。

disablewebsecurity​

<webview src="https://www.github.com/" disablewebsecurity></webview>

boolean。當存在此屬性時，訪客頁面將停用網路安全性。預設情況下，啟用網路安全性。

此值只能在第一次導覽之前修改。

partition​

<webview src="https://github.com" partition="persist:github"></webview>
<webview src="https://electron.dev.org.tw" partition="electron"></webview>

設定頁面使用的會話的 string。如果 partition 以 persist: 開頭，則頁面將使用可供應用程式中所有具有相同 partition 的頁面使用的永久會話。如果沒有 persist: 前綴，則頁面將使用記憶體中的會話。透過指派相同的 partition，多個頁面可以共用相同的會話。如果未設定 partition，則將使用應用程式的預設會話。

由於活動渲染器程序的會話無法變更，因此此值只能在第一次導覽之前修改。後續嘗試修改值將會失敗並出現 DOM 例外。

allowpopups​

<webview src="https://www.github.com/" allowpopups></webview>

boolean。當存在此屬性時，將允許訪客頁面開啟新視窗。預設情況下，停用快顯視窗。

webpreferences​

<webview src="https://github.com" webpreferences="allowRunningInsecureContent, javascript=no"></webview>

一個 string 字串，是由逗號分隔的字串列表，用於指定要在 webview 上設定的網頁偏好設定。 完整的支援偏好設定字串列表可以在 BrowserWindow 中找到。

此字串的格式與 window.open 中的 features 字串格式相同。 單獨一個名稱會被賦予 true 的布林值。 可以透過包含 = 符號，後面跟著值，將偏好設定設為其他值。 特殊值 yes 和 1 會被解釋為 true，而 no 和 0 則會被解釋為 false。

enableblinkfeatures​

<webview src="https://www.github.com/" enableblinkfeatures="PreciseMemoryInfo, CSSVariables"></webview>

一個 string 字串，是由逗號 , 分隔的字串列表，用於指定要啟用的 blink 功能。 完整的支援功能字串列表可以在 RuntimeEnabledFeatures.json5 檔案中找到。

disableblinkfeatures​

<webview src="https://www.github.com/" disableblinkfeatures="PreciseMemoryInfo, CSSVariables"></webview>

一個 string 字串，是由逗號 , 分隔的字串列表，用於指定要停用的 blink 功能。 完整的支援功能字串列表可以在 RuntimeEnabledFeatures.json5 檔案中找到。

方法​

webview 標籤具有以下方法

注意： 必須先載入 webview 元素才能使用這些方法。

範例

const webview = document.querySelector('webview')
webview.addEventListener('dom-ready', () => {
  webview.openDevTools()
})

<webview>.loadURL(url[, options])​

  • url URL
  • options 物件（可選）
    • httpReferrer (string | Referrer)（可選）- HTTP 參照網址。
    • userAgent 字串（可選）- 發出請求的使用者代理程式。
    • extraHeaders 字串（可選）- 以 "\n" 分隔的額外標頭。
    • postData (UploadRawData | UploadFile)[]（可選）
    • baseURLForDataURL 字串（可選）- 要由 data 網址載入的檔案的基礎網址（帶有尾部的路徑分隔符號）。 只有當指定的 url 是 data 網址且需要載入其他檔案時，才需要此設定。

傳回 Promise<void> - 當頁面載入完成時（請參閱 did-finish-load），promise 會 resolve，如果頁面載入失敗（請參閱 did-fail-load），則會 reject。

在 webview 中載入 url，url 必須包含協定前綴，例如 http:// 或 file://。

<webview>.downloadURL(url[, options])​

  • url 字串
  • options 物件（可選）
    • headers Record<string, string>（可選）- HTTP 請求標頭。

啟動下載位於 url 的資源，而不會導航。

<webview>.getURL()​

傳回 string - 客戶頁面的網址。

<webview>.getTitle()​

傳回 string - 客戶頁面的標題。

<webview>.isLoading()​

傳回 boolean - 客戶頁面是否仍在載入資源。

<webview>.isLoadingMainFrame()​

傳回 boolean - 主要框架（而不僅僅是其中的 iframe 或框架）是否仍在載入。

<webview>.isWaitingForResponse()​

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

<webview>.stop()​

停止任何擱置中的導航。

<webview>.reload()​

重新載入客戶頁面。

<webview>.reloadIgnoringCache()​

重新載入客戶頁面並忽略快取。

<webview>.canGoBack()​

傳回 boolean - 客戶頁面是否可以返回。

<webview>.canGoForward()​

傳回 boolean - 客戶頁面是否可以前進。

<webview>.canGoToOffset(offset)​

  • offset 整數

傳回 boolean - 客戶頁面是否可以前往 offset。

<webview>.clearHistory()​

清除導航歷史記錄。

<webview>.goBack()​

讓客戶頁面返回。

<webview>.goForward()​

讓客戶頁面前進。

<webview>.goToIndex(index)​

  • index 整數

導航到指定的絕對索引。

<webview>.goToOffset(offset)​

  • offset 整數

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

<webview>.isCrashed()​

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

<webview>.setUserAgent(userAgent)​

  • userAgent 字串

覆寫客戶頁面的使用者代理程式。

<webview>.getUserAgent()​

傳回 string - 客戶頁面的使用者代理程式。

<webview>.insertCSS(css)​

  • css 字串

傳回 Promise<string> - 一個 promise，會解析為插入 CSS 的金鑰，之後可以使用 <webview>.removeInsertedCSS(key) 移除 CSS。

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

<webview>.removeInsertedCSS(key)​

  • key 字串

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

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

<webview>.executeJavaScript(code[, userGesture])​

  • code 字串
  • userGesture 布林值（可選）- 預設值為 false。

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

在頁面中評估 code。 如果設定了 userGesture，它將會在頁面中建立使用者手勢內容。 像是 requestFullScreen 這類需要使用者動作的 HTML API，可以利用此選項進行自動化。

<webview>.openDevTools()​

為客戶頁面開啟 DevTools 視窗。

<webview>.closeDevTools()​

關閉客戶頁面的 DevTools 視窗。

<webview>.isDevToolsOpened()​

傳回 boolean - 客戶頁面是否已附加 DevTools 視窗。

<webview>.isDevToolsFocused()​

傳回 boolean - 客戶頁面的 DevTools 視窗是否已聚焦。

<webview>.inspectElement(x, y)​

  • x 整數
  • y 整數

開始檢查客戶頁面上位置 (x, y) 的元素。

<webview>.inspectSharedWorker()​

為客戶頁面中存在的共享 worker 內容開啟 DevTools。

<webview>.inspectServiceWorker()​

為客戶頁面中存在的服務 worker 內容開啟 DevTools。

<webview>.setAudioMuted(muted)​

  • muted boolean

設定訪客頁面靜音。

<webview>.isAudioMuted()​

返回 boolean - 訪客頁面是否已靜音。

<webview>.isCurrentlyAudible()​

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

<webview>.undo()​

在頁面中執行編輯指令 undo。

<webview>.redo()​

在頁面中執行編輯指令 redo。

<webview>.cut()​

在頁面中執行編輯指令 cut。

<webview>.copy()​

在頁面中執行編輯指令 copy。

<webview>.centerSelection()​

將頁面中目前選取的文字置中。

<webview>.paste()​

在頁面中執行編輯指令 paste。

<webview>.pasteAndMatchStyle()​

在頁面中執行編輯指令 pasteAndMatchStyle。

<webview>.delete()​

在頁面中執行編輯指令 delete。

<webview>.selectAll()​

在頁面中執行編輯指令 selectAll。

<webview>.unselect()​

在頁面中執行編輯指令 unselect。

<webview>.scrollToTop()​

捲動至目前 <webview> 的頂部。

<webview>.scrollToBottom()​

捲動至目前 <webview> 的底部。

<webview>.adjustSelection(options)​

  • options 物件
    • start 數字 (選用) - 要偏移目前選取範圍起始索引的數量。
    • end 數字 (選用) - 要偏移目前選取範圍結束索引的數量。

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

請參閱 webContents.adjustSelection 以取得範例。

<webview>.replace(text)​

  • text 字串

在頁面中執行編輯指令 replace。

<webview>.replaceMisspelling(text)​

  • text 字串

在頁面中執行編輯指令 replaceMisspelling。

<webview>.insertText(text)​

  • text 字串

返回 Promise<void>

將 text 插入到焦點元素中。

<webview>.findInPage(text[, options])​

  • text 字串 - 要搜尋的內容，不得為空。
  • options 物件（可選）
    • forward 布林值 (選用) - 是否向前或向後搜尋，預設為 true。
    • findNext 布林值 (選用) - 是否要以這個請求開始新的文字搜尋會期。初始請求應為 true，後續請求應為 false。預設為 false。
    • matchCase 布林值 (選用) - 搜尋是否應區分大小寫，預設為 false。

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

開始請求以尋找網頁中 text 的所有匹配項。可以透過訂閱 found-in-page 事件來獲得請求的結果。

<webview>.stopFindInPage(action)​

  • action 字串 - 指定結束 <webview>.findInPage 請求時要採取的動作。
    • clearSelection - 清除選取範圍。
    • keepSelection - 將選取範圍轉換為正常選取範圍。
    • activateSelection - 焦點和點擊選取節點。

使用提供的 action 停止 webview 的任何 findInPage 請求。

<webview>.print([options])​

  • options 物件（可選）
    • silent 布林值 (選用) - 不詢問使用者列印設定。預設為 false。
    • printBackground 布林值 (選用) - 列印網頁的背景顏色和影像。預設為 false。
    • deviceName 字串 (選用) - 設定要使用的印表機裝置名稱。必須是系統定義的名稱，而不是「友善」名稱，例如「Brother_QL_820NWB」，而不是「Brother QL-820NWB」。
    • color 布林值 (選用) - 設定要列印的網頁是否為彩色或灰階。預設為 true。
    • margins 物件 (選用)
      • marginType 字串 (選用) - 可以是 default、none、printableArea 或 custom。如果選擇 custom，您還需要指定 top、bottom、left 和 right。
      • top 數字 (選用) - 列印網頁的頂邊距，以像素為單位。
      • bottom 數字 (選用) - 列印網頁的底邊距，以像素為單位。
      • left 數字 (選用) - 列印網頁的左邊距，以像素為單位。
      • right 數字 (選用) - 列印網頁的右邊距，以像素為單位。
    • landscape 布林值 (選用) - 網頁是否應以橫向模式列印。預設為 false。
    • scaleFactor 數字 (選用) - 網頁的縮放比例。
    • pagesPerSheet 數字 (選用) - 每張紙要列印的頁數。
    • collate 布林值 (選用) - 是否應整理網頁。
    • copies 數字 (選用) - 要列印的網頁副本數。
    • pageRanges 物件[] (選用) - 要列印的頁面範圍。
      • from 數字 - 要列印的第一頁的索引 (以 0 為起始)。
      • to 數字 - 要列印的最後一頁的索引 (含) (以 0 為起始)。
    • duplexMode 字串 (選用) - 設定列印網頁的雙面列印模式。可以是 simplex、shortEdge 或 longEdge。
    • dpi Record<string, number> (選用)
      • horizontal 數字 (選用) - 水平 dpi。
      • vertical 數字 (選用) - 垂直 dpi。
    • header 字串 (選用) - 要列印為頁首的字串。
    • footer 字串 (選用) - 要列印為頁尾的字串。
    • pageSize 字串 | Size (選用) - 指定列印文件的大小。可以是 A3、A4、A5、Legal、Letter、Tabloid 或包含以微米為單位的 height 的物件。

返回 Promise<void>

列印 webview 的網頁。與 webContents.print([options]) 相同。

<webview>.printToPDF(options)​

  • options 物件
    • landscape 布林值 (選用) - 紙張方向。true 表示橫向，false 表示直向。預設為 false。
    • displayHeaderFooter 布林值 (選用) - 是否顯示頁首和頁尾。預設為 false。
    • printBackground 布林值 (選用) - 是否列印背景圖形。預設為 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 布林值 (選用) - 是否偏好由 css 定義的頁面大小。預設為 false，在此情況下，內容將會縮放以符合紙張大小。
    • generateTaggedPDF 布林值 (選用) 實驗性 - 是否產生帶有標籤 (可存取) 的 PDF。預設為 false。由於此屬性是實驗性的，因此產生的 PDF 可能無法完全符合 PDF/UA 和 WCAG 標準。
    • generateDocumentOutline 布林值 (選用) 實驗性 - 是否從內容標頭產生 PDF 文件大綱。預設為 false。

返回 Promise<Uint8Array> - 使用產生的 PDF 資料解析。

將 webview 的網頁列印為 PDF，與 webContents.printToPDF(options) 相同。

<webview>.capturePage([rect])​

  • rect Rectangle（可選） - 要擷取頁面的區域。

返回 Promise<NativeImage> - 使用 NativeImage 解析。

擷取 rect 內頁面的快照。省略 rect 將會擷取整個可見頁面。

<webview>.send(channel, ...args)​

  • channel 字串
  • ...args any[]

返回 Promise<void>

透過 channel 發送非同步訊息到渲染進程，您也可以發送任意的參數。渲染進程可以透過 ipcRenderer 模組監聽 channel 事件來處理訊息。

請參閱 webContents.send 以取得範例。

<webview>.sendToFrame(frameId, channel, ...args)​

  • frameId [number, number] - [processId, frameId]
  • channel 字串
  • ...args any[]

返回 Promise<void>

透過 channel 發送非同步訊息到渲染進程，您也可以發送任意的參數。渲染進程可以透過 ipcRenderer 模組監聽 channel 事件來處理訊息。

請參閱 webContents.sendToFrame 以取得範例。

<webview>.sendInputEvent(event)​

返回 Promise<void>

發送輸入 event 到頁面。

請參閱 webContents.sendInputEvent 以取得 event 物件的詳細描述。

<webview>.setZoomFactor(factor)​

  • factor 數值 - 縮放比例。

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

<webview>.setZoomLevel(level)​

  • level 數值 - 縮放級別。

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

注意：在 Chromium 層級，縮放策略是同源的，這表示特定網域的縮放級別會傳播到所有具有相同網域的視窗實例。區分視窗 URL 將會使縮放功能在每個視窗上運作。

<webview>.getZoomFactor()​

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

<webview>.getZoomLevel()​

返回 number - 目前的縮放級別。

<webview>.setVisualZoomLevelLimits(minimumLevel, maximumLevel)​

  • minimumLevel 數值
  • maximumLevel 數值

返回 Promise<void>

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

<webview>.showDefinitionForSelection() macOS​

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

<webview>.getWebContentsId()​

返回 number - 這個 webview 的 WebContents ID。

DOM 事件​

以下 DOM 事件可用於 webview 標籤

事件：'load-commit'​

返回

  • url 字串
  • isMainFrame 布林值

在載入提交時觸發。這包含目前文件內的導覽以及子框架文件層級的載入，但不包含非同步資源載入。

事件：'did-finish-load'​

導覽完成時觸發，也就是說，標籤的微調器將停止旋轉，並且會分派 onload 事件。

事件：'did-fail-load'​

返回

  • errorCode 整數
  • errorDescription 字串
  • validatedURL 字串
  • isMainFrame 布林值

此事件類似於 did-finish-load，但在載入失敗或取消時觸發，例如調用 window.stop()。

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

返回

  • isMainFrame 布林值

當框架完成導覽時觸發。

事件：'did-start-loading'​

對應於標籤微調器開始旋轉的時間點。

事件：'did-stop-loading'​

對應於標籤微調器停止旋轉的時間點。

事件：'did-attach'​

在附加到嵌入器 WebContents 時觸發。

事件：'dom-ready'​

在指定框架中的文件載入時觸發。

事件：'page-title-updated'​

返回

  • title 字串
  • explicitSet 布林值

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

事件：'page-favicon-updated'​

返回

  • favicons 字串[] - URL 陣列。

當頁面接收到圖示 URL 時觸發。

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

當頁面進入由 HTML API 觸發的全螢幕模式時觸發。

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

當頁面離開由 HTML API 觸發的全螢幕模式時觸發。

事件：'console-message'​

返回

  • level 整數 - 記錄級別，從 0 到 3。依序符合 verbose、info、warning 和 error。
  • message 字串 - 實際的控制台訊息
  • line 整數 - 觸發此控制台訊息的來源行號
  • sourceId 字串

當訪客視窗記錄控制台訊息時觸發。

以下範例程式碼會將所有記錄訊息轉發到嵌入器的控制台，而不考慮記錄級別或其他屬性。

const webview = document.querySelector('webview')
webview.addEventListener('console-message', (e) => {
  console.log('Guest page logged a message:', e.message)
})

事件：'found-in-page'​

返回

  • result 物件
    • requestId 整數
    • activeMatchOrdinal 整數 - 使用中比對的位置。
    • matches 整數 - 比對數量。
    • selectionArea Rectangle - 第一個比對區域的座標。
    • finalUpdate 布林值

當 webview.findInPage 請求的結果可用時觸發。

const webview = document.querySelector('webview')
webview.addEventListener('found-in-page', (e) => {
  webview.stopFindInPage('keepSelection')
})

const requestId = webview.findInPage('test')
console.log(requestId)

事件：'will-navigate'​

返回

  • url 字串

當使用者或頁面想要開始導覽時發出。當 window.location 物件變更或使用者點擊頁面中的連結時，可能會發生這種情況。

當使用 API（例如 <webview>.loadURL 和 <webview>.back）以程式方式啟動導覽時，不會發出此事件。

在頁面內導覽期間（例如點擊錨點連結或更新 window.location.hash）也不會發出此事件。請使用 did-navigate-in-page 事件來達到此目的。

呼叫 event.preventDefault() **不會**產生任何效果。

事件：'will-frame-navigate'​

返回

  • url 字串
  • isMainFrame 布林值
  • frameProcessId 整數
  • frameRoutingId 整數

當使用者或頁面想要開始導覽 <webview> 或其中嵌入的任何框架時發出。當 window.location 物件變更或使用者點擊頁面中的連結時，可能會發生這種情況。

當使用 API（例如 <webview>.loadURL 和 <webview>.back）以程式方式啟動導覽時，不會發出此事件。

在頁面內導覽期間（例如點擊錨點連結或更新 window.location.hash）也不會發出此事件。請使用 did-navigate-in-page 事件來達到此目的。

呼叫 event.preventDefault() **不會**產生任何效果。

事件：'did-start-navigation'​

返回

  • url 字串
  • isInPlace 布林值
  • isMainFrame 布林值
  • frameProcessId 整數
  • frameRoutingId 整數

當任何框架（包含主要框架）開始導覽時發出。對於頁面內導覽，isInPlace 將為 true。

事件：'did-redirect-navigation'​

返回

  • url 字串
  • isInPlace 布林值
  • isMainFrame 布林值
  • frameProcessId 整數
  • frameRoutingId 整數

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

事件：'did-navigate'​

返回

  • url 字串

當導航完成時發出。

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

事件：'did-frame-navigate'​

返回

  • url 字串
  • httpResponseCode 整數 - 非 HTTP 導航為 -1
  • httpStatusText 字串 - 非 HTTP 導航為空字串
  • isMainFrame 布林值
  • frameProcessId 整數
  • frameRoutingId 整數

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

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

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

返回

  • isMainFrame 布林值
  • url 字串

當發生頁內導航時發出。

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

事件：'close'​

當訪客頁面嘗試關閉自身時觸發。

以下範例程式碼會在訪客嘗試關閉自身時，將 webview 導航到 about:blank。

const webview = document.querySelector('webview')
webview.addEventListener('close', () => {
  webview.src = 'about:blank'
})

事件：'ipc-message'​

返回

  • frameId [數字, 數字] - [processId, frameId] 配對。
  • channel 字串
  • args 任何[]

當訪客頁面已將非同步訊息傳送至嵌入器頁面時觸發。

透過 sendToHost 方法和 ipc-message 事件，您可以在訪客頁面和嵌入器頁面之間進行通訊。

// In embedder page.
const webview = document.querySelector('webview')
webview.addEventListener('ipc-message', (event) => {
  console.log(event.channel)
  // Prints "pong"
})
webview.send('ping')
// In guest page.
const { ipcRenderer } = require('electron')
ipcRenderer.on('ping', () => {
  ipcRenderer.sendToHost('pong')
})

事件：'render-process-gone'​

返回

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

事件：'plugin-crashed'​

返回

  • name 字串
  • version 字串

當外掛程式處理程序崩潰時觸發。

事件：'destroyed'​

當 WebContents 被銷毀時觸發。

事件：'media-started-playing'​

當媒體開始播放時發出。

事件：'media-paused'​

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

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

返回

  • themeColor 字串

當頁面的主題顏色變更時發出。這通常是因為遇到 meta 標籤。

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

事件：'update-target-url'​

返回

  • url 字串

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

事件：'devtools-open-url'​

返回

  • url 字串 - 已點擊或選取的連結 URL。

當在 DevTools 中點擊連結或在其上下文選單中選取「在新分頁中開啟」時發出。

事件：'devtools-search-query'​

返回

  • event 事件
  • query 字串 - 要查詢的文字。

當在其上下文選單中選取文字的「搜尋」時發出。

事件：'devtools-opened'​

當 DevTools 開啟時發出。

事件：'devtools-closed'​

當 DevTools 關閉時發出。

事件：'devtools-focused'​

當 DevTools 取得焦點/開啟時發出。

事件：'context-menu'​

返回

  • params 物件
    • x 整數 - x 坐標。
    • y 整數 - y 坐標。
    • linkURL 字串 - 包圍叫用上下文選單之節點的連結 URL。
    • linkText 字串 - 與連結關聯的文字。如果連結內容是影像，則可能為空字串。
    • pageURL 字串 - 叫用上下文選單的最上層頁面 URL。
    • frameURL 字串 - 叫用上下文選單的子框架 URL。
    • srcURL 字串 - 叫用上下文選單之元素的來源 URL。具有來源 URL 的元素為影像、音訊和視訊。
    • mediaType 字串 - 叫用上下文選單之節點的類型。可以是 none、image、audio、video、canvas、file 或 plugin。
    • hasImageContents 布林值 - 上下文選單是否在具有非空內容的影像上叫用。
    • isEditable 布林值 - 上下文是否可編輯。
    • selectionText 字串 - 叫用上下文選單之選取範圍的文字。
    • titleText 字串 - 叫用上下文選單之選取範圍的標題文字。
    • altText 字串 - 叫用上下文選單之選取範圍的替代文字。
    • suggestedFilename 字串 - 當透過上下文選單的「另存連結為」選項儲存檔案時，建議使用的檔案名稱。
    • selectionRect 矩形 - 代表文件中選取範圍坐標的矩形。
    • selectionStartOffset 數字 - 選取文字的起始位置。
    • referrerPolicy 參照位址 - 叫用選單之框架的參照位址原則。
    • misspelledWord 字串 - 游標下方的拼寫錯誤單字（如果有的話）。
    • dictionarySuggestions 字串[] - 建議使用者顯示以取代 misspelledWord 的單字陣列。僅在有拼寫錯誤單字且已啟用拼寫檢查時可用。
    • frameCharset 字串 - 叫用選單之框架的字元編碼。
    • formControlType 字串 - 叫用上下文選單的來源。可能的值包括 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 布林值 - 如果上下文可編輯，則拼寫檢查是否啟用。
    • menuSourceType 字串 - 叫用上下文選單的輸入來源。可以是 none、mouse、keyboard、touch、touchMenu、longPress、longTap、touchHandle、stylus、adjustSelection 或 adjustSelectionReset。
    • mediaFlags 物件 - 叫用上下文選單的媒體元素旗標。
      • inError 布林值 - 媒體元素是否已崩潰。
      • isPaused 布林值 - 媒體元素是否已暫停。
      • isMuted 布林值 - 媒體元素是否已靜音。
      • hasAudio 布林值 - 媒體元素是否有音訊。
      • isLooping 布林值 - 媒體元素是否正在循環播放。
      • isControlsVisible 布林值 - 媒體元素的控制項是否可見。
      • canToggleControls 布林值 - 媒體元素的控制項是否可切換。
      • canPrint 布林值 - 媒體元素是否可列印。
      • canSave 布林值 - 媒體元素是否可下載。
      • canShowPictureInPicture 布林值 - 媒體元素是否可顯示子母畫面。
      • isShowingPictureInPicture 布林值 - 媒體元素目前是否正在顯示子母畫面。
      • canRotate 布林值 - 媒體元素是否可旋轉。
      • canLoop 布林值 - 媒體元素是否可循環播放。
    • editFlags 物件 - 這些旗標表示渲染器是否認為可以執行對應的動作。
      • canUndo 布林值 - 渲染器是否認為可以復原。
      • canRedo 布林值 - 渲染器是否認為可以重做。
      • canCut 布林值 - 渲染器是否認為可以剪下。
      • canCopy 布林值 - 渲染器是否認為可以複製。
      • canPaste 布林值 - 渲染器是否認為可以貼上。
      • canDelete 布林值 - 渲染器是否認為可以刪除。
      • canSelectAll 布林值 - 渲染器是否認為可以全選。
      • canEditRichly 布林值 - 渲染器是否認為可以豐富地編輯文字。

當有新的上下文選單需要處理時發出。