Qt WebEngine 기능

Qt WebEngine 는 다음 기능을 지원합니다:

• 오디오 및 비디오 코덱
• 크롬 개발 도구
• 클라이언트 인증서
• 사용자 지정 스키마
• 드래그 앤 드롭
• 파비콘
• 전체 화면
• 하드웨어 가속
• HTML5 DRM
• HTML5 지리적 위치
• HTML5 웹소켓
• HTTP/2 프로토콜
• 로컬 스토리지
• 기본 대화 상자
• PDF 파일 보기
• 페이지 수명 주기 API
• PDF로 인쇄
• 푸시 알림
• 맞춤법 검사기
• Touch
• 소스 보기
• 웹 알림
• 웹엔진 드라이버
• WebGL
• WebRTC

오디오 및 비디오 코덱

Qt WebEngine 은 H.264 및 MPEG layer-3(MP3)와 같은 필수 독점 오디오 및 비디오 코덱이 활성화된 경우에만 MPEG-4 Part 14(MP4) 파일 형식을 지원합니다. 전용 코덱은 Qt를 구성할 때 configure 도구에 다음 옵션을 전달하여 활성화할 수 있습니다:

-webengine-proprietary-codecs

예를 들어, 최상위 레벨에서 빌드하기 위해 Qt를 구성할 때 다음 옵션을 전달할 수 있습니다:

configure -webengine-proprietary-codecs

자세한 내용은 Qt 구성 옵션을 참조하십시오.

cmake를 사용하여 Qt WebEngine 모듈만 빌드하는 경우 다음 명령을 사용하여 구성 및 빌드할 수 있습니다(이 예에서는 Qt WebEngine 소스 코드가 C:\qt\qtwebengine)에 있습니다:

qt-configure-module C:\qt\qtwebengine -webengine-proprietary-codecs
cmake --build . --parallel

FFmpeg는 오디오 및 비디오를 녹화, 변환 및 스트리밍하는 크로스 플랫폼 솔루션입니다. 여러 코덱과 함께 사용하도록 구성할 수 있으므로 코덱 라이브러리와 함께 배포하는 동안 라이선스 문제가 발생할 수 있습니다. 일부 코덱의 경우 OpenH264와 같은 오픈 소스 구현을 사용할 수 있습니다.

Chromium 개발 도구

Chromium 개발자 도구는 모든 웹 콘텐츠의 레이아웃 및 성능 문제를 검사하고 디버깅할 수 있는 기능을 제공합니다.

이 기능은 --remote-debugging-port=[your-port] 명령줄 옵션을 사용하여 Qt WebEngine 애플리케이션을 실행하거나 환경 변수 QTWEBENGINE_REMOTE_DEBUGGING 를 설정한 다음 Chromium 기반 브라우저(예: Simple Browser 또는 Nano Browser)를 사용하여 http://localhost:[your-port] 에 연결하여 테스트할 수 있습니다.

--webEngineArgs --remote-debugging-port=5000

원격 디버깅 중 WebSocket 오류를 방지하려면 추가 명령줄 인수를 추가하세요 --remote-allow-origins=<origin>[,<origin>, ...], 여기서 <origin> 은 요청 출처를 나타냅니다. 모든 오리진으로부터의 연결을 허용하려면 --remote-allow-origins=* 을 사용합니다. 아무것도 지정하지 않으면 원격 디버깅이 활성화되면 Qt WebEngine 명령줄 인수에 --remote-allow-origins=* 을 추가하여 모든 오리진으로부터의 요청을 허용합니다.

크롬 개발자 도구 페이지는 애플리케이션 내에서 표시할 수도 있습니다. 이를 설정하려면 검사할 페이지에 QWebEnginePage::setInspectedPage()를 호출하여 this 페이지에 개발자 도구를 암시적으로 로드하거나 QWebEnginePage::setDevToolsPage()를 호출하여 this 페이지를 검사할 수 있습니다.

각 QML 속성은 WebEngineView.devToolsView 및 WebEngineView.inspectedView 입니다.

자세한 내용은 Qt WebEngine 디버깅 및 프로파일링을 참조하세요.

클라이언트 인증서

일부 웹 서버, 특히 많은 인트라넷 사이트에서는 클라이언트가 클라이언트 인증서라고 하는 인증서로 자신을 인증하도록 요구합니다. Qt WebEngine 은 macOS 및 Windows에서는 시스템 설정에 설치된 클라이언트 인증서를, Linux에서는 NSS 데이터베이스에 설치된 인증서를 읽습니다. 인증서는 pk12util 도구를 사용하여 NSS 데이터베이스에 설치할 수 있습니다.

기본적으로 Qt WebEngine 에서는 서버에 클라이언트 인증서를 제공하지 않는데, 이는 사용자를 고유하게 식별하고 개인정보 보호 기대치를 위반할 수 있기 때문입니다.

클라이언트 인증서에 대한 지원을 활성화하려면 애플리케이션에서 QWebEnginePage::selectClientCertificate 또는 WebEngineView.selectClientCertificate 신호를 수신하고 제공되는 인증서 중 하나를 선택해야 합니다. 신뢰할 수 없는 웹사이트로 이동할 수 있는 애플리케이션의 경우 원격 서버에 사용자를 고유하게 식별하기 전에 항상 사용자에게 선택권을 부여하는 것이 좋습니다.

