介绍
安装
指南
- Engine
- Profile
- Browser
- BrowserView
- 导航
- 内容
- 上下文菜单
- DOM
- JavaScript
- 弹出窗口
- 对话框
- 下载
- Chrome 扩展程序
- 网络
- 缓存
- Cookies
- 代理
- 身份验证
- 权限
- 插件
- 打印
- 密码
- 用户数据配置文件
- 信用卡
- 媒体
- 缩放
- 拼写检查器
- 部署
- Chromium
故障排除
- 日志记录
- 常见异常
- 应用程序不终止
- 视频不播放
- 无法登录 Google 账号
- 用户数据未被储存
- 配色方案
- 启动失败
- Windows 启动缓慢
- 无响应的 .NET 应用程序
- Chromium 进程意外终止
- 意外行为
- Windows 7/8/8.1 停止支持
迁移
导航
本指南描述了导航事件并展示了如何加载 URL 和文件、过滤导航请求、处理导航历史等。
加载 URL
要导航到由 URL 标识的资源,请使用以下方法之一:
INavigation.LoadUrl(string url)
INavigation.LoadUrl(LoadUrlParameters parameters)
下面的示例展示了如何使用 INavigation.LoadUrl(string)
方法导航到 https://www.google.com
:
INavigation navigation = browser.Navigation;
navigation.LoadUrl("https://www.google.com");
Dim navigation As INavigation = browser.Navigation
navigation.LoadUrl("https://www.google.com")
同步加载 URL
LoadUrl
方法向给定资源发送一个导航请求并返回一个Task<NavigationResult>
,该任务可用于等待资源完全加载完成。
如果您需要阻塞当前线程执行直到资源完全加载,请使用 Task.Wait()
方法:
navigation.LoadUrl("https://www.google.com").Wait();
navigation.LoadUrl("https://www.google.com").Wait()
该方法会阻塞当前线程执行,直到资源的主框架被完全加载或直到达到默认的 100 秒超时时间为止。
如果导航失败,返回的 Task<NavigationResult>
将完成,其Task.Result
属性将返回有关可能的导航失败的详细信息。
如果资源在给定的时间内未加载,则会抛出 TimeoutException
异常。
当主框架至少发生以下事件之一,即 FrameLoadFinished
, NavigationFinished
, 或 FrameLoadFailed
时,网页被视为已完全加载。
使用 POST 加载 URL
要通过 URL 加载网页并发送 POST 数据,请使用 INavigation.LoadUrl(LoadUrlParameters)
方法。 下面的代码演示了如何使用额外的标头加载 URL 和发送不同格式的 POST 数据。
你可以以 key=value
的格式向网络服务器发送网路表单数据:
navigation.LoadUrl(new LoadUrlParameters("https://postman-echo.com/post")
{
UploadData = new FormData(new Dictionary<string, string>()
{
{"key", "value"}
})
});
navigation.LoadUrl(New LoadUrlParameters("https://postman-echo.com/post") With {
.UploadData = New FormData(New Dictionary(Of String, String)() From {
{"key", "value"}
})
})
您需要为每种请求类型明确指定 “Content-Type” 标头。
如果您想发送一些纯文本,请添加额外的标头来指示网络服务器它是纯文本:
navigation.LoadUrl(new LoadUrlParameters("https://postman-echo.com/post")
{
UploadData = new TextData("Some text..."),
HttpHeaders = new[]
{
new HttpHeader("Content-Type", "text/plain")
}
});
navigation.LoadUrl(New LoadUrlParameters("https://postman-echo.com/post") With {
.UploadData = New TextData("Some text..."),
.HttpHeaders =
{
New HttpHeader("Content-Type", "text/plain")
}
})
您可以发送任何类型的数据。 为此,请指定其 Content-Type
。 请参阅下面发送 JSON 数据的代码示例:
navigation.LoadUrl(new LoadUrlParameters("https://postman-echo.com/post")
{
PostData = "{\"title\":\"Hello\"}",
HttpHeaders = new[]
{
new HttpHeader("Content-Type", "application/json")
}
});
navigation.LoadUrl(New LoadUrlParameters("https://postman-echo.com/post") With {
.PostData = "{""title"":""Hello""}",
.HttpHeaders =
{
New HttpHeader("Content-Type", "application/json")
}
})
加载文件
您可以使用相同的方法从本地文件系统加载 HTML 文件,方法是提供 HTML 文件的绝对路径而非 URL。 请参阅以下代码示例:
navigation.LoadUrl(Path.GetFullPath("index.html"));
navigation.LoadUrl(Path.GetFullPath("index.html"))
加载 HTML
要将 HTML 加载到浏览器中,您可以创建一个 data
: 编码的 URI,然后使用常规的 LoadUrl
调用加载它。 下面是一个例子:
var html = "<html><head></head><body><h1>Html Encoded in URL!</h1></body></html>";
var base64EncodedHtml = Convert.ToBase64String(Encoding.UTF8.GetBytes(html));
browser.Navigation.LoadUrl("data:text/html;base64," + base64EncodedHtml).Wait();
Dim html = "<html><head></head><body><h1>Html Encoded in URL!</h1></body></html>"
Dim base64EncodedHtml = Convert.ToBase64String(Encoding.UTF8.GetBytes(html))
browser.Navigation.LoadUrl("data:text/html;base64," & base64EncodedHtml).Wait()
Chromium 将数据编码 URI 的最大长度限制为 2MB。
但是,使用此方法时无法设置基本 URL。
另一种可能的方法是使用处理程序注册一个 Scheme
并拦截相应的请求以提供 HTML。 请参阅相应的文章.
重载
有几种重新加载当前加载的网页的选项:
- 使用 HTTP 缓存重新加载:
navigation.Reload();
navigation.Reload()
- 忽略 HTTP 缓存重新加载:
navigation.ReloadIgnoringCache();
navigation.ReloadIgnoringCache()
- 使用 HTTP 缓存重新加载并检查是否重新发布:
navigation.ReloadAndCheckForRepost();
navigation.ReloadAndCheckForRepost()
- 忽略 HTTP 缓存重新加载并检查是否重新发布:
navigation.ReloadIgnoringCacheAndCheckForRepost();
navigation.ReloadIgnoringCacheAndCheckForRepost()
停止
使用 INavigation.Stop()
方法取消任何挂起的导航或下载操作,并停止任何动态页面元素,例如背景声音和动画。 请参阅以下代码示例:
navigation.Stop();
navigation.Stop()
后退 & 前进
DotNetBrowser 允许使用导航后退-前进历史列表。
当您创建一个 IBrowser 实例时,它默认导航到 about:blank 网页。 在导航后退-前进列表中始终有一个条目。
要加载后退-前进列表中的前一个位置,请使用以下方法:
if (navigation.CanGoBack()) {
navigation.GoBack();
}
If navigation.CanGoBack() Then
navigation.GoBack()
End If
要加载后退-前进列表中的下一个位置,请使用以下方法:
if (navigation.CanGoForward()) {
navigation.GoForward();
}
If navigation.CanGoForward() Then
navigation.GoForward()
End If
要导航到后退-前进列表中特定索引处的条目,请使用以下方法:
if (index >=0 && index < navigation.EntryCount) {
navigation.GoTo(index);
}
If index >=0 AndAlso index < navigation.EntryCount Then
navigation.GoTo(index)
End If
要翻阅后退-前进列表并获得每个导航条目的详细信息,请使用以下方法。
for (int index = 0; index < navigation.EntryCount; index++) {
INavigationEntry navigationEntry = navigation.EntryAt(index);
Console.WriteLine("URL: " + navigationEntry.Url);
Console.WriteLine("Title: " + navigationEntry.Title);
}
For index As Integer = 0 To navigation.EntryCount - 1
Dim navigationEntry As INavigationEntry = navigation.EntryAt(index)
Console.WriteLine("URL: " & navigationEntry.Url)
Console.WriteLine("Title: " & navigationEntry.Title)
Next
要通过删除条目来修改后退-前进列表,请使用以下方法。
// 返回后退/前进列表中的条目数。
int entryCount = navigation.EntryCount;
// 删除索引处的导航条目。
for (int i = entryCount - 2; i >= 0; i--) {
bool success = navigation.RemoveEntryAt(i);
Console.WriteLine("Navigation entry at index " + i +
" has been removed successfully? " + success);
}
' 返回后退/前进列表中的条目数。
Dim entryCount As Integer = navigation.EntryCount
' 删除索引处的导航条目。
For i As Integer = entryCount - 2 To 0 Step -1
Dim success As Boolean = navigation.RemoveEntryAt(i)
Console.WriteLine("Navigation entry at index " & i &
" has been removed successfully? " & success)
Next
过度滚动历史导航
在硬件加速渲染模式下,DotNetBrowser 允许通过在带有触摸屏的设备上向左/向右滑动来后退/前进导航。 默认情况下,过度滚动导航是禁用的。 要启用它,请使用 IBrowserSettings.OverscrollHistoryNavigationEnabled
属性:
browser.Settings.OverscrollHistoryNavigationEnabled = true;
browser.Settings.OverscrollHistoryNavigationEnabled = True
过滤 URL
您可以决定是否忽略特定 URL 的导航请求。
请参阅下面的代码示例,其中展示了如何忽略所有以 https://www.google
开头的 URL 的导航请求:
navigation.StartNavigationHandler =
new Handler<StartNavigationParameters, StartNavigationResponse>((p) =>
{
// 忽略以 "https://www.google" 开头的 URL
// 导航请求。
if (p.Url.StartsWith("https://www.google"))
{
return StartNavigationResponse.Ignore();
}
return StartNavigationResponse.Start();
});
navigation.StartNavigationHandler =
New Handler(Of StartNavigationParameters, StartNavigationResponse)(Function(p)
' 忽略以 "https://www.google" 开头的 URL
' 导航请求。
If p.Url.StartsWith("https://www.google") Then
Return StartNavigationResponse.Ignore()
End If
Return StartNavigationResponse.Start()
End Function)
过滤资源
SendUrlRequestHandler “处理程序可让您确定 HTML、图像、JavaScript 或 CSS 文件、favicon 等资源是否已加载。 默认情况下,加载所有资源。 要修改默认行为,请在您决定取消或加载哪些资源的地方注册您自己的处理程序实现。
请参阅下面的代码示例,了解如何抑制所有图像:
engine.Network.SendUrlRequestHandler =
new Handler<SendUrlRequestParameters, SendUrlRequestResponse>(p =>
{
if (p.UrlRequest.ResourceType == ResourceType.Image)
{
return SendUrlRequestResponse.Cancel();
}
return SendUrlRequestResponse.Continue();
});
engine.Network.SendUrlRequestHandler =
New Handler(Of SendUrlRequestParameters, SendUrlRequestResponse)(Function(p)
If p.UrlRequest.ResourceType = ResourceType.Image Then
Return SendUrlRequestResponse.Cancel()
End If
Return SendUrlRequestResponse.Continue()
End Function)
导航事件
加载网页是一个复杂的过程,其中会触发导航事件。 下图展示了加载网页时可能触发的导航事件的顺序:
加载开始
要在内容加载开始时获得通知,请使用 LoadStarted
事件。 请参阅以下代码示例:
navigation.LoadStarted += (s, e) => {};
AddHandler navigation.LoadStarted, Sub(s, e)
End Sub
该事件对应于标签页的加载指示器开始旋转的时刻。
加载完成
要在内容加载完成时获得通知,请使用 LoadFinished
事件。 例如:
navigation.LoadFinished += (s, e) => {};
AddHandler navigation.LoadFinished, Sub(s, e)
End Sub
该事件对应于标签页的加载指示器停止旋转的时刻。
加载进度
LoadProgressChanged
事件允许获取有关加载进度的通知:
navigation.LoadProgressChanged += (s, e) =>
{
// 表示网页加载进度的值。
double progress = e.Progress;
};
AddHandler navigation.LoadProgressChanged, Sub(s, e)
' 表示网页加载进度的值。
Dim progress As Double = e.Progress
End Sub
导航开始
要在导航开始时获得通知,请使用 NavigationStarted
事件。 请参阅以下代码示例:
navigation.NavigationStarted += (s, e) =>
{
string url = e.Url;
// 指示导航是否
// 将在同一文档范围内执行。
bool isSameDocument = e.IsSameDocument;
};
AddHandler navigation.NavigationStarted, Sub(s, e)
Dim url As String = e.Url
' 只是导航是否
' 将在同一文档范围内执行。
Dim isSameDocument As Boolean = e.IsSameDocument
End Sub
导航停止
要在导航停止时获得通知,请使用 NavigationStopped
事件。 请参阅以下代码示例:
navigation.NavigationStopped += (s, e) => {};
AddHandler navigation.NavigationStopped, Sub(s, e)
End Sub
当使用 Navigation.stop()
方法停止导航时会触发此事件。
导航重定向
要在导航重定向到新 URL 时获得通知,请使用 NavigationRedirected
事件。 请参阅以下代码示例:
navigation.NavigationRedirected += (s, e) => {
// 导航重定向 URL。
string url = e.Url;
};
AddHandler navigation.NavigationRedirected, Sub(s, e)
' 导航重定向 URL。
Dim url As String = e.Url
End Sub
导航完成
要在导航完成时获得通知,请使用 NavigationFinished
事件。 请参阅以下代码示例:
navigation.NavigationFinished += (s, e) => {
string url = e.Url;
IFrame frame = e.Frame;
bool hasCommitted = e.HasCommitted;
bool isSameDocument = e.IsSameDocument;
bool isErrorPage = e.IsErrorPage;
if (isErrorPage) {
NetError error = e.ErrorCode;
}
};
AddHandler navigation.NavigationFinished, Sub(s, e)
Dim url As String = e.Url
Dim frame As IFrame = e.Frame
Dim hasCommitted As Boolean = e.HasCommitted
Dim isSameDocument As Boolean = e.IsSameDocument
Dim isErrorPage As Boolean = e.IsErrorPage
If isErrorPage Then
Dim [error] As NetError = e.ErrorCode
End If
End Sub
当导航被提交、中止或被新导航替换时,将触发此事件。 要知道导航是否已提交,请使用 NavigationFinishedEventArgs.HasCommitted
。 要了解导航是否导致错误页面,请使用 NavigationFinishedEventArgs.IsErrorPage
。
如果由于导航已提交而调用该事件,则文档加载仍将继续进行。
该事件由 same-document(在同一文档范围内)的导航触发,比如片段导航或 window.history.pushState()
/window.history.replaceState()
,这些导航不会导致文档的更改。 使用 NavigationFinishedEventArgs.IsSameDocument
属性来检查是否是同一文档导航。
框架加载完成
要在 IFrame
中的内容加载完成时获得通知,请使用 FrameLoadFinished
事件。 请参阅以下代码示例:
navigation.FrameLoadFinished += (s, e) =>
{
string url = e.ValidatedUrl;
IFrame frame = e.Frame;
};
AddHandler navigation.FrameLoadFinished, Sub(s, e)
Dim url As String = e.ValidatedUrl
Dim frame As IFrame = e.Frame
End Sub
此事件对应于 Frame
中的内容已完全加载的时刻。
框架加载失败
要在 Frame
中的内容加载因某种原因失败时获得通知,请使用 FrameLoadFailed
事件。
请参阅以下代码示例:
navigation.FrameLoadFailed += (s, e) =>
{
string url = e.ValidatedUrl;
NetError error = e.ErrorCode;
};
AddHandler navigation.FrameLoadFailed, Sub(s, e)
Dim url As String = e.ValidatedUrl
Dim [error] As NetError = e.ErrorCode
End Sub
框架文件加载完成
要在 Frame
中的文档加载完成时获得通知,请使用FrameDocumentLoadFinished
事件。
请参阅以下代码示例:
navigation.FrameDocumentLoadFinished += (s, e) =>
{
IFrame frame = e.Frame;
};
AddHandler navigation.FrameDocumentLoadFinished, Sub(s, e)
Dim frame As IFrame = e.Frame
End Sub
此时,延迟脚本被执行,标记为 document_end 的内容脚本被注入到框架中。
自定义错误页面
要覆盖标准 Chromium 错误页面,请使用 ShowHttpErrorPageHandler
和 ShowNetErrorPageHandler
处理程序,分别处理 HTTP 错误(如 404 Not Found)或网络错误(如 ERR_CONNECTION_REFUSED)。 请参阅以下示例:
HTTP 错误页面
browser.Navigation.ShowHttpErrorPageHandler =
new Handler<ShowHttpErrorPageParameters, ShowHttpErrorPageResponse>(arg =>
{
string url = arg.Url;
HttpStatusCode httpStatusCode = arg.HttpStatus;
return ShowHttpErrorPageResponse.Show("HTTP Error web page:" + httpStatusCode);
});
browser.Navigation.ShowHttpErrorPageHandler =
New Handler(Of ShowHttpErrorPageParameters, ShowHttpErrorPageResponse)(Function(arg)
Dim url As String = arg.Url
Dim httpStatusCode As HttpStatusCode = arg.HttpStatus
Return ShowHttpErrorPageResponse.Show("HTTP Error web page:" & httpStatusCode)
End Function)
网络错误页面
browser.Navigation.ShowNetErrorPageHandler =
new Handler<ShowNetErrorPageParameters, ShowNetErrorPageResponse>(arg =>
{
return ShowNetErrorPageResponse.Show("Network error web page");
});
browser.Navigation.ShowNetErrorPageHandler =
New Handler(Of ShowNetErrorPageParameters, ShowNetErrorPageResponse)(Function(arg)
Return ShowNetErrorPageResponse.Show("Network error web page")
End Function)
服务器提供的自定义错误页面不会被这些处理程序拦截,并且无法使用此功能进行覆盖。 上述处理程序仅在覆盖 Chromium 默认错误页面时调用。