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 (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부터 확장 프로그램 개발자는 선택적으로 명령어를 'global'로 표시할 수 있습니다. 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(
  callback?: function,
)

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