설명
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
메뉴가 표시될 수 있는 다양한 컨텍스트 'all'을 지정하는 것은 'launcher'를 제외한 다른 모든 컨텍스트의 조합과 같습니다. '런처' 컨텍스트는 앱에서만 지원되며 런처, 작업 표시줄, 도크 등에서 앱 아이콘을 클릭할 때 표시되는 컨텍스트 메뉴에 메뉴 항목을 추가하는 데 사용됩니다. 다른 플랫폼에 따라 런처 컨텍스트 메뉴에서 실제로 지원되는 항목에 제한이 있을 수 있습니다.
enum
"browser_action"
CreateProperties
새 컨텍스트 메뉴 항목의 속성입니다.
속성
-
선택됨
부울 선택사항
체크박스 또는 라디오 버튼의 초기 상태입니다. 선택된 경우
true
, 선택 해제된 경우false
입니다. 주어진 그룹에서 한 번에 하나의 라디오 버튼만 선택할 수 있습니다. -
contexts
[ContextType, ...ContextType[]] 선택사항
이 메뉴 항목이 표시될 컨텍스트 목록입니다. 기본값은
['page']
입니다. -
documentUrlPatterns
string[] 선택사항
URL이 지정된 패턴 중 하나와 일치하는 문서 또는 프레임에만 적용되도록 항목을 제한합니다. 패턴 형식에 대한 자세한 내용은 패턴 일치를 참고하세요.
-
사용 설정됨
부울 선택사항
컨텍스트 메뉴 항목의 사용 설정 또는 사용 중지 여부입니다. 기본값은
true
입니다. -
id
문자열 선택사항
이 항목에 할당할 고유 ID입니다. 이벤트 페이지의 경우 필수입니다. 이 확장 프로그램의 다른 ID와 동일할 수 없습니다.
-
parentId
문자열 | 숫자 선택사항
상위 메뉴 항목의 ID입니다. 상위 메뉴 항목의 ID로, 항목이 이전에 추가된 항목의 하위 항목이 됩니다.
-
targetUrlPatterns
string[] 선택사항
documentUrlPatterns
와 마찬가지로img
,audio
,video
태그의src
속성과a
태그의href
속성을 기반으로 필터링합니다. -
title
문자열 선택사항
항목에 표시할 텍스트입니다.
type
가separator
가 아니면 필수입니다. 컨텍스트가selection
인 경우 문자열 내의%s
를 사용하여 선택된 텍스트를 표시합니다. 예를 들어 이 매개변수의 값이 ''%s'를 라틴어로 번역'이고 사용자가 '쿨'이라는 단어를 선택하는 경우 선택 항목의 컨텍스트 메뉴 항목은 '''cool'을 돼지 라틴어로 번역'이 됩니다.' -
유형
ItemType 선택사항
메뉴 항목 유형입니다. 기본값은
normal
입니다. -
표시
부울 선택사항
메뉴에 항목이 표시되는지 여부입니다.
-
onclick
void 선택사항
메뉴 항목을 클릭하면 다시 호출되는 함수입니다. 서비스 워커 내부에서는 사용할 수 없습니다. 대신
contextMenus.onClicked
에 리스너를 등록해야 합니다.onclick
함수는 다음과 같습니다.(info: OnClickData, tab: Tab) => {...}
-
정보
클릭된 항목에 대한 정보 및 클릭이 발생한 컨텍스트
-
탭
클릭이 발생한 탭의 세부정보 이 매개변수는 플랫폼 앱에는 없습니다.
-
ItemType
메뉴 항목 유형입니다.
enum
OnClickData
컨텍스트 메뉴 항목을 클릭할 때 전송되는 정보입니다.
속성
-
선택됨
부울 선택사항
클릭된 후 체크박스 또는 라디오 항목의 상태를 나타내는 플래그입니다.
-
수정 가능
boolean
요소의 수정 가능 여부를 나타내는 플래그 (텍스트 입력, 텍스트 영역 등).
-
frameId
number 선택사항
Chrome 51 이상컨텍스트 메뉴가 프레임에 있는 경우 클릭된 요소의 프레임 ID입니다.
-
frameUrl
문자열 선택사항
프레임에 있는 경우 컨텍스트 메뉴가 클릭된 요소 프레임의 URL입니다.
-
linkUrl
문자열 선택사항
요소가 링크인 경우 연결되는 URL입니다.
-
mediaType
문자열 선택사항
컨텍스트 메뉴가 이러한 유형의 요소 중 하나에서 활성화된 경우 '이미지', '동영상' 또는 '오디오' 중 하나입니다.
-
문자열 | 숫자
클릭된 메뉴 항목의 ID입니다.
-
pageUrl
문자열 선택사항
메뉴 항목을 클릭한 페이지의 URL입니다. 런처 컨텍스트 메뉴와 같이 현재 페이지가 없는 컨텍스트에서 클릭이 발생하면 이 속성이 설정되지 않습니다.
-
parentMenuItemId
문자열 | 숫자 선택사항
클릭된 항목의 상위 ID(있는 경우)
-
selectionText
문자열 선택사항
컨텍스트 선택 텍스트입니다(있는 경우).
-
srcUrl
문자열 선택사항
'src' URL이 있는 요소에 표시됩니다.
-
wasChecked
부울 선택사항
클릭되기 전 체크박스 또는 라디오 항목의 상태를 나타내는 플래그입니다.
속성
ACTION_MENU_TOP_LEVEL_LIMIT
확장 프로그램 작업 컨텍스트 메뉴에 추가할 수 있는 최상위 확장 프로그램 항목의 최대 개수입니다. 이 한도를 초과하는 항목은 무시됩니다.
값
6
메서드
create()
chrome.contextMenus.create(
createProperties: CreateProperties,
callback?: function,
)
새 컨텍스트 메뉴 항목을 만듭니다. 생성 중에 오류가 발생하면 생성 콜백이 실행될 때까지 오류가 감지되지 않을 수 있습니다. 세부정보는 runtime.lastError
에서 확인할 수 있습니다.
매개변수
-
createProperties
-
callback
함수 선택사항
callback
매개변수는 다음과 같습니다.() => void
반환 값
-
숫자 | 문자열
새로 만든 항목의 ID입니다.
remove()
chrome.contextMenus.remove(
menuItemId: string | number,
callback?: function,
)
컨텍스트 메뉴 항목을 삭제합니다.
매개변수
-
문자열 | 숫자
삭제할 컨텍스트 메뉴 항목의 ID입니다.
-
callback
함수 선택사항
callback
매개변수는 다음과 같습니다.() => void
반환 값
-
Promise<void>
Chrome 123 이상프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
removeAll()
chrome.contextMenus.removeAll(
callback?: function,
)
이 확장 프로그램에서 추가한 모든 컨텍스트 메뉴 항목을 삭제합니다.
매개변수
-
callback
함수 선택사항
callback
매개변수는 다음과 같습니다.() => void
반환 값
-
Promise<void>
Chrome 123 이상프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
update()
chrome.contextMenus.update(
id: string | number,
updateProperties: object,
callback?: function,
)
이전에 만든 컨텍스트 메뉴 항목을 업데이트합니다.
매개변수
-
id
문자열 | 숫자
업데이트할 항목의 ID입니다.
-
updateProperties
객체
업데이트할 속성입니다.
contextMenus.create
함수와 동일한 값이 허용됩니다.-
선택됨
부울 선택사항
-
contexts
[ContextType, ...ContextType[]] 선택사항
-
documentUrlPatterns
string[] 선택사항
-
사용 설정됨
부울 선택사항
-
parentId
문자열 | 숫자 선택사항
이 항목의 상위로 만들 항목의 ID입니다. 참고: 항목을 해당 하위 항목의 하위 요소가 되도록 설정할 수는 없습니다.
-
targetUrlPatterns
string[] 선택사항
-
title
문자열 선택사항
-
유형
ItemType 선택사항
-
표시
부울 선택사항
Chrome 62 이상메뉴에 항목이 표시되는지 여부입니다.
-
onclick
void 선택사항
onclick
함수는 다음과 같습니다.(info: OnClickData, tab: Tab) => {...}
-
정보Chrome 44 이상
-
탭Chrome 44 이상
클릭이 발생한 탭의 세부정보 이 매개변수는 플랫폼 앱에는 없습니다.
-
-
-
callback
함수 선택사항
callback
매개변수는 다음과 같습니다.() => void
반환 값
-
Promise<void>
Chrome 123 이상프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
이벤트
onClicked
chrome.contextMenus.onClicked.addListener(
callback: function,
)
컨텍스트 메뉴 항목을 클릭하면 실행됩니다.
매개변수
-
callback
기능
callback
매개변수는 다음과 같습니다.(info: OnClickData, tab?: tabs.Tab) => void
-
정보
-
탭
tabs.Tab 선택사항
-