설명
commands 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,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.
}
});
}
유형
Command
속성
-
설명
문자열 선택사항
확장 프로그램 명령어 설명
-
이름
문자열 선택사항
확장 프로그램 명령어의 이름
-
단축키
문자열 선택사항
이 명령어에 대해 활성 상태인 바로가기 또는 활성 상태가 아닌 경우 비어 있습니다.
메서드
getAll()
chrome.commands.getAll(
callback?: function,
)
이 확장 프로그램에 등록된 모든 확장 프로그램 명령어와 바로가기 (활성 상태인 경우)를 반환합니다. Chrome 110 이전에는 이 명령어가 _execute_action를 반환하지 않았습니다.
반환 값
-
Promise<Command[]>
Chrome 96 이상Promise는 매니페스트 V3 이상에서 지원되지만 이전 버전과의 호환성을 위해 콜백이 제공됩니다. 동일한 함수 호출에서 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.