Qt WebEngine 에서는 시스템 설정에 저장된 클라이언트 인증서 외에도 인메모리 저장소도 제공합니다. QWebEngineClientCertificateStore 인스턴스는 QWebEngineProfile::clientCertificateStore() 메서드를 사용하여 얻을 수 있습니다. 애플리케이션은 이 클래스를 사용하여 QWebEngineClientCertificateStore::add() 호출로 새 인증서를 추가할 수 있습니다. selectClientCertificate 호출 시 Qt WebEngine 에는 시스템 및 인메모리에 저장된 클라이언트 인증서가 모두 나열됩니다.

자세한 구현 내용은 클라이언트 인증서 예시를 참조하세요.

사용자 정의 스키마

Qt WebEngine 를 사용하면 애플리케이션에서 특수 보안 정책 및 전송 메커니즘을 사용하여 자체 사용자 지정 URL 스키마를 정의할 수 있습니다.

사용자 지정 스키마를 사용하여 일반적인 웹 보안 정책을 모두 갖춘 대체 네트워크 프로토콜, 사용자 인터페이스 구성 요소를 표시하거나 정보를 디버깅하기 위한 권한 있는 내부 스키마, 추가 제한이 있는 샌드박스가 적용된 스키마 등을 구현할 수 있습니다.

자세한 내용은 QWebEngineUrlScheme 및 QWebEngineUrlSchemeHandler 을 참조하세요.

드래그 앤 드롭

Qt WebEngine 은 HTML5 드래그 앤 드롭을 지원합니다.

이 기능은 HTML5 데모 - 드래그 앤 드롭, HTML5 데모 - 간단한 드래그 앤 드롭 또는 HTML5 데모 - 드래그 앤 드롭, 자동 업로드와 같은 HTML5 데모를 Simple Browser 또는 Nano 브라우저에서 열어 테스트해 볼 수 있습니다.

파일을 브라우저로 드래그하는 것은 실제로 HTML5의 일부가 아니지만 지원됩니다. HTML5 데모 - 파일 API를 열어 테스트할 수 있습니다.

파비콘

Qt WebEngine 은 웹 사이트 URL 아이콘인 파비콘을 지원합니다. 각 아이콘은 QWebEngineProfile 각각의 내부 데이터베이스에 저장되며 QWebEnginePage::icon() 호출 또는 현재 로드된 콘텐츠의 WebEngineView.icon 속성을 사용하여 액세스할 수 있습니다.

또한 Qt WebEngine 에서는 내부 프로필의 데이터베이스에 이미 저장된 아이콘에 액세스하기 위한 API를 제공합니다.

QML 파비콘 처리

아이콘에 액세스하기 위해 QQuickImageProvider 이 등록되어 있습니다. 이 공급자는 스키마가 "image:"이고 호스트가 "favicon"인 특수 URL로 액세스할 수 있습니다.

Image {
    source: "image://favicon/url"
}

url 은 파비콘의 URL이 될 수 있습니다:

Image {
    source: "image://favicon/https://www.qt.io/hubfs/2016_Qt_Logo/qt_logo_green_rgb_16x16.png"
}

url 은 해당 아이콘에 액세스하기 위한 페이지 URL일 수도 있습니다:

Image {
    source: "image://favicon/https://www.qt.io/"
}

두 개 이상의 아이콘을 사용할 수 있는 경우 Image::sourceSize 속성을 지정하여 원하는 크기의 아이콘을 선택할 수 있습니다. Image::sourceSize 을 지정하지 않거나 0으로 지정하면 사용 가능한 가장 큰 아이콘이 선택됩니다.

이미지 제공업체는 기존 WebEngineView 인스턴스에서 요청된 아이콘을 조회합니다. 먼저 현재 표시된 아이콘과 일치하는지 확인합니다. 일치하는 아이콘을 찾지 못하면 데이터베이스에서 아이콘을 요청합니다. 각 프로필에는 고유한 아이콘 데이터베이스가 있으며 영구 저장소에 저장되므로 네트워크 연결 없이도 저장된 아이콘에 액세스할 수 있습니다. 아이콘을 데이터베이스에 저장하려면 아이콘을 미리 로드해야 합니다.

C++ 파비콘 처리

사용자는 QWebEngineProfile::requestIconForPageURL() 또는 QWebEngineProfile::requestIconForIconURL() 호출을 사용하여 각 QWebEngineProfile 에 대해 이전에 로드된 콘텐츠에서 아이콘을 요청할 수 있습니다. 프로필의 데이터베이스는 영구 저장소에 저장되며 네트워크 연결 없이도 액세스할 수 있습니다.

전체 화면

Qt WebEngine 은 전체 화면 모드에서 웹 콘텐츠를 볼 수 있도록 지원합니다. 자세한 내용은 WebEngineSettings.fullscreenSupportEnabled, WebEngineView.fullScreenRequested, QWebEngineSettings::FullScreenSupportEnabled, QWebEnginePage::fullScreenRequested 을 참조하세요.

이 기능은 비디오 플레이어 또는 나노 브라우저에서 YouTube의 동영상을 재생하고 전체 화면 아이콘을 클릭하여 전체 화면 모드로 전환하여 테스트할 수 있습니다.

하드웨어 가속

Qt WebEngine 은 가능한 경우 웹 콘텐츠 렌더링에 하드웨어 가속을 사용하려고 시도합니다. 실제 렌더링은 Chromium에서 수행하며 최종 이미지는 플랫폼과 사용 가능한 드라이버에 따라 OpenGL, Vulkan, Metal 또는 Direct3D와 같은 최신 GPU API를 사용하는 Chromium의 컴포저에서 생성합니다.

그런 다음 이 최종 이미지를 Qt WebEngine 에서 GPU 상호 운용성을 사용하여 Qt 렌더링 파이프라인으로 가져와 불필요한 복사본 없이 GPU 리소스를 효율적으로 공유할 수 있습니다. 가져온 이미지는 Qt Quick Scene Graph로 전달되며, 이 역시 Qt Rendering Hardware Interface(RHI)를 통해 하드웨어 가속 렌더링을 수행합니다.

