설명
명령어 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 이벤트를 사용해 보세요.
팝업 열기에 따라 조치를 취해야 하는 경우 DOMContentLoaded 이벤트를 수신할 수 있습니다.
범위
기본적으로 명령어의 범위는 Chrome 브라우저로 지정됩니다. 즉, 브라우저가 명령 단축키가 비활성화됩니다. Chrome 35부터 확장 프로그램 개발자는 원하는 경우 명령어를 '전역'으로 표시합니다. Chrome에 포커스가 없는 경우에도 전역 명령어가 작동합니다.
전역 명령어의 단축키 추천은 Ctrl+Shift+[0..9]로 제한됩니다. 이것은
다른 응용 프로그램의 바로가기를 재정의하는 위험을 최소화하기 위한 보호 조치
예를 들어 Alt+P는 인쇄 대화상자를 열기 위한 단축키인 전역으로 허용되어야 했습니다.
다른 애플리케이션에서는 작동하지 않을 수 있습니다.
최종 사용자는 노출된 UI를 사용하여 원하는 키 조합에 전역 명령을 자유롭게 재매핑할 수 있습니다.
chrome://extensions/shortcuts
예:
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 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.