Keyboard Lock API로 키 캡처

양방향 웹사이트, 게임, 원격 데스크톱 또는 애플리케이션 스트리밍을 비롯한 다양한 사용 사례에 몰입도 높은 전체 화면 환경을 제공합니다.

Thomas Steiner

점점 더 많은 사용자가 브라우저에서 대부분의 시간을 보내면서 양방향 웹사이트, 게임, 원격 데스크톱 스트리밍, 애플리케이션 스트리밍은 몰입도 높은 전체 화면 환경을 제공하기 위해 노력하고 있습니다. 이를 위해 사이트는 전체 화면 모드에서 특수 키와 단축키에 액세스하여 탐색, 메뉴 또는 게임에 사용할 수 있어야 합니다. 필요한 키의 예로는 Esc, Alt + Tab, Cmd + `, Ctrl + N 등이 있습니다.

기본적으로 이러한 키는 브라우저나 기본 운영체제에서 캡처하므로 웹 애플리케이션에서 사용할 수 없습니다. Keyboard Lock API를 사용하면 웹사이트에서 호스트 OS에서 허용하는 모든 키를 사용할 수 있습니다 (브라우저 호환성 참고).

macOS Chrome의 브라우저 탭에 스트리밍된 Ubuntu Linux (아직 전체 화면 모드로 실행되지 않음)
문제: 스트리밍된 Ubuntu Linux 원격 데스크톱이 전체 화면 모드로 실행되지 않고 활성 키보드 잠금이 없으므로 시스템 키가 여전히 macOS 호스트 운영체제에 의해 캡처되고 아직 몰입도 높은 환경을 제공하지 않습니다.

Keyboard Lock API 사용

Keyboard API의 Keyboard 인터페이스는 물리적 키보드의 키 누르기 캡처를 전환하고 사용자의 키보드 레이아웃에 관한 정보를 가져오는 함수를 제공합니다.

기본 요건

최신 브라우저에서는 Fullscreen API를 통해 JavaScript에서 시작된 전체 화면과 키보드 단축키를 통해 사용자가 시작한 전체 화면의 두 가지 유형을 사용할 수 있습니다. Keyboard Lock API는 JavaScript에서 시작된 전체 화면이 활성화된 경우에만 사용할 수 있습니다. 다음은 JavaScript에서 시작된 전체 화면의 예입니다.

await document.documentElement.requestFullscreen();

기능 감지

다음 패턴을 사용하여 Keyboard Lock API가 지원되는지 확인할 수 있습니다.

if ('keyboard' in navigator && 'lock' in navigator.keyboard) {
  // Supported!
}

키보드 잠금

Keyboard 인터페이스의 lock() 메서드는 물리적 키보드의 일부 또는 모든 키에 대한 키 누르기 캡처를 사용 설정한 후 프로미스를 반환합니다. 이 메서드는 기본 운영체제에서 액세스 권한을 부여한 키만 캡처할 수 있습니다. lock() 메서드는 잠글 키 코드 배열을 1개 이상 취합니다. 키 코드를 제공하지 않으면 모든 키가 잠깁니다. 유효한 키 코드 값 목록은 UI 이벤트 KeyboardEvent 코드 값 사양에서 확인할 수 있습니다.

모든 키 캡처

다음 예에서는 모든 키 누르기를 캡처합니다.

navigator.keyboard.lock();

특정 키 캡처

다음 예에서는 W, A, S, D 키를 캡처합니다. 키 누름에 사용되는 수정자에 관계없이 이러한 키를 캡처합니다. 미국 QWERTY 레이아웃을 가정하면 "KeyW"를 등록하면 W, Shift + W, Control + W, Control + Shift + W, W가 포함된 기타 모든 키 조합이 앱에 전송됩니다. "KeyA", "KeyS", "KeyD"에도 동일하게 적용됩니다.

await navigator.keyboard.lock([
  "KeyW",
  "KeyA",
  "KeyS",
  "KeyD",
]);

키보드 이벤트를 사용하여 캡처된 키 누르기에 응답할 수 있습니다. 예를 들어 다음 코드는 onkeydown 이벤트를 사용합니다.

document.addEventListener('keydown', (event) => {
  if ((event.code === 'KeyA') && !(event.ctrlKey || event.metaKey)) {
    // Do something when the 'A' key was pressed, but only
    // when not in combination with the command or control key.
  }
});

키보드 잠금 해제

unlock() 메서드는 lock() 메서드에 의해 캡처된 모든 키를 잠금 해제하고 동기식으로 반환합니다.

navigator.keyboard.unlock();

문서가 닫히면 브라우저는 항상 암시적으로 unlock()를 호출합니다.

데모

Glitch에서 데모를 실행하여 Keyboard Lock API를 테스트할 수 있습니다. 소스 코드를 확인해야 합니다. 아래의 전체 화면으로 전환 버튼을 클릭하면 새 창에서 데모가 실행되어 전체 화면 모드로 전환됩니다.

보안 고려사항

이 API의 한 가지 문제는 모든 키를 가져오고 Fullscreen API 및 PointerLock API와 함께 사용자가 웹페이지를 종료하지 못하도록 하는 데 사용할 수 있다는 점입니다. 이를 방지하기 위해 사양에서는 API에서 모든 키를 요청하더라도 사용자가 키보드 잠금을 해제할 수 있는 방법을 브라우저에서 제공하도록 요구합니다. Chrome에서 이 이스케이프 해치는 Esc 키를 길게 (2초) 눌러 키보드 잠금에서 종료되도록 트리거하는 것입니다.

감사의 말씀

이 도움말은 조 미들리와 케이스 바스케스가 검토했습니다. 키보드 잠금 사양은 게리 카크마르치크와 제이미 월치가 작성했습니다. Unsplash의 켄 수아레스님 제공 히어로 이미지