Qt와 크롬은 모두 GPU 가속에 의존하지만 반드시 동일한 그래픽 API를 사용할 필요는 없습니다. 실제로 Qt WebEngine 는 호환성과 최적의 성능을 보장하기 위해 가능한 경우 Qt가 선택한 백엔드 구성을 기본값으로 하여 Chromium의 GPU 백엔드를 Qt에서 사용하는 것과 일치시키려고 시도하지만, 필요한 경우 이러한 기본값을 수동으로 재정의할 수 있습니다.

하드웨어 가속을 사용할 수 없거나 실패하면 Qt WebEngine 은 자동으로 소프트웨어 렌더링으로 돌아갑니다.

소프트웨어 렌더링 강제 사용

소프트웨어 렌더링으로의 자동 폴백이 항상 가능한 것은 아니며 Qt WebEngine 웹 콘텐츠가 제대로 표시되지 않거나 오류 메시지와 함께 종료될 수 있습니다. 이러한 경우 하드웨어 가속을 명시적으로 비활성화하고 대신 소프트웨어 렌더링을 사용해야 할 수도 있습니다.

소프트웨어 렌더링을 강제 적용하는 방법에는 여러 가지가 있습니다:

• 크롬에서 하드웨어 가속을 비활성화합니다:

  export QTWEBENGINE_CHROMIUM_FLAGS=--disable-gpu

• Qt Quick 씬 그래프에서 하드웨어 가속을 비활성화합니다:

  export QT_QUICK_BACKEND=software

Qt에서 그래픽 API 백엔드 변경하기

그래픽 API 백엔드를 선택하는 방법에는 두 가지가 있습니다:

• 애플리케이션을 시작하기 전에 QSG_RHI_BACKEND 환경 변수를 설정합니다.
• QQuickWindow::setGraphicsApi()를 QSGRendererInterface::GraphicsApi 과 함께 호출하여 첫 번째 QQuickWindow 를 구성합니다.

자세한 내용은 Qt 렌더링 하드웨어 인터페이스를 통한 렌더링을 참조하십시오.

Chromium에서 그래픽 API 백엔드 변경하기

호환성 문제나 일관성 없는 렌더링 동작이 발생할 수 있으므로 일반적으로 Chromium의 그래픽 API 백엔드를 변경하는 것은 권장하지 않습니다. 가능하면 QSG_RHI_BACKEND 환경 변수를 사용하는 것이 좋습니다. 그러나 디버깅을 위해 또는 드라이버별 문제에 대한 임시 해결 방법으로 필요한 경우가 있을 수 있습니다.

Chromium의 백엔드를 재정의하려면 QTWEBENGINE_CHROMIUM_FLAGS 환경 변수를 설정하여 --use-gl= 또는 --use-angle= 과 같은 해당 Chromium 명령줄 플래그를 전달하세요.

Qt WebEngine 에서 현재 하드웨어 가속이 지원되는 모든 플랫폼에서 Chromium은 기본적으로 ANGLE 백엔드를 사용합니다. ANGLE은 기본 네이티브 그래픽 백엔드를 숨기는 Chromium의 크로스 플랫폼 그래픽 추상화 레이어입니다.

기본 구성( Qt WebEngine )은 이 구성을 사용합니다:

export QTWEBENGINE_CHROMIUM_FLAGS="--use-gl=angle --use-angle=default"

특정 구성에서 ANGLE이 충돌하는 경우 하드웨어 가속 렌더링을 위해 Vulkan을 계속 사용하면서 완전히 비활성화할 수 있습니다:

export QTWEBENGINE_CHROMIUM_FLAGS="--use-gl=stub --enable-features=Vulkan --use-vulkan=native"

또는 다음 구성은 렌더링에 Vulkan을 사용하면서 WebGL 지원을 위해 ANGLE을 활성화한 상태로 유지합니다:

export QTWEBENGINE_CHROMIUM_FLAGS="--use-gl=angle --enable-features=Vulkan --use-vulkan=native"

해당 Chromium 명령줄 플래그에 대한 자세한 내용은 Chromium의 소스 코드를 참조하세요: //ui/gl/gl_switches.cc

Linux의 NVIDIA

NVIDIA GPU가 탑재된 Linux 시스템에서 Chromium은 렌더링에 Vulkan을 사용해야 합니다.

Qt WebEngine 는 GBM 버퍼 객체를 사용하여 텍스처를 Chromium에서 Qt의 그래픽 파이프라인으로 가져옵니다. 그러나 현재 NVIDIA 드라이버는 이러한 버퍼 객체 할당을 지원하지 않습니다. 해결 방법으로 Qt WebEngine 은 Chromium이 Vulkan으로 렌더링하도록 강제하고 Vulkan 상호 운용성을 사용하여 텍스처를 가져옵니다.

로깅 및 문제 해결 활성화

렌더링 문제가 발생하면 문제를 효과적으로 조사하고 보고하기 위해 실패한 구성과 하드웨어 가속의 현재 상태를 파악하는 것이 중요합니다.

이 정보를 확인하는 가장 쉬운 방법은 chrome://gpu 내부 페이지를 로드하여 내용을 분석하는 것입니다. 그러나 렌더링 문제가 발생하는 동안에는 이 페이지를 항상 읽을 수 있거나 사용할 수 없는 경우도 있습니다.

Qt WebEngine 자세한 그래픽 정보를 덤프하도록 설정할 수 있는 로깅 카테고리를 제공합니다:

