WebEngine 快速纳米浏览器
使用WebEngineView QML 类型实现的网络浏览器。
Quick Nano Browser演示了如何使用 QML 来开发一个小型网络浏览器应用程序。 Qt WebEngine QML types来开发一个小型网络浏览器应用程序，它由一个带有标题栏、工具栏、标签视图和状态栏的浏览器窗口组成。网络内容在标签视图中的网络引擎视图中加载。如果出现证书错误，系统会在消息对话框中提示用户采取相应措施。状态栏会弹出，显示悬停链接的 URL。
网页可请求以全屏模式显示。用户可以使用工具栏按钮允许全屏模式。用户可以使用键盘快捷键离开全屏模式。其他工具栏按钮还可以在浏览器历史记录中前后移动、重新加载标签页内容，以及打开设置菜单以启用以下功能：JavaScript、插件、全屏模式、关闭记录、HTTP 磁盘缓存、自动加载图像和忽略证书错误。
运行示例
要从 Qt Creator，打开Welcome 模式，并从Examples 中选择示例。更多信息，请参阅Qt Creator: 教程：构建并运行。
创建浏览器主窗口
浏览器主窗口加载后，会使用默认配置文件创建一个空标签页。每个标签页都是填充主窗口的网络引擎视图。
我们在BrowserWindow.qml文件中使用ApplicationWindow 类型创建主窗口：
ApplicationWindow { id: browserWindow property QtObject applicationRoot property Item currentWebView: tabBar.currentIndex < tabBar.count ? tabLayout.children[tabBar.currentIndex] : null ... width: 1300 height: 900 visible: true title: currentWebView && currentWebView.title
我们使用TabBar Qt Quick 控件创建一个锚定到窗口顶部的标签栏，并创建一个新的空标签页：
TabBar { id: tabBar anchors.top: parent.top anchors.left: parent.left anchors.right: parent.right Component.onCompleted: createTab(defaultProfilePrototype.instance()) function createTab(profile, focusOnNewTab = true, url = undefined) { var webview = tabComponent.createObject(tabLayout, {profile: profile}); var newTabButton = tabButtonComponent.createObject(tabBar, {tabTitle: Qt.binding(function () { return webview.title; })}); tabBar.addItem(newTabButton); if (focusOnNewTab) { tabBar.setCurrentIndex(tabBar.count - 1); }
该标签页包含一个加载网页内容的网络引擎视图：
Component { id: tabComponent WebEngineView { id: webEngineView focus: true onLinkHovered: function(hoveredUrl) { if (hoveredUrl == "") hideStatusText.start(); else { statusText.text = hoveredUrl; statusBubble.visible = true; hideStatusText.stop(); } } states: [ State { name: "FullScreen" PropertyChanges { target: tabBar visible: false height: 0 } PropertyChanges { target: navigationBar visible: false } } ] settings.localContentCanAccessRemoteUrls: true settings.localContentCanAccessFileUrls: false settings.autoLoadImages: appSettings.autoLoadImages settings.javascriptEnabled: appSettings.javaScriptEnabled settings.errorPageEnabled: appSettings.errorPageEnabled settings.pluginsEnabled: appSettings.pluginsEnabled settings.fullScreenSupportEnabled: appSettings.fullScreenSupportEnabled settings.autoLoadIconsForPage: appSettings.autoLoadIconsForPage settings.touchIconsEnabled: appSettings.touchIconsEnabled settings.webRTCPublicInterfacesOnly: appSettings.webRTCPublicInterfacesOnly settings.pdfViewerEnabled: appSettings.pdfViewerEnabled settings.imageAnimationPolicy: appSettings.imageAnimationPolicy settings.screenCaptureEnabled: true onCertificateError: function(error) { if (!error.isMainFrame) { error.rejectCertificate(); return; } error.defer(); sslDialog.enqueue(error); } onNewWindowRequested: function(request) { if (!request.userInitiated) console.warn("Blocked a popup window."); else if (request.destination === WebEngineNewWindowRequest.InNewTab) { var tab = tabBar.createTab(currentWebView.profile, true, request.requestedUrl); tab.acceptAsNewWindow(request); } else if (request.destination === WebEngineNewWindowRequest.InNewBackgroundTab) { var backgroundTab = tabBar.createTab(currentWebView.profile, false); backgroundTab.acceptAsNewWindow(request); } else if (request.destination === WebEngineNewWindowRequest.InNewDialog) { var dialog = applicationRoot.createDialog(currentWebView.profile); dialog.currentWebView.acceptAsNewWindow(request); } else { var window = applicationRoot.createWindow(currentWebView.profile); window.currentWebView.acceptAsNewWindow(request); } } onFullScreenRequested: function(request) { if (request.toggleOn) { webEngineView.state = "FullScreen"; browserWindow.previousVisibility = browserWindow.visibility; browserWindow.showFullScreen(); fullScreenNotification.show(); } else { webEngineView.state = ""; browserWindow.visibility = browserWindow.previousVisibility; fullScreenNotification.hide(); } request.accept(); } onRegisterProtocolHandlerRequested: function(request) { console.log("accepting registerProtocolHandler request for " + request.scheme + " from " + request.origin); request.accept(); } onDesktopMediaRequested: function(request) { // select the primary screen request.selectScreen(request.screensModel.index(0, 0)); } onRenderProcessTerminated: function(terminationStatus, exitCode) { var status = ""; switch (terminationStatus) { case WebEngineView.NormalTerminationStatus: status = "(normal exit)"; break; case WebEngineView.AbnormalTerminationStatus: status = "(abnormal exit)"; break; case WebEngineView.CrashedTerminationStatus: status = "(crashed)"; break; case WebEngineView.KilledTerminationStatus: status = "(killed)"; break; } print("Render process exited with code " + exitCode + " " + status); reloadTimer.running = true; } onSelectClientCertificate: function(selection) { selection.certificates[0].select(); } onFindTextFinished: function(result) { if (!findBar.visible) findBar.visible = true; findBar.numberOfMatches = result.numberOfMatches; findBar.activeMatch = result.activeMatch; } onLoadingChanged: function(loadRequest) { if (loadRequest.status == WebEngineView.LoadStartedStatus) findBar.reset(); } onPermissionRequested: function(permission) { permissionDialog.permission = permission; permissionDialog.visible = true; } onWebAuthUxRequested: function(request) { webAuthDialog.init(request); } Timer { id: reloadTimer interval: 0 running: false repeat: false onTriggered: currentWebView.reload() } } }
我们使用Action 类型创建新标签页：
Action { shortcut: StandardKey.AddTab onTriggered: { tabBar.createTab(tabBar.count != 0 ? currentWebView.profile : defaultProfilePrototype.instance()); addressBar.forceActiveFocus(); addressBar.selectAll(); }
我们在ToolBar 中使用TextField Qt Quick 控件创建地址栏，显示当前 URL 和用户可输入的其他 URL：
menuBar: ToolBar { id: navigationBar RowLayout { anchors.fill: parent ... TextField { id: addressBar ... focus: true Layout.fillWidth: true Binding on text { when: currentWebView value: currentWebView.url } onAccepted: currentWebView.url = Utils.fromUserInput(text) selectByMouse: true }
处理证书错误
如果出现证书错误，我们会检查它是来自主框架，还是来自页面内的资源。资源错误会自动触发证书拒绝，因为用户没有足够的上下文来做出决定。对于所有其他情况，我们会调用defer() QML 方法暂停 URL 请求，等待用户输入：
onCertificateError: function(error) { if (!error.isMainFrame) { error.rejectCertificate(); return; } error.defer(); sslDialog.enqueue(error); }
我们使用对话框类型来提示用户继续或取消加载网页。如果用户选择Yes ，我们会调用acceptCertificate() 方法继续加载 URL 中的内容。如果用户选择No ，我们会调用rejectCertificate() 方法拒绝请求并停止从 URL 加载内容：
Dialog { id: sslDialog anchors.centerIn: parent contentWidth: Math.max(mainTextForSSLDialog.width, detailedTextForSSLDialog.width) contentHeight: mainTextForSSLDialog.height + detailedTextForSSLDialog.height property var certErrors: [] // fixme: icon! // icon: StandardIcon.Warning standardButtons: Dialog.No | Dialog.Yes title: "Server's certificate not trusted" contentItem: Item { Label { id: mainTextForSSLDialog text: "Do you wish to continue?" } Text { id: detailedTextForSSLDialog anchors.top: mainTextForSSLDialog.bottom text: "If you wish so, you may continue with an unverified certificate.\n" + "Accepting an unverified certificate means\n" + "you may not be connected with the host you tried to connect to.\n" + "Do you wish to override the security check and continue?" } } onAccepted: { certErrors.shift().acceptCertificate(); presentError(); } onRejected: reject() function reject(){ certErrors.shift().rejectCertificate(); presentError(); } function enqueue(error){ certErrors.push(error); presentError(); } function presentError(){ visible = certErrors.length > 0 } }
处理权限请求
我们使用onPermissionRequested() 信号处理器来处理访问特定功能或设备的请求。permission 参数是一个 WebEnginePermission 类型的对象，可用于处理传入的请求。我们将临时存储该对象，因为我们需要用它来构建对话框的信息：
onPermissionRequested: function(permission) { permissionDialog.permission = permission; permissionDialog.visible = true; }
我们将显示一个对话框，要求用户授予或拒绝访问权限。自定义questionForFeature() JavaScript 函数会生成一个有关请求的人可读问题。如果用户选择Yes ，我们将调用grant() 方法；如果用户选择No ，我们将调用deny() 方法。
Dialog { id: permissionDialog anchors.centerIn: parent width: Math.min(browserWindow.width, browserWindow.height) / 3 * 2 contentWidth: mainTextForPermissionDialog.width contentHeight: mainTextForPermissionDialog.height standardButtons: Dialog.No | Dialog.Yes title: "Permission Request" property var permission; contentItem: Item { Label { id: mainTextForPermissionDialog } } onAccepted: permission.grant() onRejected: permission.deny() onVisibleChanged: { if (visible) { mainTextForPermissionDialog.text = questionForPermissionType(); width = contentWidth + 20; } } function questionForPermissionType() { var question = "Allow " + permission.origin + " to " switch (permission.permissionType) { case WebEnginePermission.PermissionType.Geolocation: question += "access your location information?"; break; case WebEnginePermission.PermissionType.MediaAudioCapture: question += "access your microphone?"; break; case WebEnginePermission.PermissionType.MediaVideoCapture: question += "access your webcam?"; break; case WebEnginePermission.PermissionType.MediaAudioVideoCapture: question += "access your microphone and webcam?"; break; case WebEnginePermission.PermissionType.MouseLock: question += "lock your mouse cursor?"; break; case WebEnginePermission.PermissionType.DesktopVideoCapture: question += "capture video of your desktop?"; break; case WebEnginePermission.PermissionType.DesktopAudioVideoCapture: question += "capture audio and video of your desktop?"; break; case WebEnginePermission.PermissionType.Notifications: question += "show notification on your desktop?"; break; case WebEnginePermission.PermissionType.ClipboardReadWrite: question += "read from and write to your clipboard?"; break; case WebEnginePermission.PermissionType.LocalFontsAccess: question += "access the fonts stored on your machine?"; break; default: question += "access unknown or unsupported permission type [" + permission.permissionType + "] ?"; break; } return question; } }
进入和离开全屏模式
我们在工具栏上的设置菜单中创建了一个允许全屏模式的菜单项。此外，我们还创建了一个通过键盘快捷键离开全屏模式的操作。我们调用accept() 方法来接受全屏请求。该方法将isFullScreen 属性设置为等于toggleOn 属性。
onFullScreenRequested: function(request) { if (request.toggleOn) { webEngineView.state = "FullScreen"; browserWindow.previousVisibility = browserWindow.visibility; browserWindow.showFullScreen(); fullScreenNotification.show(); } else { webEngineView.state = ""; browserWindow.visibility = browserWindow.previousVisibility; fullScreenNotification.hide(); } request.accept(); }
进入全屏模式后，我们将使用在FullScreenNotification.qml 中创建的 FullScreenNotification 自定义类型显示通知。
我们在设置菜单中使用Action 类型创建一个快捷方式，以便按下 escape 键离开全屏模式：
Settings { id : appSettings property alias fullScreenSupportEnabled: fullScreenSupportEnabled.checked property alias autoLoadIconsForPage: autoLoadIconsForPage.checked property alias touchIconsEnabled: touchIconsEnabled.checked property alias webRTCPublicInterfacesOnly : webRTCPublicInterfacesOnly.checked property alias devToolsEnabled: devToolsEnabled.checked property alias pdfViewerEnabled: pdfViewerEnabled.checked property int imageAnimationPolicy: WebEngineSettings.ImageAnimationPolicy.Allow } Action { shortcut: "Escape" onTriggered: { if (currentWebView.state == "FullScreen") { browserWindow.visibility = browserWindow.previousVisibility; fullScreenNotification.hide(); currentWebView.triggerWebAction(WebEngineView.ExitFullScreen); } if (findBar.visible) findBar.visible = false; } }
处理 WebAuth/FIDO 用户体验请求
我们使用onWebAuthUxRequested() 信号处理器来处理 WebAuth/FIDO UX 请求。request 参数是WebEngineWebAuthUxRequest 的一个实例，其中包含用户体验请求详情和处理请求所需的 API。我们用它来构建 WebAuthUX 对话框并启动用户体验请求流。
onWebAuthUxRequested: function(request) { webAuthDialog.init(request); }
WebEngineWebAuthUxRequest 对象会定期发出stateChanged 信号，通知潜在观察者当前的 WebAuth 用户体验状态。观察者会相应地更新 WebAuth 对话框。我们使用 onStateChanged() 信号处理程序来处理状态更改请求。有关如何处理这些信号的示例，请参见WebAuthDialog.qml 。
Connections { id: webauthConnection ignoreUnknownSignals: true function onStateChanged(state) { webAuthDialog.setupUI(state); } function init(request) { pinLabel.visible = false; pinEdit.visible = false; confirmPinLabel.visible = false; confirmPinEdit.visible = false; selectAccountModel.clear(); webAuthDialog.authrequest = request; webauthConnection.target = request; setupUI(webAuthDialog.authrequest.state) webAuthDialog.visible = true; pinEntryError.visible = false; }
MacOS 的签名要求
在 macOS 上运行Quick Nano 浏览器时，要允许网站访问位置、摄像头和麦克风，应用程序需要签名。这在构建时会自动完成，但你需要为构建环境设置一个有效的签名身份。
文件和属性
本示例使用 Tango 图标库中的图标：
| Tango 图标库 | 公共领域 |
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
