이 페이지는 Cloud Translation API를 통해 번역되었습니다.

VirtualKeyboard API를 사용한 완전한 제어

Thomas Steiner

브라우저 지원

태블릿이나 휴대전화와 같은 기기에는 일반적으로 텍스트를 입력하기 위한 가상 키보드가 있습니다. 항상 표시되고 항상 동일한 물리적 키보드와 달리 가상 키보드는 사용자의 작업에 따라 표시되고 사라지며, 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가 지정했으며 Microsoft의 전 편집자 Grisha Lyukshin도 참여했습니다.