chrome.contextMenus

설명

chrome.contextMenus API를 사용하여 Chrome 컨텍스트 메뉴에 항목을 추가하세요. 이미지, 하이퍼링크, 페이지 등 컨텍스트 메뉴에 추가할 객체의 유형을 선택할 수 있습니다.

권한

contextMenus

API를 사용하려면 확장 프로그램의 매니페스트에서 "contextMenus" 권한을 선언해야 합니다. 또한 메뉴 항목 옆에 표시할 16x16픽셀 아이콘을 지정해야 합니다. 예를 들면 다음과 같습니다.

{
  "name": "My extension",
  ...
  "permissions": [
    "contextMenus"
  ],
  "icons": {
    "16": "icon-bitty.png",
    "48": "icon-small.png",
    "128": "icon-large.png"
  },
  ...
}

개념 및 사용법

컨텍스트 메뉴 항목은 file://이 있는 문서를 포함하여 모든 문서 (또는 문서 내 프레임)에 표시될 수 있습니다. 또는 chrome:// URL로 구성됩니다. 항목을 표시할 수 있는 문서를 제어하려면 create() 또는 update() 메서드를 호출할 때의 documentUrlPatterns 필드

컨텍스트 메뉴 항목을 필요한 만큼 만들 수 있지만 확장 프로그램에서 하나 이상의 한 번에 표시되는 경우 Chrome은 자동으로 하나의 상위 메뉴로 축소합니다.

예

이 API를 사용하려면 chrome-extension-samples에서 contextMenus API 예를 설치하세요. 저장소

유형

ContextType

Chrome 44 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

메뉴가 표시될 수 있는 다양한 컨텍스트 'all' 지정 '런처'를 제외한 다른 모든 컨텍스트의 조합과 동일합니다. '런처' 컨텍스트는 앱에서만 지원되며 런처/작업 표시줄/도크 등에서 앱 아이콘을 클릭할 때 표시되는 컨텍스트 메뉴에 메뉴 항목을 추가하는 데 사용됩니다. 플랫폼에 따라 런처 컨텍스트 메뉴에서 실제로 지원되는 항목이 제한될 수 있습니다.

열거형

'모두'

'페이지'

"프레임"

"선택"

"링크"

"수정 가능"

"이미지"

"동영상"

"오디오"

"런처"

"browser_action"

"page_action"

"작업"

CreateProperties

Chrome 123 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

새 컨텍스트 메뉴 항목의 속성

속성

  • 선택됨

    불리언 선택사항

    체크박스 또는 라디오 버튼의 초기 상태입니다. 선택된 경우 true, 선택 해제된 경우 false입니다. 특정 그룹에서 한 번에 하나의 라디오 버튼만 선택할 수 있습니다.

  • contexts

    [ContextType, ...ContextType[]] 선택사항

    이 메뉴 항목이 표시될 컨텍스트 목록입니다. 기본값은 ['page']입니다.

  • documentUrlPatterns

    string[] 선택사항

    URL이 지정된 패턴 중 하나와 일치하는 문서 또는 프레임에만 적용되도록 항목을 제한합니다. 패턴 형식에 관한 자세한 내용은 패턴 일치를 참고하세요.

  • 사용 설정됨

    불리언 선택사항

    이 컨텍스트 메뉴 항목의 사용 설정 여부입니다. 기본값은 true입니다.

  • id

    문자열(선택사항)

    이 항목에 할당할 고유 ID입니다. 이벤트 페이지의 필수 속성입니다. 이 확장 프로그램의 다른 ID와 같을 수 없습니다.

  • parentId

    string | 숫자 선택사항

    상위 메뉴 항목의 ID입니다. 그러면 항목이 이전에 추가된 항목의 하위 요소가 됩니다.

  • targetUrlPatterns

    string[] 선택사항

    documentUrlPatterns와 마찬가지로 img, audio, video 태그의 src 속성과 a 태그의 href 속성을 기반으로 필터링합니다.

  • 제목

    문자열(선택사항)

    항목에 표시할 텍스트입니다. type이 separator가 아니면 필수입니다. 컨텍스트가 selection인 경우 문자열 내에 %s를 사용하여 선택된 텍스트를 표시합니다. 예를 들어 이 매개변수의 값이 'Translate '%s' Pig Latin" 사용자가 'cool'이라는 단어를 선택하면 컨텍스트 메뉴 항목은 'Translate 'cool'이 됩니다. Pig Latin"이라고 말합니다.

  • 유형

    ItemType: 선택사항

    메뉴 항목의 유형입니다. 기본값은 normal입니다.

  • 표시

    불리언 선택사항

    항목이 메뉴에 표시되는지 여부입니다.

  • 클릭

    void 선택사항

    메뉴 항목을 클릭하면 다시 호출되는 함수입니다. 서비스 워커 내부에서는 사용할 수 없습니다. 대신 contextMenus.onClicked의 리스너를 등록해야 합니다.

    onclick 함수는 다음과 같습니다. 

    (info: OnClickData, tab: Tab) => {...}

    • 정보

      OnClickData

      클릭한 항목에 관한 정보와 클릭이 발생한 컨텍스트입니다.

    • 탭

      Tab

      클릭이 발생한 탭의 세부정보 플랫폼 앱에는 이 매개변수가 없습니다.

