확장앱에 단축키 설정하기

단축키 API를 이용해 확장앱에 다양한 단축키 기능을 간단하게 구현할 수 있습니다.

매니페스트 설정

단축키 API를 사용하려면 먼저 매니페스트 파일에 아래와 같이 commands 항목을 추가해야 합니다.

"commands": {
"test": {
"suggested_key": {
"default": "Ctrl+Shift+J",
"mac": "Command+Shift+J"
},
"description": "Test alert function"
}
}

위 예제에서 test는 임의로 정한 단축키 이름입니다. 이 부분에는 test 외에 단축키 입력 탐지시 구분할 수 있는 적당한 이름이라면 어떤 것이든 설정할 수 있습니다. suggested_key 항목의 하위 항목에 각 운영체제별로 다른 키 조합을 지정할 수 있습니다. 기본값(default)으로 설정한 키 조합은 특별히 다른 조합을 지정하지 않은 모든 운영체제에서 동작합니다. 그 외에 각각 windows, mac, linux 항목을 지정하여 운영체제별 사용자 경험에 적합한 단축키 조합을 다르게 지정할 수 있습니다. 위 예제는 test 단축키를 맥 운영체제에서는 Command ⌘ 키, 윈도우 · 리눅스 등 그 외의 환경에서는 Ctrl 키와 조합하도록 설정한 것입니다.

만약 개발 도중 단축키를 바꾸기로 결정한 경우 단순히 개발자 모드에서 확장앱을 새로고침 하는 것 만으로는 충분치 않을 수 있습니다. 확장앱을 삭제하고 다시 설치해야 변경한 단축키 설정이 적용됩니다.

설정 가능한 키 조합

suggested_key 하위 항목에서 지정할 수 있는 키 조합 표현은 아래와 같습니다.

  • A-Z, 0-9, Comma(,), Period(.)
  • Home, End, PageUp, PageDown, Insert, Delete, Tab, Command
  • Up(↑), Down(↓), Left(←), Right(→)
  • MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop

모든 키 조합은 반드시 Alt 또는 Ctrl (맥 환경에서는 Cmd) 조합을 포함해야 합니다. 단:

  • AltCtrl 키를 하나의 조합에 둘 다 포함할 수 없습니다
  • MediaNextTrack, MediaPlayPause 등 미디어 키는 Alt 또는 Ctrl 과 조합할 수 없습니다

키 조합에 Ctrl키를 설정한 경우, 맥 환경에서는 자동으로 Command로 변환하여 동작합니다.
만약 맥 환경에서도 꼭 Ctrl 키를 지정하려면 MacCtrl로 구분하여 지정해야 합니다.

단축키의 우선 순위

브라우저의 단축키 설정은 확장앱의 단축키 설정보다 우선합니다. 만약 브라우저에서 이미 사용중인 단축키를 확장앱에서 지정하더라도 확장앱이 아닌 브라우저의 단축키 동작만 수행됩니다. 그러므로 확장앱 단축키 조합을 지정할 때 설정 > 단축키 항목을 참조하여 기본 단축키와 겹치지 않는지 확인해야 합니다. 더불어, 웨일 브라우저에서는 사용자가 누구든 브라우저 단축키 조합을 변경하거나 추가할 수 있는 기능을 제공하므로 의도치 않게 어떤 사용자는 자신의 브라우저 단축키 설정으로 인해 여러분이 제공하는 확장앱 단축키가 동작하지 않을 수 있습니다. 만약 사용자가 단축키가 동작하지 않는다고 불평하면 혹시 겹치는 설정이 없는지 확인하도록 안내하세요.

단축키 입력 탐지

백그라운드 스크립트에서 아래와 같이 단축키 API의 이벤트 핸들러 함수를 통해 사용자의 단축키 입력을 탐지할 수 있습니다. onCommand 이벤트 핸들러의 첫 번째 인자는 위에서 매니페스트에 commands 항목에 설정했던 단축키 이름입니다.

whale.commands.onCommand.addListener(function (command) {
if (command === `test`) {
alert('컨트롤 쉬프트 제이를 누르셨군요!');
}
});

단축키 이름의 예약어

매니페스트에 browser_action, page_action 혹은 sidebar_action 을 설정한 경우, 단축키 이름을 특별히 정해진 이름으로 지정하면 따로 백그라운드 스크립트에서 입력을 탐지하지 않아도 각각 툴바(browserAction, pageAction) 또는 사이드바(sidebarAction) 버튼을 클릭한 것과 같은 동작을 하게 할 수 있습니다.

매니페스트 키 단축키 이름
browser_action _execute_browser_action
page_action _execute_page_action
sidebar_action _execute_sidebar_action

예를 들어, 툴바에 버튼을 추가하고 버튼을 클릭하거나 단축키를 누르면 팝업창을 표시하기 위해서는 아래와 같이 매니페스트와 백그라운드 스크립트를 작성하게 됩니다.

{
"browser_action": {
"default_title": "Open Popup",
"default_popup": "popup.html"
},
"background": {
"scripts": ["background.js"]
},
"commands": {
"open-popup": {
"suggested_key": {
"default": "Ctrl+Shift+Y"
}
}
}
}
background.js
whale.commands.onCommand.addListener(function (command) {
if (command === `open-popup`) {
whale.browserAction.setPopup({
popup: whale.runtime.getManifest().browser_action.default_popup
});
}
});

위 구현은 아래와 같이 단축키 이름에 예약어 _execute_browser_action를 사용하면 백그라운드 스크립트 구현을 생략할 수 있습니다.

{
"browser_action": {
"default_title": "Open Popup",
"default_popup": "popup.html"
},
"commands": {
"_execute_browser_action": {
"suggested_key": {
"default": "Ctrl+Shift+Y"
}
}
}
}

북마크 다루기 방문기록 다루기