Keyboard Lock API로 키 캡처

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

Thomas Steiner

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

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

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

Keyboard Lock API 사용

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

기본 요건

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

await document.documentElement.requestFullscreen();

특성 인식

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

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

키보드 잠금

Keyboard 인터페이스의 lock() 메서드는 실제 키보드의 일부 또는 모든 키에 대한 키 누름 캡처를 사용 설정한 후 프로미스를 반환합니다. 이 메서드는 기본 운영체제에서 액세스 권한이 부여된 키만 캡처할 수 있습니다. lock() 메서드는 잠글 키 코드 하나 이상의 배열을 사용합니다. 키 코드가 제공되지 않으면 모든 키가 잠깁니다. 유효한 키 코드 값 목록은 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()를 호출합니다.

데모

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

보안 고려사항

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

감사의 말씀

이 도움말은 조 메들리와 케이시 바스크가 검토했습니다. 키보드 잠금 사양은 Gary Kacmarcik과 Jamie Walch가 작성했습니다.