类:WebRequest
类:WebRequest
¥Class: WebRequest
在请求生命周期的各个阶段拦截并修改请求的内容。
¥Intercept and modify the contents of a request at various stages of its lifetime.
进程:主进程
该类不是从 'electron'
模块导出的。它仅可用作 Electron API 中其他方法的返回值。
¥Process: Main
This class is not exported from the 'electron'
module. It is only available as a return value of other methods in the Electron API.
WebRequest
类的实例可以通过使用 Session
的 webRequest
属性来访问。
¥Instances of the WebRequest
class are accessed by using the webRequest
property of a Session
.
WebRequest
的方法接受可选的 filter
和 listener
。当 API 事件发生时,listener
将与 listener(details)
一起调用。details
对象描述请求。
¥The methods of WebRequest
accept an optional filter
and a listener
. The
listener
will be called with listener(details)
when the API's event has
happened. The details
object describes the request.
⚠️ 仅使用最后附加的 listener
。将 null
作为 listener
传递将取消订阅该事件。
¥⚠️ Only the last attached listener
will be used. Passing null
as listener
will unsubscribe from the event.
filter
对象有一个 urls
属性,它是一个 URL 模式数组,用于过滤掉与 URL 模式不匹配的请求。如果省略 filter
,则所有请求都将被匹配。
¥The filter
object has a urls
property which is an Array of URL
patterns that will be used to filter out the requests that do not match the URL
patterns. If the filter
is omitted then all requests will be matched.
对于某些事件,listener
与 callback
一起传递,当 listener
完成其工作时,应使用 response
对象调用 callback
。
¥For certain events the listener
is passed with a callback
, which should be
called with a response
object when listener
has done its work.
为请求添加 User-Agent
标头的示例:
¥An example of adding User-Agent
header for requests:
const { session } = require('electron')
// Modify the user agent for all requests to the following urls.
const filter = {
urls: ['https://*.github.com/*', '*://electron.github.io/*']
}
session.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {
details.requestHeaders['User-Agent'] = 'MyAgent'
callback({ requestHeaders: details.requestHeaders })
})
实例方法
¥Instance Methods
以下方法可用于 WebRequest
的实例:
¥The following methods are available on instances of WebRequest
:
webRequest.onBeforeRequest([filter, ]listener)
-
filter
网络请求过滤器(可选)¥
filter
WebRequestFilter (optional) -
listener
Function | null-
details
对象¥
details
Object-
id
整数¥
id
Integer -
url
字符串¥
url
string -
method
字符串¥
method
string -
webContentsId
整数(可选)¥
webContentsId
Integer (optional) -
webContents
网页内容(可选)¥
webContents
WebContents (optional) -
frame
WebFrameMain(可选)¥
frame
WebFrameMain (optional) -
resourceType
字符串 - 可以是mainFrame
、subFrame
、stylesheet
、script
、image
、font
、object
、xhr
、ping
、cspReport
、media
、webSocket
或other
。¥
resourceType
string - Can bemainFrame
,subFrame
,stylesheet
,script
,image
,font
,object
,xhr
,ping
,cspReport
,media
,webSocket
orother
. -
referrer
字符串¥
referrer
string -
timestamp
双倍的¥
timestamp
Double -
uploadData
UploadData[]
-
-
callback
函数¥
callback
Function-
response
对象¥
response
Object-
cancel
布尔值(可选)¥
cancel
boolean (optional) -
redirectURL
字符串(可选) - 原始请求无法发送或完成,而是重定向到给定的 URL。¥
redirectURL
string (optional) - The original request is prevented from being sent or completed and is instead redirected to the given URL.
-
-
-
当请求即将发生时,listener
将与 listener(details, callback)
一起调用。
¥The listener
will be called with listener(details, callback)
when a request
is about to occur.
uploadData
是 UploadData
对象的数组。
¥The uploadData
is an array of UploadData
objects.
必须使用 response
对象调用 callback
。
¥The callback
has to be called with an response
object.
有效 urls
的一些示例:
¥Some examples of valid urls
:
'http://foo:1234/'
'http://foo.com/'
'http://foo:1234/bar'
'*://*/*'
'*://example.com/*'
'*://example.com/foo/*'
'http://*.foo:1234/'
'file://foo:1234/bar'
'http://foo:*/'
'*://www.foo.com/'
webRequest.onBeforeSendHeaders([filter, ]listener)
-
filter
网络请求过滤器(可选)¥
filter
WebRequestFilter (optional) -
listener
Function | null-
details
对象¥
details
Object-
id
整数¥
id
Integer -
url
字符串¥
url
string -
method
字符串¥
method
string -
webContentsId
整数(可选)¥
webContentsId
Integer (optional) -
webContents
网页内容(可选)¥
webContents
WebContents (optional) -
frame
WebFrameMain(可选)¥
frame
WebFrameMain (optional) -
resourceType
字符串 - 可以是mainFrame
、subFrame
、stylesheet
、script
、image
、font
、object
、xhr
、ping
、cspReport
、media
、webSocket
或other
。¥
resourceType
string - Can bemainFrame
,subFrame
,stylesheet
,script
,image
,font
,object
,xhr
,ping
,cspReport
,media
,webSocket
orother
. -
referrer
字符串¥
referrer
string -
timestamp
双倍的¥
timestamp
Double -
uploadData
UploadData[](可选)¥
uploadData
UploadData[] (optional) -
requestHeaders
记录<字符串,字符串>¥
requestHeaders
Record<string, string>
-
-
callback
函数¥
callback
Function-
beforeSendResponse
对象¥
beforeSendResponse
Object-
cancel
布尔值(可选)¥
cancel
boolean (optional) -
requestHeaders
Record<string,字符串 | string[]>(可选) - 提供后,将使用这些标头发出请求。¥
requestHeaders
Record<string, string | string[]> (optional) - When provided, request will be made with these headers.
-
-
-
一旦请求标头可用,在发送 HTTP 请求之前,将使用 listener(details, callback)
调用 listener
。这可能发生在与服务器建立 TCP 连接之后、发送任何 http 数据之前。
¥The listener
will be called with listener(details, callback)
before sending
an HTTP request, once the request headers are available. This may occur after a
TCP connection is made to the server, but before any http data is sent.
必须使用 response
对象调用 callback
。
¥The callback
has to be called with a response
object.
webRequest.onSendHeaders([filter, ]listener)
-
filter
网络请求过滤器(可选)¥
filter
WebRequestFilter (optional) -
listener
Function | null-
details
对象¥
details
Object-
id
整数¥
id
Integer -
url
字符串¥
url
string -
method
字符串¥
method
string -
webContentsId
整数(可选)¥
webContentsId
Integer (optional) -
webContents
网页内容(可选)¥
webContents
WebContents (optional) -
frame
WebFrameMain(可选)¥
frame
WebFrameMain (optional) -
resourceType
字符串 - 可以是mainFrame
、subFrame
、stylesheet
、script
、image
、font
、object
、xhr
、ping
、cspReport
、media
、webSocket
或other
。¥
resourceType
string - Can bemainFrame
,subFrame
,stylesheet
,script
,image
,font
,object
,xhr
,ping
,cspReport
,media
,webSocket
orother
. -
referrer
字符串¥
referrer
string -
timestamp
双倍的¥
timestamp
Double -
requestHeaders
记录<字符串,字符串>¥
requestHeaders
Record<string, string>
-
-
在将请求发送到服务器之前,将使用 listener(details)
调用 listener
,在触发此监听器时可以看到先前 onBeforeSendHeaders
响应的修改。
¥The listener
will be called with listener(details)
just before a request is
going to be sent to the server, modifications of previous onBeforeSendHeaders
response are visible by the time this listener is fired.
webRequest.onHeadersReceived([filter, ]listener)
-
filter
网络请求过滤器(可选)¥
filter
WebRequestFilter (optional) -
listener
Function | null-
details
对象¥
details
Object-
id
整数¥
id
Integer -
url
字符串¥
url
string -
method
字符串¥
method
string -
webContentsId
整数(可选)¥
webContentsId
Integer (optional) -
webContents
网页内容(可选)¥
webContents
WebContents (optional) -
frame
WebFrameMain(可选)¥
frame
WebFrameMain (optional) -
resourceType
字符串 - 可以是mainFrame
、subFrame
、stylesheet
、script
、image
、font
、object
、xhr
、ping
、cspReport
、media
、webSocket
或other
。¥
resourceType
string - Can bemainFrame
,subFrame
,stylesheet
,script
,image
,font
,object
,xhr
,ping
,cspReport
,media
,webSocket
orother
. -
referrer
字符串¥
referrer
string -
timestamp
双倍的¥
timestamp
Double -
statusLine
字符串¥
statusLine
string -
statusCode
整数¥
statusCode
Integer -
responseHeaders
记录<字符串, string[]>(可选)¥
responseHeaders
Record<string, string[]> (optional)
-
-
callback
函数¥
callback
Function-
headersReceivedResponse
对象¥
headersReceivedResponse
Object-
cancel
布尔值(可选)¥
cancel
boolean (optional) -
responseHeaders
Record<string,字符串 | string[]>(可选) - 当提供时,假定服务器已使用这些标头进行响应。¥
responseHeaders
Record<string, string | string[]> (optional) - When provided, the server is assumed to have responded with these headers. -
statusLine
字符串(可选) - 当覆盖responseHeaders
以更改标头状态时应提供,否则将使用原始响应标头的状态。¥
statusLine
string (optional) - Should be provided when overridingresponseHeaders
to change header status otherwise original response header's status will be used.
-
-
-
当收到请求的 HTTP 响应标头时,将使用 listener(details, callback)
调用 listener
。
¥The listener
will be called with listener(details, callback)
when HTTP
response headers of a request have been received.
必须使用 response
对象调用 callback
。
¥The callback
has to be called with a response
object.
webRequest.onResponseStarted([filter, ]listener)
-
filter
网络请求过滤器(可选)¥
filter
WebRequestFilter (optional) -
listener
Function | null-
details
对象¥
details
Object-
id
整数¥
id
Integer -
url
字符串¥
url
string -
method
字符串¥
method
string -
webContentsId
整数(可选)¥
webContentsId
Integer (optional) -
webContents
网页内容(可选)¥
webContents
WebContents (optional) -
frame
WebFrameMain(可选)¥
frame
WebFrameMain (optional) -
resourceType
字符串 - 可以是mainFrame
、subFrame
、stylesheet
、script
、image
、font
、object
、xhr
、ping
、cspReport
、media
、webSocket
或other
。¥
resourceType
string - Can bemainFrame
,subFrame
,stylesheet
,script
,image
,font
,object
,xhr
,ping
,cspReport
,media
,webSocket
orother
. -
referrer
字符串¥
referrer
string -
timestamp
双倍的¥
timestamp
Double -
responseHeaders
记录<字符串, string[]>(可选)¥
responseHeaders
Record<string, string[]> (optional) -
fromCache
布尔值 - 指示是否从磁盘缓存中获取响应。¥
fromCache
boolean - Indicates whether the response was fetched from disk cache. -
statusCode
整数¥
statusCode
Integer -
statusLine
字符串¥
statusLine
string
-
-
当收到响应正文的第一个字节时,将使用 listener(details)
调用 listener
。对于 HTTP 请求,这意味着状态行和响应标头可用。
¥The listener
will be called with listener(details)
when first byte of the
response body is received. For HTTP requests, this means that the status line
and response headers are available.
webRequest.onBeforeRedirect([filter, ]listener)
-
filter
网络请求过滤器(可选)¥
filter
WebRequestFilter (optional) -
listener
Function | null-
details
对象¥
details
Object-
id
整数¥
id
Integer -
url
字符串¥
url
string -
method
字符串¥
method
string -
webContentsId
整数(可选)¥
webContentsId
Integer (optional) -
webContents
网页内容(可选)¥
webContents
WebContents (optional) -
frame
WebFrameMain(可选)¥
frame
WebFrameMain (optional) -
resourceType
字符串 - 可以是mainFrame
、subFrame
、stylesheet
、script
、image
、font
、object
、xhr
、ping
、cspReport
、media
、webSocket
或other
。¥
resourceType
string - Can bemainFrame
,subFrame
,stylesheet
,script
,image
,font
,object
,xhr
,ping
,cspReport
,media
,webSocket
orother
. -
referrer
字符串¥
referrer
string -
timestamp
双倍的¥
timestamp
Double -
redirectURL
字符串¥
redirectURL
string -
statusCode
整数¥
statusCode
Integer -
statusLine
字符串¥
statusLine
string -
ip
字符串(可选) - 请求实际发送到的服务器 IP 地址。¥
ip
string (optional) - The server IP address that the request was actually sent to. -
fromCache
布尔值¥
fromCache
boolean -
responseHeaders
记录<字符串, string[]>(可选)¥
responseHeaders
Record<string, string[]> (optional)
-
-
当服务器发起的重定向即将发生时,listener
将与 listener(details)
一起调用。
¥The listener
will be called with listener(details)
when a server initiated
redirect is about to occur.
webRequest.onCompleted([filter, ]listener)
-
filter
网络请求过滤器(可选)¥
filter
WebRequestFilter (optional) -
listener
Function | null-
details
对象¥
details
Object-
id
整数¥
id
Integer -
url
字符串¥
url
string -
method
字符串¥
method
string -
webContentsId
整数(可选)¥
webContentsId
Integer (optional) -
webContents
网页内容(可选)¥
webContents
WebContents (optional) -
frame
WebFrameMain(可选)¥
frame
WebFrameMain (optional) -
resourceType
字符串 - 可以是mainFrame
、subFrame
、stylesheet
、script
、image
、font
、object
、xhr
、ping
、cspReport
、media
、webSocket
或other
。¥
resourceType
string - Can bemainFrame
,subFrame
,stylesheet
,script
,image
,font
,object
,xhr
,ping
,cspReport
,media
,webSocket
orother
. -
referrer
字符串¥
referrer
string -
timestamp
双倍的¥
timestamp
Double -
responseHeaders
记录<字符串, string[]>(可选)¥
responseHeaders
Record<string, string[]> (optional) -
fromCache
布尔值¥
fromCache
boolean -
statusCode
整数¥
statusCode
Integer -
statusLine
字符串¥
statusLine
string -
error
字符串¥
error
string
-
-
当请求完成时,listener
将与 listener(details)
一起调用。
¥The listener
will be called with listener(details)
when a request is
completed.
webRequest.onErrorOccurred([filter, ]listener)
-
filter
网络请求过滤器(可选)¥
filter
WebRequestFilter (optional) -
listener
Function | null-
details
对象¥
details
Object-
id
整数¥
id
Integer -
url
字符串¥
url
string -
method
字符串¥
method
string -
webContentsId
整数(可选)¥
webContentsId
Integer (optional) -
webContents
网页内容(可选)¥
webContents
WebContents (optional) -
frame
WebFrameMain(可选)¥
frame
WebFrameMain (optional) -
resourceType
字符串 - 可以是mainFrame
、subFrame
、stylesheet
、script
、image
、font
、object
、xhr
、ping
、cspReport
、media
、webSocket
或other
。¥
resourceType
string - Can bemainFrame
,subFrame
,stylesheet
,script
,image
,font
,object
,xhr
,ping
,cspReport
,media
,webSocket
orother
. -
referrer
字符串¥
referrer
string -
timestamp
双倍的¥
timestamp
Double -
fromCache
布尔值¥
fromCache
boolean -
error
字符串 - 错误描述。¥
error
string - The error description.
-
-
当发生错误时,listener
将与 listener(details)
一起调用。
¥The listener
will be called with listener(details)
when an error occurs.