• qt.webenginecontext Qt WebEngine 초기화 방법, 감지된 GPU 및 그래픽 구성을 기록합니다.
• qt.webengine.compositor 는 Chromium에서 사용하는 구성과 텍스처를 Qt의 그래픽 파이프라인으로 가져오기 위해 Qt WebEngine 가 수행하는 단계를 기록합니다.

이러한 로그를 활성화하려면 예를 들어 QT_LOGGING_RULES 환경 변수를 설정합니다:

export QT_LOGGING_RULES="qt.webenginecontext=true;qt.webengine.compositor=true"

다음은 qt.webenginecontext 의 GPU 로그 예시입니다:

Chromium GL Backend: angle
Chromium ANGLE Backend: default
Chromium Vulkan Backend: disabled

QSG RHI Backend: OpenGL
QSG RHI Backend Supported: yes
QSG RHI Device: AMD AMD Radeon Graphics (radeonsi, raphael_mendocino, LLVM 20.1.8, DRM 3.61, 6.12.41-gentoo-x86_64) 4.6 (Compatibility Profile) Mesa 25.1.9
QSG RHI GPU Vendor: AMD

첫 번째 블록은 Chromium 구성을 보여줍니다:

• Chromium GL Backend --use-gl= 설정의 값을 보여줍니다.
• Chromium ANGLE Backend --use-angle= 설정의 값을 보여줍니다.
• Chromium Vulkan Backend --use-vulkan= 설정의 값을 보여줍니다.

두 번째 블록은 Qt 구성을 표시합니다:

• QSG RHI Backend 기본 네이티브 그래픽 API를 표시합니다.
• QSG RHI Backend Supported 이 그래픽 API가 Qt WebEngine 에서 지원되는지 여부를 나타냅니다.
• QSG RHI Device RHI에서 사용하는 그래픽 장치의 메타데이터를 표시합니다.
• QSG RHI Vendor 는 RHI에서 사용하는 그래픽 장치의 공급업체를 보여줍니다.

다음은 동일한 GPU에 대한 qt.webengine.compositor 의 ANGLE 로그 예시입니다:

qt.webengine.compositor: ANGLE_OPENGL display is initialized:
GL Renderer: ANGLE (AMD, AMD Radeon Graphics (radeonsi raphael_mendocino LLVM 20.1.8), OpenGL 4.6 (Core Profile) Mesa 25.1.9)
2 GPU(s) detected:
  Nvidia, device id: 0x1d01, driver: Mesa 25.1.9, system device id: 0x0, preference: None, active: no
  AMD, device id: 0x164e, driver: Mesa 25.1.9, system device id: 0x0, preference: None, active: yes
NVIDIA Optimus: disabled
AMD Switchable: disabled

위의 로그 항목은

• ANGLE_OPENGL display is initialized ANGLE이 지정된 디스플레이 유형으로 성공적으로 초기화되었음을 확인합니다.
• GL Renderer ANGLE이 사용하는 그래픽 디바이스에 대한 메타데이터를 보여줍니다( QSG RHI Device)와 일치할 것으로 예상됩니다.
• 2 GPU(s) detected 는 ANGLE이 감지한 GPU를 나열합니다.
• NVIDIA Optimus 와 AMD Switchable 는 ANGLE이 런타임에 GPU 전환을 지원하는지 여부를 나타냅니다(현재는 지원되지 않음).

HTML5 DRM

Qt WebEngine 은 Widevine CDM 플러그인이 설치된 경우 DRM으로 보호된 동영상 표시를 지원합니다. 이 플러그인은 바이너리 형식으로만 제공되므로 DRM 복호화 구현 세부 정보를 숨길 수 있습니다. 이 플러그인은 타사 또는 Google Chrome 설치에서 얻을 수 있습니다.

시작 시 Qt WebEngine 은 기본 Google Chrome 설치 디렉토리 또는 Linux 배포판별 경로와 같이 잘 알려진 여러 위치에서 Widevine CDM 플러그인을 찾습니다. widevine-path 을 사용하여 플러그인 위치를 QTWEBENGINE_CHROMIUM_FLAGS 으로 전달할 수도 있습니다.

Windows의 경우

set QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="C:/some path/widevinecdm.dll"

Linux의 경우

export QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="/some path/libwidevinecdm.so"

macOS의 경우:

export QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="/some path/libwidevinecdm.dylib"

DRM 서비스에서 가장 일반적으로 사용되는 동영상 형식인 H.264에는 전용 오디오 및 동영상 코덱이 필요합니다. 코덱 활성화에 대한 자세한 내용은 오디오 및 비디오 코덱을 참조하세요.

심플 브라우저 또는 나노 브라우저 예제 프로젝트에서 castLabs 또는 Bitmovin Player의 동영상을 재생하여 이 기능을 테스트할 수 있습니다.

HTML5 지오로케이션

Qt WebEngine 은 자바스크립트 지오로케이션 API를 지원하며 Qt Positioning 를 백엔드로 사용합니다. HTML5 지오로케이션은 기본적으로 비활성화되어 있습니다. 명시적으로 허용하려면 애플리케이션이 QWebEnginePage::permissionRequested 을 수신해야 합니다. QWebEnginePermission::PermissionType::Geolocation 유형의 권한 요청이 수신되면 수신된 객체에서 QWebEnginePermission::grant()를 호출하여 필요한 권한을 부여할 수 있습니다.

Qt WebEngine 이 Qt Positioning 지원으로 빌드된 경우 지도를 사용하여 사용자의 현재 위치를 찾도록 허용하여 이 기능을 테스트할 수 있습니다.

