설명
명령어 API를 사용하여 확장 프로그램에서 작업(예: 브라우저 작업을 열거나 확장 프로그램에 명령어를 전송하는 작업)을 트리거하는 단축키를 추가할 수 있습니다.
매니페스트
개념 및 사용법
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(macOS의 경우Option),Shift,MacCtrl(macOS만 해당),Command(macOS만 해당),Search(ChromeOS만 해당)
키 조합 요구사항
확장 프로그램 명령어 단축키에는
Ctrl또는Alt가 포함되어야 합니다.- 수정자는 미디어 키와 함께 사용할 수 없습니다.
macOS에서
Ctrl는 자동으로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.
}
});
}
유형
Command
속성
-
설명
문자열 선택사항
확장 프로그램 명령어 설명
-
이름
문자열 선택사항
확장 프로그램 명령어의 이름입니다.
-
단축키
문자열 선택사항
이 명령어에 대해 활성화된 단축키입니다. 활성화되지 않은 경우 비어 있습니다.
방법
getAll()
chrome.commands.getAll(
callback?: function,
)
이 확장 프로그램과 바로가기 (활성 상태인 경우)에 등록된 모든 확장 프로그램 명령어를 반환합니다. Chrome 110 이전에는 이 명령어가 _execute_action를 반환하지 않았습니다.
반환 값
-
프로미스<Command[]>
Chrome 96 이상프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.