ItemType

Chrome 44 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

메뉴 항목의 유형입니다.

열거형

"normal"

'체크박스'

'라디오'

"구분자"

OnClickData

컨텍스트 메뉴 항목을 클릭하면 전송되는 정보입니다.

속성

  • 선택됨

    불리언 선택사항

    체크박스나 라디오 항목을 클릭한 후의 상태를 나타내는 플래그입니다.

  • 수정 가능

    부울

    요소를 수정할 수 있는지 여부를 나타내는 플래그 (텍스트 입력, 텍스트 영역 등)

  • frameId

    숫자 선택사항

    Chrome 51 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    컨텍스트 메뉴가 프레임에 있는 경우 클릭된 요소의 프레임 ID입니다.

  • frameUrl

    문자열(선택사항)

    컨텍스트 메뉴가 프레임에 있는 경우 클릭된 요소의 프레임 URL입니다.

  • linkUrl

    문자열(선택사항)

    요소가 링크인 경우 요소가 가리키는 URL입니다.

  • mediaType

    문자열(선택사항)

    '이미지', '동영상' 또는 '오디오' 중 하나 컨텍스트 메뉴가 이러한 요소 유형 중 하나에서 활성화된 경우

  • menuItemId

    string | 숫자

    클릭된 메뉴 항목의 ID입니다.

  • pageUrl

    문자열(선택사항)

    메뉴 항목을 클릭한 페이지의 URL입니다. 현재 페이지가 없는 컨텍스트(예: 런처 컨텍스트 메뉴)에서 클릭이 발생한 경우 이 속성이 설정되지 않습니다.

  • parentMenuItemId

    string | 숫자 선택사항

    클릭된 상품의 상위 ID입니다(있는 경우).

  • selectionText

    문자열(선택사항)

    컨텍스트 선택의 텍스트입니다(있는 경우).

  • srcUrl

    문자열(선택사항)

    'src'가 있는 요소에 표시됩니다. URL입니다.

  • wasChecked

    불리언 선택사항

    클릭되기 전의 체크박스나 라디오 항목의 상태를 나타내는 플래그입니다.

속성

ACTION_MENU_TOP_LEVEL_LIMIT

확장 프로그램 작업 컨텍스트 메뉴에 추가할 수 있는 최상위 확장 프로그램 항목의 최대 개수입니다. 이 한도를 초과하는 항목은 무시됩니다.

값

6

메서드

create()

chrome.contextMenus.create(
  createProperties: CreateProperties,
  callback?: function,
)

새 컨텍스트 메뉴 항목을 만듭니다. 생성 중에 오류가 발생하더라도 생성 콜백이 실행될 때까지 감지되지 않을 수 있습니다. 세부정보는 runtime.lastError에서 확인할 수 있습니다.

매개변수

  • createProperties

    CreateProperties

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    () => void

반환 값

  • 숫자 | 문자열

    새로 생성된 항목의 ID입니다.

remove()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.contextMenus.remove(
  menuItemId: string | number,
  callback?: function,
)

컨텍스트 메뉴 항목을 삭제합니다.

매개변수

  • menuItemId

    string | 숫자

    삭제할 컨텍스트 메뉴 항목의 ID입니다.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    () => void

반환 값

  • 프로미스<void>

    Chrome 123 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

removeAll()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.contextMenus.removeAll(
  callback?: function,
)

이 확장 프로그램에서 추가한 모든 컨텍스트 메뉴 항목을 삭제합니다.

매개변수

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    () => void

반환 값

  • 프로미스<void>

    Chrome 123 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

update()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
  callback?: function,
)

이전에 만든 컨텍스트 메뉴 항목을 업데이트합니다.

매개변수

  • id

    string | 숫자

    업데이트할 상품의 ID입니다.

  • updateProperties

    객체

    업데이트할 속성입니다. contextMenus.create 함수와 동일한 값을 사용합니다.

    • 선택됨

      불리언 선택사항

    • contexts

      [ContextType, ...ContextType[]] 선택사항

    • documentUrlPatterns

      string[] 선택사항

    • 사용 설정됨

      불리언 선택사항

    • parentId

      string | 숫자 선택사항

      이 항목의 상위 항목이 될 항목의 ID입니다. 참고: 항목을 그 하위의 하위 항목이 되도록 설정할 수는 없습니다.

    • targetUrlPatterns

      string[] 선택사항

    • 제목

      문자열(선택사항)

    • 유형

      ItemType: 선택사항

    • 표시

      불리언 선택사항

      Chrome 62 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

      항목이 메뉴에 표시되는지 여부입니다.

    • 클릭

      void 선택사항

      onclick 함수는 다음과 같습니다. 

      (info: OnClickData, tab: Tab) => {...}

      • 정보

        OnClickData

        Chrome 44 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.
      • 탭

        Tab

        Chrome 44 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

        클릭이 발생한 탭의 세부정보 플랫폼 앱에는 이 매개변수가 없습니다.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    () => void

반환 값

  • 프로미스<void>

    Chrome 123 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

이벤트

onClicked

chrome.contextMenus.onClicked.addListener(
  callback: function,
)

컨텍스트 메뉴 항목을 클릭하면 실행됩니다.

매개변수