이와 같은 백엔드 설정은 Qt Positioning 를 참조하여 GPS 또는 IP 기반 위치와 같은 가능한 백엔드 설정을 확인하세요.

HTML5 권한

Qt WebEngine 은 QWebEnginePermission API를 통해 여러 유형의 웹 기능 권한을 지원합니다. 페이지에서 사용자의 카메라 또는 지리적 위치 액세스 등 잠재적으로 민감한 사용자 정보를 요청할 때마다 웹 도메인에 권한을 부여하거나 거부할 수 있습니다.

애플리케이션 개발자는 최종 사용자에게 권한을 요청할지 아니면 자동으로 결정할지 선택할 수 있습니다. 또한 알려진 도메인에서 특정 권한을 요청할 것으로 예상되는 경우 선제적으로 특정 권한을 부여하거나 거부할 수 있습니다.

QWebEngineProfile 개체는 개별 도메인에 부여되거나 거부된 모든 권한을 저장합니다. 현재 프로필이 기록되지 않는 한 이러한 권한은 디스크에 저장되어 다음에 애플리케이션을 열 때 불러올 수 있습니다. 그러나 이 동작은 수정할 수 있으며 개발자는 애플리케이션이 종료될 때까지만 권한을 저장하거나 웹사이트가 권한을 요청할 때마다 권한 요청을 트리거하도록 선택할 수 있습니다.

현재 지원되는 웹 권한의 전체 목록은 in the QWebEnginePermission documentation 에서 확인할 수 있습니다.

프레임

개발자는 QWebEngineFrame API를 사용하여 웹 페이지 내의 개별 <iframe> 요소를 검사하고 상호 작용할 수 있습니다. 이를 통해 JavaScript를 삽입하거나 프레임이 삽입된 페이지를 무시하고 프레임의 콘텐츠만 인쇄할 수 있습니다. 프레임이 다른 프레임 안에 존재하는 경우 프레임에 재귀적으로 액세스할 수도 있습니다.

HTML5 웹소켓

Qt WebEngine 은 ws:// 또는 wss:// 프로토콜을 사용하여 웹소켓 서버와 통신할 수 있는 웹소켓 자바스크립트 API를 지원합니다. 또한 Qt WebChannel 및 Qt WebSockets 과의 통합을 통해 JavaScript와 애플리케이션의 네이티브 측 간의 통신이 가능합니다.

Qt WebChannel 모듈에는 채팅 서버와 웹 기반 채팅 클라이언트에 대한 좋은 예가 있습니다. 클라이언트는 Qt WebEngine 의 예제 브라우저(예: 심플 브라우저 또는 나노 브라우저)에서 바로 작동합니다.

HTTP/2 프로토콜

Qt WebEngine 은 HTTP/2 프로토콜의 크롬 구현을 지원합니다.

이 기능은 심플 브라우저 또는 나노 브라우저에서 Akamai HTTP/2 데모와 같은 HTTP/2 데모를 열어 테스트할 수 있습니다.

로컬 스토리지

Qt WebEngine 는 만료일 없이 키-값 쌍을 Local Storage 에 저장하는 기능을 지원합니다. 이는 웹 스토리지 API의 일부로, 사용자는 Window.localStorage JavaScript 속성을 사용하여 지정된 도메인에 대한 Storage 개체에 액세스할 수 있습니다. 저장된 데이터는 페이지 또는 브라우저 애플리케이션이 닫힌 후에도 유지됩니다.

Local 저장소는 QWebEngineSettings::LocalStorageEnabled 설정으로 비활성화할 수도 있습니다. 또한 QWebEngineProfile::setPersistentStoragePath 호출을 통해 저장 경로를 조정할 수 있습니다.

QWebEngineProfile profile("MyProfile");
profile.settings()->setAttribute(QWebEngineSettings::LocalStorageEnabled, isEnabled);
profile.setPersistentStoragePath("/path/to/storage");

Qt WebEngine Application 패널을 방문하여 Local Storage 메뉴를 확장하면 Qt WebEngine 개발자 도구를 사용하여 Local Storage 의 콘텐츠를 쉽게 조사할 수 있는 방법도 제공합니다.

기본 대화 상자

웹 페이지에서 다음과 같은 기능에 대한 대화 상자를 요청할 수 있습니다:

• HTTP 및 프록시 인증을 위한 사용자 자격 증명 입력
• JavaScript 경고, 확인 대화 상자 및 프롬프트 표시
• 색상 선택
• 파일 선택
• 양식 유효성 검사 메시지 표시

Qt WebEngine 는 이러한 기능에 대한 표준 대화 상자를 제공합니다. 위젯 기반 애플리케이션에서 표준 대화 상자는 QDialog 을 기반으로 하는 반면, Qt Quick 애플리케이션에서는 Qt Quick Controls 1 또는 Qt Quick Controls 2를 기반으로 할 수 있습니다. 후자는 eglfs 플랫폼에서만 사용됩니다.

Qt Quick Controls 1 또는 Qt Quick Controls 2 기반의 대화 상자를 명시적으로 강제하려면 QTWEBENGINE_DIALOG_SET 환경 변수를 QtQuickControls1 또는 QtQuickControls2 로 설정합니다.

Qt WebEngine 위젯 대화 상자는 QWebEnginePage::chooseFiles(), QWebEnginePage::javaScriptAlert(), QWebEnginePage::javaScriptConfirm() 및 QWebEnginePage::javaScriptPrompt() 함수를 다시 구현하여 사용자 정의할 수 있습니다.

