chrome.commands

설명

매니페스트

개념 및 사용

Commands API를 사용하면 확장 프로그램 개발자가 특정 명령어를 정의하고 기본 키 조합에 바인딩할 수 있습니다. 확장 프로그램이 허용하는 각 명령어는 확장 프로그램의 매니페스트에서 "commands" 객체의 속성으로 선언해야 합니다.

속성 키는 명령어의 이름으로 사용됩니다. 명령어 객체는 두 가지 속성을 사용할 수 있습니다.

suggested_key

명령어의 기본 단축키를 선언하는 선택적 속성입니다. 생략하면 명령어가 바인딩 해제됩니다. 이 속성은 문자열 또는 객체 값을 사용할 수 있습니다.

• 문자열 값은 모든 플랫폼에서 사용해야 하는 기본 단축키를 지정합니다.

• 객체 값을 사용하면 확장 프로그램 개발자가 각 플랫폼의 단축키를 맞춤설정할 수 있습니다. 플랫폼별 단축키를 제공할 때 유효한 객체 속성은 default, chromeos, linux, mac, windows입니다.

자세한 내용은 키 조합 요구사항을 참고하세요.

description

사용자에게 명령어의 목적에 관한 간단한 설명을 제공하는 데 사용되는 문자열입니다. 이 문자열은 확장 프로그램 단축키 관리 UI에 표시됩니다. 설명은 표준 명령어에 필요하지만 작업 명령어에서는 무시됩니다.

확장 프로그램에는 여러 명령어가 있을 수 있지만 최대 4개의 추천 단축키를 지정할 수 있습니다. 사용자는 chrome://extensions/shortcuts 대화상자에서 바로가기를 직접 추가할 수 있습니다.

지원되는 키

다음 키는 사용 가능한 명령어 단축키입니다. 키 정의는 대소문자를 구분합니다. 잘못된 대소문자가 적용된 키로 확장 프로그램을 로드하려고 하면 설치 시 매니페스트 파싱 오류가 발생합니다.

알파 키

A … Z

숫자 키

0 … 9

표준 키 문자열

일반: Comma, Period, Home, End, PageUp, PageDown, Space, Insert, Delete

화살표 키: Up, Down, Left, Right

미디어 키: MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop

특수키 문자열

Ctrl, Alt, Shift, MacCtrl (macOS만 해당), Command (macOS만 해당), Search (ChromeOS만 해당)

키 조합 요구사항

• 확장 프로그램 명령어 단축키에는 Ctrl 또는 Alt이 포함되어야 합니다.

  • 수정자는 미디어 키와 함께 사용할 수 없습니다.

  • 많은 macOS 키보드에서 Alt는 Option 키를 나타냅니다.

  • macOS에서는 Ctrl 또는 Alt 대신 Command 또는 MacCtrl을 사용할 수도 있습니다 (다음 글머리 기호 참고).

• macOS에서는 Ctrl이 자동으로 Command로 변환됩니다.

  • Command는 "mac" 단축키에서 Command 키를 명시적으로 참조하는 데 사용할 수도 있습니다.

  • macOS에서 Control 키를 사용하려면 "mac" 단축키를 정의할 때 Ctrl를 MacCtrl로 바꿉니다.

  • 다른 플랫폼의 조합에 MacCtrl를 사용하면 유효성 검사 오류가 발생하고 확장 프로그램을 설치할 수 없습니다.

• Shift은 모든 플랫폼에서 선택사항인 수정자입니다.

• Search는 ChromeOS 전용 선택적 수정자입니다.

• 특정 운영체제 및 Chrome 단축키 (예: 창 관리)는 항상 확장 프로그램 명령 단축키보다 우선순위가 높으며 재정의할 수 없습니다.

명령 이벤트 처리

manifest.json:

{   "name": "My extension",   ...   "commands": {     "run-foo": {       "suggested_key": {         "default": "Ctrl+Shift+Y",         "mac": "Command+Shift+Y"       },       "description": "Run \"foo\" on the current page."     },     "_execute_action": {       "suggested_key": {         "windows": "Ctrl+Shift+Y",         "mac": "Command+Shift+Y",         "chromeos": "Ctrl+Shift+U",         "linux": "Ctrl+Shift+J"       }     }   },   ... } 

서비스 워커에서 onCommand.addListener를 사용하여 매니페스트에 정의된 각 명령어에 핸들러를 바인딩할 수 있습니다. 예를 들면 다음과 같습니다.

service-worker.js:

chrome.commands.onCommand.addListener((command) => {   console.log(`Command: ${command}`); }); 

작업 명령어

