VirtualKeyboard API

요약

VirtualKeyboard API는 작성자에게 가상 키보드(VK)의 표시 여부에 대한 더 많은 제어 권한과 VK 표시 여부가 변경될 때 웹 페이지 레이아웃을 더욱 적절하게 조정할 수 있는 기능을 제공합니다.

WebIDLpartial interface Navigator {
    [SecureContext, SameObject] readonly attribute VirtualKeyboard virtualKeyboard;
};

[Exposed=Window, SecureContext]
interface VirtualKeyboard : EventTarget {
    undefined show();
    undefined hide();
    readonly attribute DOMRect boundingRect;
    attribute boolean overlaysContent;
    attribute EventHandler ongeometrychange;
};

VirtualKeyboard 객체에는 다음이 연결되어 있습니다:

boundingRect

DOMRect, 처음에는 값이 0입니다.

overlaysContent

boolean, 처음에는 false입니다. 이 속성이 true로 설정되면 사용자 에이전트는 MUST NOT 자신의 document의 viewport 또는 visual viewport를 리사이즈해서는 안 됩니다.

show() 메서드

이 메서드는 다음 단계를 따라야 합니다:

window를 this의 relevant global object로 설정합니다. window가 Window 객체임을 보장합니다.
window에 sticky activation이 없으면 이 단계를 중단합니다.
포커스된 요소가 폼 컨트롤(예: textarea 요소값) 또는 editing host (예: contenteditable 사용) 아니라면 이 단계를 중단합니다.
virtualKeyboardPolicy 값이 manual이 아니거나 inputMode 속성 값이 none이면 이 단계를 중단합니다.
시스템 API를 호출하여 VK를 표시합니다.
병렬로 다음 단계를 수행합니다:
1. 시스템에서 가상 키보드가 표시될 때까지 기다립니다.
2. set the virtual keyboard bounding rect 를 키보드의 OS 보고 bounding rectangle과 document의 viewport rectangle로 호출합니다.
3. 이벤트를 발생시키며 이름은 "geometrychange"이고 this에서 발생합니다.

hide() 메서드

이 메서드는 다음 단계를 따라야 합니다:

window를 this의 relevant global object로 설정합니다. window가 Window 객체임을 보장합니다.
window에 sticky activation이 없으면 이 단계를 중단합니다.
포커스된 요소의 virtualKeyboardPolicy 값이 manual이 아니거나 inputMode 속성 값이 none이면 이 단계를 중단합니다.
시스템 API를 호출하여 VK를 숨깁니다.
병렬로 다음 단계를 수행합니다:
1. 시스템에서 가상 키보드가 숨겨질 때까지 기다립니다.
2. set the virtual keyboard bounding rect 를 키보드의 OS 보고 bounding rectangle(모든 값이 0), document의 viewport rectangle로 호출합니다.
3. 이벤트를 발생시키며 이름은 "geometrychange"이고 this에서 발생합니다.

Note

플랫폼 휴리스틱은 VK show() 및 hide()에 추가적인 제한을 둘 수 있습니다. 예를 들어, Windows에서는 포인터 타입이 MUST 터치 또는 펜이어야 합니다.

Note

일부 사용자는 우려를 표명했으며 show() 및 hide() 메서드가 프라미스 기반이 아니라고 지적했습니다. 하지만 VK 표시 여부가 변경될 때 ongeometrychange 이벤트가 발생하므로 반환값이 필요하지 않아 웹 개발자가 더 쉽게 사용할 수 있다고 봅니다.

overlaysContent

overlaysContent getter 단계는 this의 overlaysContent를 반환하는 것입니다.

overlaysContent setter 단계는 this의 overlaysContent를 주어진 값으로 설정하는 것입니다.

boundingRect

이 속성은 VK와 document의 viewport가 클라이언트 좌표에서 교차하는 부분을 보고합니다. set the virtual keyboard bounding rect를 호출합니다.

set the virtual keyboard bounding rect

set the virtual keyboard bounding rect를 설정하려면 osk(화면 키보드 사각형을 나타내는 DOMRect)와 lv(document의 viewport 사각형을 나타내는 DOMRect)를 입력값으로 받아 다음과 같이 실행합니다:

osk를 show() 또는 hide()의 결과로 얻은 화면 키보드 사각형으로 설정합니다.
lv를 document의 viewport로, show() 또는 hide()의 결과로 얻은 값으로 설정합니다.
osk를 lv의 좌표 공간으로 매핑합니다.
bounds를 DOMRect 객체로 만듭니다.
bounds를 lv와 osk의 교차 부분으로 갱신합니다.
bounds를 lv의 좌표 공간에 매핑합니다.
bounds를 반환합니다.

boundingRect getter 단계는 this의 boundingRect를 반환하는 것입니다.

ongeometrychange