Qt Quick WebEngineView::authenticationDialogRequested (), WebEngineView::javaScriptDialogRequested(), WebEngineView::colorDialogRequested(), WebEngineView::fileDialogRequested() 및 WebEngineView::formValidationMessageRequested() 시그널에 연결하여 대화 상자를 사용자 정의할 수 있습니다.

PDF 파일 보기

Qt WebEngine 는 PDF 문서로 이동하여 보기를 지원합니다. 이 기능은 Chromium 확장 API와 PDF 뷰어 플러그인을 사용하여 PDF 문서를 표시합니다. 심플 브라우저 또는 나노 브라우저에서 테스트할 수 있습니다.

이 기능은 QWebEngineSettings::PdfViewerEnabled 또는 WebEngineSettings::pdfViewerEnabled 설정을 통해 켜거나(기본값) 끌 수 있습니다.

페이지 수명 주기 API

Qt WebEngine 는 사용자 에이전트가 백그라운드 페이지를 고정하거나 폐기하여 리소스 소비를 줄일 수 있도록 하는 HTML 표준의 작업 중인 확장인 페이지 수명 주기 API 사양을 지원합니다. 이 기능은 위젯과 QML API 모두에 노출됩니다.

사용 중인 QML API의 예는 웹엔진 수명 주기 예시를 참조하세요.

수명 주기 상태 개요

각 WebEngineView 항목(또는 QWebEnginePage 개체)은 활성, 고정 또는 폐기된 세 가지 수명 주기 상태 중 하나에 속할 수 있습니다. 이러한 상태는 CPU의 절전 상태와 마찬가지로 웹 보기의 리소스 사용량을 제어합니다.

활성 상태는 웹 보기의 제한이 없는 일반적인 상태입니다. 표시되는 모든 웹 보기는 아직 로드가 완료되지 않은 모든 웹 보기와 마찬가지로 항상 활성 상태입니다. 보이지 않는 유휴 웹 보기만 다른 수명 주기 상태로 전환할 수 있습니다.

고정 상태는 CPU 사용량이 낮은 상태입니다. 이 상태에서는 대부분의 HTML 작업 소스가 일시 중단(고정)되며, 그 결과 대부분의 DOM 이벤트 처리 및 JavaScript 실행도 일시 중단됩니다. 이 상태에서는 렌더링이 불가능하므로 웹 보기가 보이지 않아야 정지 상태가 됩니다.

폐기된 상태는 리소스를 극도로 절약하는 상태입니다. 이 상태에서는 웹 보기의 브라우징 컨텍스트가 삭제되고 해당 렌더러 하위 프로세스가 종료됩니다. 이 상태의 CPU 및 메모리 사용량은 사실상 0으로 감소합니다. 이 상태를 종료하면 웹 페이지가 자동으로 다시 로드됩니다. 폐기 상태로 들어가고 나가는 과정은 웹 보기의 검색 기록을 직렬화하고 보기를 파괴한 다음 새 보기를 만들고 기록을 복원하는 것과 유사합니다.

WebEngineView::LifecycleState 를 참조하세요. 위젯 API에서 이에 해당하는 것은 QWebEnginePage::LifecycleState 입니다.

lifecycleState 및 recommendedState 속성

WebEngineView 유형의 lifecycleState 속성은 웹 보기의 현재 수명 주기 상태를 제어하는 읽기-쓰기 속성입니다. 이 속성은 전환할 수 있는 상태에 가능한 한 제한을 두지 않도록 설계되었습니다. 예를 들어, 현재 백그라운드에서 음악을 재생 중인 웹 보기를 고정하여 음악을 중지할 수 있습니다. 사용자가 볼 수 있는 백그라운드 활동을 방해하지 않는 덜 공격적인 리소스 절약 전략을 구현하려면 recommendedState 속성을 사용해야 합니다.

WebEngineView 유형의 recommendedState 속성은 웹 보기의 현재 활동을 고려하여 lifecycleState 속성에 대한 안전 한도를 계산하는 읽기 전용 속성입니다. 따라서 백그라운드에서 음악을 재생하는 웹 보기의 예에서 더 공격적인 상태는 음악을 중지하므로 권장 상태는 Active 입니다. 애플리케이션이 백그라운드 활동을 중단하지 않으려면 웹 뷰를 recommendedState 보다 더 적극적으로 리소스를 절약하는 수명 주기 상태로 설정하지 않아야 합니다.

WebEngineView::lifecycleState 및 WebEngineView::recommendedState 을 참조하세요. 위젯 API에 해당하는 것은 QWebEnginePage::lifecycleState 와 QWebEnginePage::recommendedState 입니다.

DOM 확장

lifecycleState 속성은 페이지 수명 주기 API 사양에 연결되어 freeze 및 resume 라는 두 개의 새로운 DOM 이벤트를 지정하고 새로운 Document.wasDiscarded 부울 속성을 추가합니다. freeze 및 resume 이벤트는 Active 에서 Frozen state 로 또는 그 반대로 전환할 때 발생합니다. Document.wasDiscarded 속성은 Discarded 상태에서 Active 상태로 전환할 때 true 로 설정됩니다.

PDF로 인쇄

Qt WebEngine 는 웹 페이지를 PDF 파일로 인쇄하는 기능을 지원합니다. 자세한 내용은 QWebEnginePage::printToPdf() 및 WebEngineView.printToPdf 을 참조하세요.

이 기능은 Html2Pdf를 사용하여 테스트할 수 있습니다.

푸시 알림

Qt WebEngine 는 푸시 알림을 구독하고 수신하기 위한 JavaScript 푸시 API를 지원합니다. 자세한 내용은 QWebEngineProfile::setPushServiceEnabled() 및 WebEngineProfile.setPushServiceEnabled 을 참조하세요.