_execute_action (Manifest V3), _execute_browser_action (Manifest V2), _execute_page_action (Manifest V2) 명령어는 각각 작업, 브라우저 작업 또는 페이지 작업을 트리거하는 작업에 예약되어 있습니다. 이러한 명령어는 표준 명령어와 같이 command.onCommand 이벤트를 디스패치하지 않습니다.

팝업이 열리는 것을 기반으로 조치를 취해야 하는 경우 팝업의 JavaScript 내에서 DOMContentLoaded 이벤트를 수신하는 것이 좋습니다.

범위

기본적으로 명령어는 Chrome 브라우저로 범위가 지정됩니다. 즉, 브라우저에 포커스가 없으면 명령 단축키가 비활성 상태가 됩니다. Chrome 35부터 확장 프로그램 개발자는 명령어를 '전역'으로 표시할 수 있습니다. Chrome에 포커스가 없는 동안에도 전역 명령어가 작동합니다.

전역 명령의 단축키 제안은 Ctrl+Shift+[0..9]로 제한됩니다. 이는 다른 애플리케이션에서 단축키를 재정의할 위험을 최소화하기 위한 보호 조치입니다. 예를 들어 Alt+P이 전역으로 허용되면 인쇄 대화상자를 여는 단축키가 다른 애플리케이션에서 작동하지 않을 수 있습니다.

최종 사용자는 chrome://extensions/shortcuts에 노출된 UI를 사용하여 전역 명령어를 원하는 키 조합에 자유롭게 매핑할 수 있습니다.

예:

manifest.json:

{   "name": "My extension",   ...   "commands": {     "toggle-feature-foo": {       "suggested_key": {         "default": "Ctrl+Shift+5"       },       "description": "Toggle feature foo",       "global": true     }   },   ... } 

예

다음 예에서는 Commands API의 핵심 기능을 유연하게 사용합니다.

기본 명령어

명령어를 사용하면 확장 프로그램이 사용자가 호출할 수 있는 단축키에 로직을 매핑할 수 있습니다. 가장 기본적인 경우 명령어에는 확장 프로그램의 매니페스트에 명령어 선언과 리스너 등록만 필요합니다(다음 예 참고).

manifest.json:

{   "name": "Command demo - basic",   "version": "1.0",   "manifest_version": 3,   "background": {     "service_worker": "service-worker.js"   },   "commands": {     "inject-script": {       "suggested_key": "Ctrl+Shift+Y",       "description": "Inject a script on the page"     }   } } 

service-worker.js:

chrome.commands.onCommand.addListener((command) => {   console.log(`Command "${command}" triggered`); }); 

작업 명령어

개념 및 사용 섹션에 설명된 대로 명령어를 확장 프로그램의 작업에 매핑할 수도 있습니다. 다음 예에서는 사용자가 확장 프로그램의 작업을 클릭하거나 단축키를 트리거할 때 현재 페이지에 알림을 표시하는 콘텐츠 스크립트를 삽입합니다.

manifest.json:

{   "name": "Commands demo - action invocation",   "version": "1.0",   "manifest_version": 3,   "background": {     "service_worker": "service-worker.js"   },   "permissions": ["activeTab", "scripting"],   "action": {},   "commands": {     "_execute_action": {       "suggested_key": {         "default": "Ctrl+U",         "mac": "Command+U"       }     }   } } 

service-worker.js:

chrome.action.onClicked.addListener((tab) => {   chrome.scripting.executeScript({     target: {tabId: tab.id},     func: contentScriptFunc,     args: ['action'],   }); });  function contentScriptFunc(name) {   alert(`"${name}" executed`); }  // This callback WILL NOT be called for "_execute_action" chrome.commands.onCommand.addListener((command) => {   console.log(`Command "${command}" called`); }); 

등록된 명령어 확인

확장 프로그램이 다른 확장 프로그램에서 이미 사용 중인 단축키를 등록하려고 하면 두 번째 확장 프로그램의 단축키가 예상대로 등록되지 않습니다. 이 가능성을 예상하고 설치 시 충돌을 확인하여 더 강력한 최종 사용자 환경을 제공할 수 있습니다.

service-worker.js:

chrome.runtime.onInstalled.addListener((details) => {   if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {     checkCommandShortcuts();   } });  // Only use this function during the initial install phase. After // installation the user may have intentionally unassigned commands. function checkCommandShortcuts() {   chrome.commands.getAll((commands) => {     let missingShortcuts = [];      for (let {name, shortcut} of commands) {       if (shortcut === '') {         missingShortcuts.push(name);       }     }      if (missingShortcuts.length > 0) {       // Update the extension UI to inform the user that one or more       // commands are currently unassigned.     }   }); } 

chrome.commands.getAll(): Promise<Command[]>

chrome.commands.onCommand.addListener(
  callback: function,
)