태블릿이나 휴대전화와 같은 기기에는 일반적으로 텍스트를 입력하기 위한 가상 키보드가 있습니다.
항상 존재하고 항상 동일한 물리적 키보드와 달리 가상 키보드는 사용자의 작업에 따라 표시되고 사라지며, inputmode
속성을 기반으로 동적으로 조정할 수도 있습니다.
이러한 유연성은 브라우저의 레이아웃 엔진에 가상 키보드의 존재를 알리고 이를 보상하기 위해 문서의 레이아웃을 조정해야 할 수 있다는 단점이 있습니다. 예를 들어 사용자가 입력하려는 입력란이 가상 키보드로 가려져 있을 수 있으므로 브라우저에서 스크롤하여 입력란을 표시해야 합니다.
전통적으로 브라우저는 이 문제를 자체적으로 처리했지만, 더 복잡한 애플리케이션의 경우 브라우저 동작을 더 세부적으로 제어해야 할 수 있습니다. 예를 들어 가상 키보드가 하나의 화면 세그먼트에만 표시되는 경우 기존 접근 방식을 사용하면 화면 공간이 '낭비'되지만 사용 가능한 뷰포트는 두 화면 모두에서 축소되는 멀티스크린 휴대기기가 있습니다. 아래 이미지는 VirtualKeyboard API를 사용하여 문서의 레이아웃을 동적으로 최적화하여 가상 키보드의 존재를 보완하는 방법을 보여줍니다.
이러한 상황에서 VirtualKeyboard API가 사용됩니다. 다음 세 부분으로 구성됩니다.
- JavaScript에서 가상 키보드에 프로그래매틱 방식으로 액세스하기 위한
navigator
객체의VirtualKeyboard
인터페이스입니다. - 가상 키보드의 모양에 관한 정보를 제공하는 CSS 환경 변수 집합입니다.
- 가상 키보드를 표시할지 결정하는 가상 키보드 정책입니다.
현재 상태
VirtualKeyboard API는 데스크톱 및 모바일의 Chromium 94부터 사용할 수 있습니다.
기능 감지 및 브라우저 지원
현재 브라우저에서 VirtualKeyboard API가 지원되는지 감지하려면 다음 스니펫을 사용하세요.
if ('virtualKeyboard' in navigator) {
// The VirtualKeyboard API is supported!
}
VirtualKeyboard API 사용
VirtualKeyboard API는 navigator
객체에 새 인터페이스 VirtualKeyboard
를 추가합니다.
새로운 가상 키보드 동작 선택
브라우저에 가상 키보드 가림을 직접 처리하고 있다고 알리려면 먼저 불리언 속성 overlaysContent
를 true
로 설정하여 새 가상 키보드 동작을 선택해야 합니다.
navigator.virtualKeyboard.overlaysContent = true;
가상 키보드 표시 및 숨기기
show()
메서드를 호출하여 프로그래매틱 방식으로 가상 키보드를 표시할 수 있습니다. 이렇게 하려면 포커스가 있는 요소가 양식 컨트롤(예: textarea
요소)이거나 수정 호스트(예: contenteditable
속성 사용)여야 합니다. 이 메서드는 항상 undefined
를 반환하지만 이전에 가상 키보드가 표시되지 않은 경우 geometrychange
이벤트를 트리거합니다.
navigator.virtualKeyboard.show();
가상 키보드를 숨기려면 hide()
메서드를 호출합니다. 이 메서드는 항상 undefined
를 반환하지만 이전에 가상 키보드가 표시된 경우 geometrychange
이벤트를 트리거합니다.
navigator.virtualKeyboard.hide();
현재 도형 가져오기
boundingRect
속성을 확인하여 가상 키보드의 현재 도형을 가져올 수 있습니다.
가상 키보드의 현재 크기를 DOMRect
객체로 노출합니다.
inset은 top, right, bottom 또는 left 속성에 해당합니다.
const { x, y, width, height } = navigator.virtualKeyboard.boundingRect;
console.log('Virtual keyboard geometry:', x, y, width, height);
도형 변경사항 알림 받기
가상 키보드가 표시되거나 사라질 때마다 geometrychange
이벤트가 전달됩니다. 이벤트의 target
속성에는 위에서 설명한 대로 가상 키보드 인셋의 새 도형을 DOMRect
로 포함하는 virtualKeyboard
객체가 포함됩니다.
navigator.virtualKeyboard.addEventListener('geometrychange', (event) => {
const { x, y, width, height } = event.target.boundingRect;
console.log('Virtual keyboard geometry changed:', x, y, width, height);
});
CSS 환경 변수
VirtualKeyboard API는 가상 키보드의 모양에 관한 정보를 제공하는 CSS 환경 변수 집합을 노출합니다.
inset
CSS 속성과 유사하게 모델링되며, 즉, top, right, bottom 또는 left 속성에 해당합니다.
keyboard-inset-top
keyboard-inset-right
keyboard-inset-bottom
keyboard-inset-left
keyboard-inset-width
keyboard-inset-height
가상 키보드 인셋은 표시 영역 가장자리에서 상단, 오른쪽, 하단, 왼쪽 인셋으로 직사각형을 정의하는 6개의 환경 변수입니다. 너비 및 높이 인셋은 개발자 인체공학을 위해 다른 인셋에서 계산됩니다. 대체 값이 제공되지 않은 경우 각 키보드 인셋의 기본값은 0px
입니다.
일반적으로 환경 변수는 아래 예와 같이 사용합니다.
.some-class {
/**
* Use a margin that corresponds to the virtual keyboard's height
* if the virtual keyboard is shown, else use the fallback value of `50px`.
*/
margin-block-end: env(keyboard-inset-height, 50px);
}
.some-other-class {
/**
* Use a margin that corresponds to the virtual keyboard's height
* if the virtual keyboard is shown, else use the default fallback value of `0px`.
*/
margin-block-end: env(keyboard-inset-height);
}
가상 키보드 정책
수정 가능한 요소에 포커스가 있을 때 가상 키보드가 표시되지 않아야 하는 경우가 있습니다. 한 예로 사용자가 셀을 탭하여 값을 다른 셀의 수식에 포함할 수 있는 스프레드시트 애플리케이션이 있습니다. virtualkeyboardpolicy
는 키워드가 auto
및 manual
문자열인 속성입니다. contenteditable
호스트인 요소에 지정된 경우 auto
는 포커스가 있거나 탭할 때 수정 가능한 상응하는 요소에서 가상 키보드를 자동으로 표시하도록 하고, manual
는 가상 키보드의 현재 상태 변경에서 포커스를 분리하고 수정 가능한 요소를 탭합니다.
<!-- Do nothing on regular focus, but show the virtual keyboard on double-click. -->
<div
contenteditable
virtualkeyboardpolicy="manual"
inputmode="text"
ondblclick="navigator.virtualKeyboard.show();"
>
Double-click to edit.
</div>
데모
Glitch의 데모에서 VirtualKeyboard API가 작동하는 모습을 확인할 수 있습니다. 소스 코드를 살펴보고 구현 방법을 확인하세요.
geometrychange
이벤트는 iframe 삽입에서 관찰할 수 있지만 실제 가상 키보드 동작을 보려면 자체 브라우저 탭에서 데모를 열어야 합니다.
유용한 링크
감사의 말씀
VirtualKeyboard API는 Microsoft의 Anupam Snigdha가 지정하고 전 편집자인 Grisha Lyukshin과 마찬가지로 Microsoft의 도움을 받아 작성되었습니다.