VK와 document의 viewport의 교차가 변경될 때(예: VK가 표시/숨겨지거나 브라우저 창이 재배치되는 경우) 이벤트가 디스패치됩니다.

WebIDL partial interface mixin ElementContentEditable {
     [CEReactions] attribute DOMString virtualKeyboardPolicy;
};

이슈 1

input과 textarea 처리를 추가하세요.

virtualKeyboardPolicy는 열거형 속성이며, 키워드는 빈 문자열, auto, manual입니다. IDL 속성은 동일 이름의 콘텐츠 속성을 반영해야 합니다. contenteditable 호스트인 요소에 지정되면, auto는 해당 편집 가능한 요소가 포커스되거나 탭될 때 VK를 자동으로 표시하고, manual은 편집 가능한 요소의 포커스 및 탭 동작을 VK의 상태 변화와 분리하여 VK가 현재 상태를 유지하도록 합니다.
virtualKeyboardPolicy 속성 값의 변경은 auto에서 빈 문자열 또는 그 반대로 변경하는 경우를 제외하면 현재 정의된 동작을 무효화합니다.

이슈 2

포커스와 같은 이벤트와의 타이밍을 명시하세요.

auto 열거형 속성이 설정되면 VK는 브라우저가 처리합니다.
manual 열거형 속성이 설정되면 브라우저의 VK 기본 처리를 방지하며, 스크립트에서 직접 처리해야 합니다.
빈 문자열 열거형 속성이 설정되면 VK는 브라우저가 처리합니다.

이름	값
keyboard-inset-top	길이
keyboard-inset-right	길이
keyboard-inset-bottom	길이
keyboard-inset-left	길이
keyboard-inset-width	길이
keyboard-inset-height	길이

예시 1: VirtualKeyboardPolicy


<div contenteditable virtualkeyboardpolicy="manual" inputmode="text"
style="height:50px;width:300px;border:1px solid black;"data-formula="12+30">42</div>
<script>
    let div = document.querySelector("div")
    div.addEventListener("focusout", handleFocusOut)
    div.addEventListener("dblclick", handleDblClick)

    function handleFocusOut() {
        let formula = parseIntoFormula(div.firstChild.data)
        div.setAttribute("data-formula", formula)
        div.firstChild.data = evaluateFormula(formula)
    }

    function handleDblClick(e) {
        div.firstChild.data = div.getAttribute("data-formula")

        if (e.pointerType == "touch") {
            navigator.virtualKeyboard.show()
        }
    }

    function parseIntoFormula(text) {
        return "12+30"
    }

    function evaluateFormula(formula) {
        return "42"
    }

    function handleSuccessfulShow() {
        // VK 표시 성공 처리
    }

    function handleFailedShow() {
        // VK 표시 실패 처리
    }
</script>

예시 2: overlaysContent를 활용한 CSS 기반 콘텐츠 재배치


    <meta name="viewport" content="width=device-width, initial-scale=1">
    <style>
        body {
            display: grid;
            margin: 8px;
            height: calc(100vh - 16px);
            grid-template:
            "messages"  1fr
            "input"     auto
            "keyboard"  env(keyboard-inset-height, 0px);
        }
        input[type=text]::placeholder {
            color: #444;
        }
        input[type=text] {
            padding: 10px;
            font-size: 24px;
            border: 4px solid black;
            border-radius: 4px;
            background-color: #86DBF6;
            justify-self: center;
        }
    </style>
    <div id="messages">...</div>
    <input type="text" placeholder="type...">
    <script>
        if ("virtualKeyboard" in navigator) {
            navigator.virtualKeyboard.overlaysContent = true
        }
    </script>

아래 그림과 마크업은 VK가 표시될 때 활성 셀을 재배치하는 캔버스 기반 스프레드시트를 보여줍니다. geometrychange 이벤트가 캔버스의 페인트 요청을 트리거하며, 페인팅 코드는 boundingRect 속성을 활용해 활성 셀을 올바른 위치에 렌더링할 수 있습니다. 단일 터치 스크린 장치에서 가상 키보드가 표시된 그림

예시 3: JavaScript geometrychange 활용 콘텐츠 재배치


    <meta name="viewport" content="width=device-width, initial-scale=1">
    <style>
        body {
            display: grid;
            margin: 0;
            height: 100vh;
            grid-template:
            "controls" min-content
            "cells"    1fr;
        }
        #controls {
            height: 100px;
            background-color: #139CFF;
        }
        canvas {
            justify-self: stretch;
            align-self: stretch;
        }
    </style>
    <div id="controls">...</div>
    <canvas></canvas>
    <script type="module">
        navigator.virtualKeyboard.overlaysContent = true

        navigator.virtualKeyboard.addEventListener("geometrychange", () => {
            // VK 위로 활성 셀을 재배치할 수 있도록 캔버스 재페인트 요청
            requestAnimationFrame(paintCanvas)
        })

        paintCanvas() {
            let keyboardRect = navigator.virtualKeyboard.boundingRect
            // 생략된 코드에서 keyboardRect를 활용해 셀을 올바른 위치에 페인트합니다.
            // 사용자에 의해 셀 영역이 패닝된 경우도 반영합니다.
        }
    </script>