이 기능은 WebEngine 푸시 알림 예제를 통해 테스트할 수 있습니다.

맞춤법 검사기

Qt WebEngine 는 맞춤법 검사 기능을 HTML 양식에 통합하여 사용자가 맞춤법 검사된 메시지를 제출할 수 있도록 지원합니다. 사용자가 밑줄이 그어진 철자가 틀린 단어를 클릭하면 기본 컨텍스트 메뉴에 최대 4개의 제안이 표시됩니다. 하나를 선택하면 철자가 틀린 단어가 대체됩니다.

맞춤법 검사기가 맞춤법을 확인하려면 사전이 필요합니다. Hunspell 프로젝트의 사전을 지원하지만 특수 바이너리 형식으로 컴파일해야 합니다. Hunspell 사전은 두 개의 파일로 구성됩니다:

• 해당 언어의 단어가 포함된 사전인 .dic 파일
• 사전에서 특수 플래그의 의미를 정의하는 .aff 파일

이 두 파일은 Qt와 함께 제공되는 qwebengine_convert_dict 도구를 사용하여 bdic 형식으로 변환할 수 있습니다. Qt WebEngine 맞춤법 검사기가 초기화되면 bdict 사전을 로드하고 일관성을 확인하려고 시도합니다.

CMake의 경우, qt_add_webengine_dictionary 명령을 사용하여 Hunspell .dic 파일을 .bdic 바이너리 형식으로 변환할 수 있습니다. 이 명령은 프로젝트에서 종속성을 사용할 수 있는 qtwebengine_dictionaries 대상을 생성합니다.

기본적으로 Qt WebEngine 은 실행 파일을 기준으로 qtwebengine_dictionaries 디렉터리 내에서 사전이 존재할 경우 사전을 검색합니다. 존재하지 않으면 QT_INSTALL_PREFIX/qtwebengine_dictionaries 에서 찾습니다.

또는 QTWEBENGINE_DICTIONARIES_PATH 환경 변수의 값으로 또는 명령줄을 통해 사전 디렉터리 경로를 설정할 수 있습니다:

--webEngineArgs --webengine-dictionaries-path=<path>

재정의가 설정되면 애플리케이션은 제공된 디렉토리 내에서만 사전을 찾고 다른 곳에서는 사전을 찾지 않습니다.

macOS에서는 빌드 시 Qt WebEngine 을 어떻게 구성하느냐에 따라 맞춤법 검사 데이터를 찾는 방법이 두 가지로 나뉩니다:

• Hunspell 사전(기본값) - 다른 플랫폼에서와 마찬가지로 .bdic 사전이 사용됩니다.
• 네이티브 사전 - macOS 맞춤법 검사 API가 사용됩니다(즉, 결과는 설치된 OS 사전에 따라 달라집니다).

따라서 macOS Hunspell의 경우 Qt WebEngine 은 애플리케이션 번들 Resources 디렉터리 안에 있는 qtwebengine_dictionaries 하위 디렉터리와 Qt 프레임워크 번들 안에 있는 Resources 디렉터리를 찾습니다.

요약하자면, Hunspell을 사용하는 경우 다음 경로가 고려됩니다:

• QTWEBENGINE_DICTIONARIES_PATH설정된 경우
• QCoreApplication::applicationDirPath()/qtwebengine_dictionaries 또는 QCoreApplication::applicationDirPath()/../Contents/Resources/qtwebengine_dictionaries(macOS의 경우)
• [QLibraryInfo::DataPath]/qtwebengine_dictionaries 또는 경로/to/QtWebEngineCore.framework/Resources/qtwebengine_dictionaries (macOS의 Qt 프레임워크 번들)

맞춤법 검사는 기본적으로 비활성화되어 있으며 위젯 기반 애플리케이션에서는 QWebEngineProfile::setSpellCheckEnabled() 메서드를, Qt Quick 애플리케이션에서는 WebEngineProfile.spellCheckEnabled 속성을 사용하여 프로필별로 활성화할 수 있습니다.

맞춤법 검사에 사용되는 현재 언어는 프로필별로 정의되며 QWebEngineProfile::setSpellCheckLanguages() 메서드 또는 WebEngineProfile.spellCheckLanguages 속성을 사용하여 설정할 수 있습니다.

이 기능은 맞춤법 검사기 예제를 빌드하고 실행하여 테스트할 수 있습니다.

Qt WebEngine webengine-spellchecker configure 스위치를 사용하여 맞춤법 검사기 지원 없이도 컴파일할 수 있습니다.

qt-configure-module path\to\qtwebengine\sources -no-webengine-spellchecker

자세한 내용은 Qt 구성 옵션을 참조하십시오.

Touch

Qt WebEngine 는 웹 페이지 탐색 및 상호 작용을 위한 터치 장치를 지원합니다.

JavaScript API의 터치 이벤트 지원은 터치 스크린의 존재 여부에 따라 달라집니다(즉, 지원되는 터치 장치가 시스템에 연결되어 있는 경우 ontouchstart 및 관련 핸들러가 document.window 객체에 존재하게 됩니다).

일부 웹사이트는 이 API를 사용하여 모바일 기기에서 실행할지 데스크톱에서 실행할지 결정하고 이에 따라 디자인을 결정합니다. 이로 인해 터치스크린 노트북이나 가짜 터치 장치를 에뮬레이트하는 기타 설정에서 원치 않는 결과가 발생할 수 있습니다.

애플리케이션은 QWebEngineSettings::TouchEventsApiEnabled 을 사용하여 이 기능을 명시적으로 설정할 수 있습니다.