아래 그림은 지도 앱이 하나의 윈도우 세그먼트에 지도를, 다른 세그먼트에 검색 결과를 표시하는 구조를 보여줍니다. 윈도우 세그먼트 및 미디어 쿼리 제안과 함께, 검색 상자는 VK가 폴더블 장치의 왼쪽 화면에 표시될 때 항상 보이도록 하단 마진을 늘립니다. 단일 터치 스크린 장치에서 가상 키보드가 표시된 그림

예시 4: overlaysContent를 활용한 폴더블 장치 콘텐츠 재배치


    <meta name="viewport" content="width=device-width, initial-scale=1">
    <style>
        @media (spanning: single-fold-vertical) {
            body {
                display: grid;
                margin: 0;
                height: 100vh;
                grid-template-columns: env(fold-left) calc(100vw - env(fold-right));
                grid-column-gap: calc(env(fold-right) - env(fold-left));
            }
            .map {
                grid-column: 1;
                grid-row: 1;
            }
            .search-box {
            /* 지도와 동일한 그리드 컬럼에 overlay */
                grid-column: 1;
                grid-row: 1;

                /* 검색 상자를 셀 하단에 가운데 정렬 */
                align-self: end;

                /* VK가 왼쪽 화면에 없을 때 마진 */
                margin: 20px;

                /* 스타일 부여 */
                padding: 10px;
                font-size: 24px;
                border: 4px solid black;
                border-radius: 4px;
                background-color: #86DBF6;
            }
            .locations-list {
                grid-column: 2;
                grid-row: 1;
            }

            @media (env(keyboard-inset-right) <= env(fold-left)) {
            /* VK가 왼쪽 화면에 있을 때 검색 상자 마진 조정 */
                .search-box {
                    margin-bottom: calc(20px + env(keyboard-inset-height));
                }
            }
        }
    </style>
    <div class="map">...</div>
    <input class="search-box" type="search" placeholder="search...">
    <div class="locations-list">...</div>
    <script type="module">
        navigator.virtualKeyboard.overlaysContent = true
    </script>

VirtualKeyboard API는 사용자의 VK 레이아웃과 관련된 일부 정보를 노출할 수 있으므로, 사용자 에이전트는 이미 기존 API를 통해 스크립트가 가진 정보 외에 추가 정보가 노출되지 않도록 해야 합니다. 잠재적인 보안 및 프라이버시 위험을 완화하기 위해, 브라우저는 아래에 기술된 모범 사례를 따라야 합니다.

사용자 에이전트는 MUST hide() 및 show() 메서드를 보안 컨텍스트에서만 호출하도록 허용해야 합니다.
사용자 에이전트는 MUST show() 메서드가 sticky activation이 있을 때만 호출되도록 허용해야 합니다.

사용자 에이전트는 MUST overlaysContent가 보안 최상위 브라우징 컨텍스트에서만 설정되도록 허용해야 합니다.

VirtualKeyboard API

요약

문서 상태

1. 소개

2. 적합성

3. `VirtualKeyboard` 인터페이스

4. `ElementContentEditable` 믹스인 확장

5. 가상 키보드 표시 변경 CSS 환경 변수

5.1 키보드 인셋 변수

6. 예시

6.1 VK 제어 API 사용 예시

6.2 VK 표시 시 overlaysContent와 geometry 이벤트 활용 예시

7. 프라이버시 및 보안 고려사항

7.1 `hide()` 및 `show()` 메서드

7.2 `boundingRect`, `overlaysContent` 및 `ongeometrychange` 속성

A. IDL 색인

B. 기여자

C. 참고 문헌

C.1 규범 문헌

VirtualKeyboard API

요약

문서 상태

1. 소개

2. 적합성

3. VirtualKeyboard 인터페이스

4. ElementContentEditable 믹스인 확장

5. 가상 키보드 표시 변경 CSS 환경 변수

5.1 키보드 인셋 변수

6. 예시

6.1 VK 제어 API 사용 예시

6.2 VK 표시 시 overlaysContent와 geometry 이벤트 활용 예시

7. 프라이버시 및 보안 고려사항

7.1 hide() 및 show() 메서드

7.2 boundingRect, overlaysContent 및 ongeometrychange 속성

A. IDL 색인

B. 기여자

C. 참고 문헌

C.1 규범 문헌

3. `VirtualKeyboard` 인터페이스

4. `ElementContentEditable` 믹스인 확장

7.1 `hide()` 및 `show()` 메서드

7.2 `boundingRect`, `overlaysContent` 및 `ongeometrychange` 속성