API가 비활성화되어 있어도 터치 이벤트는 웹 페이지에 계속 전달된다는 점에 유의하세요. WebEngine 보기 포커스 프록시 객체에 QObject::installEventFilter 를 사용하여 이벤트 필터 객체를 설치하고 모든 터치 이벤트를 필터링하여 웹 페이지로 터치 이벤트 전송을 금지할 수 있습니다.

소스 보기

Qt WebEngine 는 웹 페이지의 HTML 소스 보기를 지원합니다.

이 기능은 사용자 지정 메뉴에서 사용하거나 사용자 지정 이벤트에 할당할 수 있습니다. 자세한 내용은 WebEngineView::WebAction 및 QWebEnginePage::WebAction 을 참조하세요.

이 기능은 심플 브라우저 또는 나노 브라우저에서 웹 페이지를 연 다음 컨텍스트 메뉴에서 Page Source 을 선택하여 테스트할 수 있습니다. Page Source 컨텍스트 메뉴 항목은 새 탭에서 소스 보기를 엽니다.

현재 탭에서 소스 보기를 여는 경우 보기-소스 URI 체계의 URL도 지원됩니다. 예를 들어 URL 표시줄에 다음 URL을 입력하면 qt.io 웹 페이지의 HTML 소스를 볼 수 있습니다:

view-source:https://www.qt.io/

보기 소스 URI 체계를 가진 불완전한 URL의 자동 완성 기능을 사용하면 이 기능을 더욱 편리하게 사용할 수 있습니다. 예를 들어, 다음 불완전한 URL은 qt.io 웹 페이지의 소스 보기도 로드합니다:

view-source:qt.io

웹 알림

Qt WebEngine 은 자바스크립트 웹 알림 API를 지원합니다. 애플리케이션은 QWebEnginePage::Notifications 또는 WebEngineView.Notifications 를 사용하여 이 기능을 명시적으로 허용해야 합니다.

웹엔진드라이버

WebEngineDriver를 사용하면 여러 브라우저에서 웹 사이트 테스트를 자동화할 수 있습니다. 웹엔진드라이버는 크롬드라이버를 기반으로 하며 동일한 방식으로 사용할 수 있습니다. ChromeDriver와 그 사용에 대한 자세한 내용은 ChromeDriver 사용자 사이트를 참조하세요.

웹엔진드라이버는 Qt WebEngine 기반 브라우저에 연결할 수 있도록 크롬드라이버에 비해 약간의 수정이 있습니다. Simple Browser 또는 Nano Browser와 같은 Qt WebEngine 예제 브라우저와 호환됩니다.

브라우저 자동화는 셀레늄 웹드라이버와 같은 웹드라이버 클라이언트를 통해 스크립팅됩니다. 예를 들어 웹엔진드라이버는 셀레늄 웹드라이버의 파이썬 언어 바인딩과 함께 사용할 수 있습니다:

from selenium import webdriver
from selenium.webdriver.chrome.service import Service

service = Service(executable_path='QTDIR/libexec/webenginedriver')
options = webdriver.ChromeOptions()
options.binary_location = 'path/to/browser_binary'

driver = webdriver.Chrome(service=service, options=options)
driver.get("http://www.google.com/")
driver.quit()

이 예제에서는

• executable_path 는 웹엔진드라이버의 바이너리 경로로 설정해야 합니다.
• QTDIR 는 Qt가 설치된 디렉토리
• options.binary_location 는 브라우저의 바이너리 경로로 설정해야 합니다.

스크립트를 실행하기 전에 QTWEBENGINE_REMOTE_DEBUGGING 환경 변수를 설정해야 합니다. 이 값은 브라우저와 웹엔진드라이버가 서로 통신할 때 사용하는 포트 번호입니다.

export QTWEBENGINE_REMOTE_DEBUGGING=12345

스크립트를 실행하면 지정된 웹 브라우저가 열리고 Google 웹 사이트가 로드됩니다.

원격 디버깅 포트가 설정된 상태에서 시작된 경우 이미 실행 중인 브라우저에 WebEngineDriver를 연결할 수도 있습니다. options.debugger_address 을 스크립트에서 원격 디버깅 주소로 설정해야 합니다:

options.debugger_address = 'localhost:12345'

이 경우 브라우저가 이미 실행 중이므로 options.binary_location 을 설정해서는 안 됩니다. options.debugger_address 이 설정된 경우 환경 변수 QTWEBENGINE_REMOTE_DEBUGGING 은 WebEngineDriver에서 사용되지 않습니다.

WebGL

Qt WebEngine 은 일부 그래픽 스택 설정에 대해 WebGL을 지원합니다. 사용자는 QtWebEngine 기반 애플리케이션을 사용하여 chrome://gpu 페이지를 방문할 수 있습니다. 그래픽 기능 상태 개요에는 현재 플랫폼 설정에서 WebGL이 지원되는지 여부가 표시됩니다. 사용자는 WebGL 보고서도 확인할 수 있습니다.

WebGL 지원은 기본적으로 활성화되어 있습니다. QWebEngineSettings::WebGLEnabled 설정을 사용하여 비활성화할 수 있습니다.

WebRTC

WebRTC는 간단한 API를 통해 브라우저에 실시간 통신(RTC) 기능을 제공합니다. 자세한 내용은 WebEngineView.Feature, 및 QWebEnginePage::Feature를 참조하세요.

이 기능은 웹캠 또는 마이크를 설정한 다음 Simple Browser 또는 Nano Browser에서 https://test.webrtc.org/ 을 열어 테스트할 수 있습니다.