chrome.browserAction

설명

브라우저 작업을 사용하여 주소 표시줄 오른쪽에 있는 기본 Chrome 툴바에 아이콘을 추가합니다. 브라우저 작업에는 아이콘 외에도 도움말, 배지, 팝업이 포함될 수 있습니다.

가용성

<ph type="x-smartling-placeholder"></ph> &amp;leq; MV2

다음 그림에서 주소 표시줄 오른쪽의 여러 색상의 정사각형은 표시됩니다. 아이콘 아래에 팝업이 표시됩니다.

항상 활성 상태가 아닌 아이콘을 만들려면 브라우저 대신 페이지 작업을 사용하세요. 있습니다.

매니페스트

다음과 같이 확장 프로그램 매니페스트에 브라우저 작업을 등록합니다.

{
  "name": "My extension",
  ...
  "browser_action": {
    "default_icon": {                // optional
      "16": "images/icon16.png",     // optional
      "24": "images/icon24.png",     // optional
      "32": "images/icon32.png"      // optional
    },
    "default_title": "Google Mail",  // optional, shown in tooltip
    "default_popup": "popup.html"    // optional
  },
  ...
}

Chrome에서 사용할 수 있는 크기의 아이콘을 제공할 수 있으며, Chrome은 가장 가까운 아이콘을 선택하여 배율을 조정합니다. 16 딥 공간을 채우도록 적절한 크기로 설정합니다. 하지만 정확한 크기가 제공되지 않으면 배율 조정으로 인해 아이콘이 디테일을 잃거나 흐릿하게 보일 수 있습니다.

1.5x 또는 1.2x와 같이 덜 일반적인 배율을 사용하는 기기가 점점 더 보편화되고 있으므로 아이콘에 여러 크기를 제공하는 것이 좋습니다. 이렇게 하면 아이콘 표시 크기가 다른 아이콘을 제공하기 위해 더 이상 작업을 할 필요가 없습니다.

기본 아이콘을 등록하는 이전 구문이 계속 지원됩니다.

{
  "name": "My extension",
  ...
  "browser_action": {
    ...
    "default_icon": "images/icon32.png"  // optional
    // equivalent to "default_icon": { "32": "images/icon32.png" }
  },
  ...
}

UI 요소

브라우저 작업에는 아이콘, 도움말, 배지, 팝업이 포함될 수 있습니다.

아이콘

Chrome의 브라우저 작업 아이콘은 너비와 높이가 16 딥 (기기 독립적 픽셀)입니다. 크게 아이콘은 크기에 맞게 크기가 조정되지만, 16 딥 정사각형 아이콘을 사용하는 것이 가장 좋습니다.

아이콘은 정적 이미지를 사용하거나 HTML5 캔버스 요소를 사용하는 두 가지 방법으로 설정할 수 있습니다. 사용 정적 이미지는 간단한 애플리케이션에서는 더 쉽지만, 보다 동적인 UI를 만들 수도 있습니다(예: 매끄러운 애니메이션을 만들 수 있습니다.

정적 이미지는 WebKit에서 표시할 수 있는 모든 형식(BMP, GIF, ICO, JPEG, PNG 포함)일 수 있습니다. 대상 압축해제된 확장 프로그램이 있는 경우 이미지는 PNG 형식이어야 합니다.

아이콘을 설정하려면 manifest에서 browser_action의 default_icon 필드를 사용하거나 다음을 호출합니다. browserAction.setIcon 메서드를 사용하여 지도 가장자리에 패딩을 추가할 수 있습니다.

화면 픽셀 밀도 (비율 size_in_pixel / size_in_dip)가 1과 다른 경우 아이콘은 다양한 크기의 이미지 집합으로 정의될 수 있습니다. 실제 이미지는 16 딥의 픽셀 크기에 가장 잘 맞도록 디스플레이가 선택됩니다. 아이콘 집합에는 Chrome에서 가장 적절한 아이콘을 선택합니다.

도움말

도움말을 설정하려면 manifest에서 browser_action의 default_title 필드를 사용하세요. browserAction.setTitle 메서드를 호출합니다. default_title 필드가 포함되어 있습니다. 자세한 내용은 다국어화를 참고하세요.

배지

브라우저 작업 시 배지(아이콘 위에 겹쳐 표시되는 텍스트)를 표시할 수도 있습니다. 배지를 사용하면 브라우저에 대한 소량의 정보를 표시하기 위해 브라우저 작업을 쉽게 업데이트할 수 있습니다. 확장 프로그램의 상태입니다.

배지의 공간이 제한되어 있으므로 4자(영문 기준) 이하여야 합니다.

browserAction.setBadgeText 및 browserAction.setBadgeBackgroundColor을 각각 반환합니다.

브라우저 작업에 팝업이 있는 경우 사용자가 확장 프로그램의 아이콘을 클릭하면 팝업이 표시됩니다. 이 팝업에는 원하는 HTML 콘텐츠가 포함될 수 있으며 콘텐츠에 맞게 자동으로 크기가 조정됩니다. 팝업은 25x25 이상, 800x600 이하여야 합니다.

브라우저 작업에 팝업을 추가하려면 팝업 콘텐츠가 포함된 HTML 파일을 만듭니다. HTML 파일을 manifest에서 browser_action의 default_popup 필드에 추가하거나 browserAction.setPopup 메서드를 사용하여 지도 가장자리에 패딩을 추가할 수 있습니다.

팁

최상의 시각적 효과를 위해 다음 가이드라인을 따르세요.

  • 대부분의 페이지에서 사용할 수 있는 기능에 브라우저 작업을 사용하세요.
  • 몇 개의 페이지에만 의미가 있는 기능에 브라우저 작업을 사용하지 마세요. 페이지 사용 작업을 대신 사용하세요.
  • 권장: 16x16 딥 공간을 최대한 활용하는 크고 다채로운 아이콘을 사용하세요. 브라우저 작업 아이콘 페이지 작업 아이콘보다 조금 더 크고 무겁게 느껴져야 합니다.
  • Chrome의 흑백 메뉴 아이콘을 모방하지 마세요. 하지만 어쨌든 확장 프로그램은 약간 눈에 띄어야 합니다.
  • 알파 투명도를 사용하여 아이콘에 부드러운 가장자리를 더하세요. 많은 사람들이 테마를 사용하기 때문에 아이콘이 다양한 배경 색상에서 멋지게 보입니다.
  • 아이콘에 계속해서 애니메이션을 적용하지 마세요. 짜증 나.

예

examples/api/browserAction에서 브라우저 작업을 사용하는 간단한 예를 확인할 수 있습니다. 디렉터리 다른 예와 소스 코드를 보는 데 도움이 필요하면 샘플을 참조하세요.

유형

ColorArray

유형

[숫자, 숫자, 숫자, 숫자]

ImageDataType

이미지의 픽셀 데이터입니다. ImageData 객체여야 합니다. 예를 들어 canvas 요소에서 가져올 수 있습니다.

유형

ImageData

TabDetails

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

속성

  • tabId

    숫자 선택사항

    상태를 쿼리할 탭의 ID입니다. 탭을 지정하지 않으면 특정 탭이 아닌 상태가 반환됩니다.

메서드

disable()

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

탭에 대해 브라우저 작업을 사용 중지합니다.

매개변수

  • tabId

    숫자 선택사항

    브라우저 작업을 수정할 탭의 ID입니다.

  • 콜백

    함수 선택사항

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

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

    () => void

반환 값

  • 프로미스<void>

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

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

enable()

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

탭에 대한 브라우저 작업을 사용 설정합니다. 기본값은 사용 설정입니다.

매개변수

  • tabId

    숫자 선택사항

    브라우저 작업을 수정할 탭의 ID입니다.

  • 콜백

    함수 선택사항

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

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

    () => void

반환 값

  • 프로미스<void>

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

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

getBadgeBackgroundColor()

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

브라우저 작업의 배경 색상을 가져옵니다.

매개변수

  • 세부정보

    TabDetails

  • 콜백

    함수 선택사항

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

    (result: ColorArray) => void

반환 값

  • Promise&lt;ColorArray&gt;

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

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

getBadgeText()

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

브라우저 작업의 배지 텍스트를 가져옵니다. 탭을 지정하지 않으면 탭이 아닌 배지 텍스트가 반환됩니다.

매개변수

  • 세부정보

    TabDetails

  • 콜백

    함수 선택사항

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

    (result: string) => void

    • 결과

      문자열

반환 값

  • 프로미스<string>

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

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

getPopup()

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

이 브라우저 작업에 대한 팝업으로 설정된 HTML 문서를 가져옵니다.

매개변수

  • 세부정보

    TabDetails

  • 콜백

    함수 선택사항

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

    (result: string) => void

    • 결과

      문자열

반환 값

  • 프로미스<string>

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

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

getTitle()

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

브라우저 작업의 제목을 가져옵니다.

매개변수

  • 세부정보

    TabDetails

  • 콜백

    함수 선택사항

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

    (result: string) => void

    • 결과

      문자열

반환 값

  • 프로미스<string>

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

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

setBadgeBackgroundColor()

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

배지의 배경 색상을 설정합니다.

매개변수

  • 세부정보

    객체

    • 색상

      string | ColorArray

      배지의 RGBA 색상을 구성하는 0~255 범위의 4개 정수의 배열입니다. CSS 16진수 색상 값을 갖는 문자열일 수도 있습니다. 예를 들면 #FF0000 또는 #F00 (빨간색)입니다. 색상을 최대 불투명도로 렌더링합니다.

    • tabId

      숫자 선택사항

      특정 탭이 선택된 경우에만 변경을 제한합니다. 탭을 닫으면 자동으로 재설정됩니다.

  • 콜백

    함수 선택사항

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

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

    () => void

반환 값

  • 프로미스<void>

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

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

setBadgeText()

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

브라우저 작업의 배지 텍스트를 설정합니다. 배지는 아이콘 위에 표시됩니다.

매개변수

  • 세부정보

    객체

    • tabId

      숫자 선택사항

      특정 탭이 선택된 경우에만 변경을 제한합니다. 탭을 닫으면 자동으로 재설정됩니다.

    • 텍스트

      문자열(선택사항)

      전달할 수 있는 문자의 수에는 제한이 없지만 약 4자만 공백에 들어갈 수 있습니다. 빈 문자열 ('')이 전달되면 배지 텍스트가 삭제됩니다. tabId이 지정되고 text이 null이면 지정된 탭의 텍스트가 삭제되고 기본적으로 전역 배지 텍스트가 됩니다.

  • 콜백

    함수 선택사항

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

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

    () => void

반환 값

  • 프로미스<void>

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

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

setIcon()

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

브라우저 작업의 아이콘을 설정합니다. 아이콘은 이미지 파일의 경로, 캔버스 요소의 픽셀 데이터 또는 그중 하나의 사전으로 지정할 수 있습니다. path 또는 imageData 속성을 지정해야 합니다.

매개변수

  • 세부정보

    객체

    • imageData

      ImageData | 객체(선택사항)

      ImageData 객체 또는 사전 {size -> ImageData}는 설정할 아이콘을 나타냅니다. 아이콘이 사전으로 지정된 경우 화면의 픽셀 밀도에 따라 사용된 이미지가 선택됩니다. 한 화면 공간 단위에 맞는 이미지 픽셀 수가 scale와 같으면 크기가 scale * n인 이미지가 선택됩니다. 여기서 n은 UI의 아이콘 크기입니다. 이미지를 하나 이상 지정해야 합니다. 'details.imageData = foo'는 'details.imageData = {'16': foo}'와 동일합니다.

    • 경로

      string | 객체(선택사항)

      상대 이미지 경로 또는 사전 {size -> 상대 이미지 경로}이(가) 설정할 아이콘을 가리킵니다. 아이콘이 사전으로 지정된 경우 화면의 픽셀 밀도에 따라 사용된 이미지가 선택됩니다. 한 화면 공간 단위에 맞는 이미지 픽셀 수가 scale와 같으면 크기가 scale * n인 이미지가 선택됩니다. 여기서 n은 UI의 아이콘 크기입니다. 이미지를 하나 이상 지정해야 합니다. 'details.path = foo' 'details.path = {'16': foo}'와 동일합니다.

    • tabId

      숫자 선택사항

      특정 탭이 선택된 경우에만 변경을 제한합니다. 탭을 닫으면 자동으로 재설정됩니다.

  • 콜백

    함수 선택사항

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

    () => void

반환 값

  • 프로미스<void>

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

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

setPopup()

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

사용자가 브라우저 작업 아이콘을 클릭할 때 HTML 문서가 팝업으로 열리도록 설정합니다.

매개변수

  • 세부정보

    객체

    • 팝업

      문자열

      팝업에 표시할 HTML 파일의 상대 경로입니다. 빈 문자열 ('')로 설정하면 팝업이 표시되지 않습니다.

    • tabId

      숫자 선택사항

      특정 탭이 선택된 경우에만 변경을 제한합니다. 탭을 닫으면 자동으로 재설정됩니다.

  • 콜백

    함수 선택사항

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

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

    () => void

반환 값

  • 프로미스<void>

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

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

setTitle()

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

브라우저 작업의 제목을 설정합니다. 이 제목은 도움말에 표시됩니다.

매개변수

  • 세부정보

    객체

    • tabId

      숫자 선택사항

      특정 탭이 선택된 경우에만 변경을 제한합니다. 탭을 닫으면 자동으로 재설정됩니다.

    • 제목

      문자열

      마우스를 올려 놓았을 때 브라우저 작업이 표시해야 하는 문자열입니다.

  • 콜백

    함수 선택사항

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

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

    () => void

반환 값

  • 프로미스<void>

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

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

이벤트

onClicked

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

브라우저 작업 아이콘을 클릭하면 실행됩니다. 브라우저 작업에 팝업이 있으면 실행되지 않습니다.

매개변수

  • 콜백

    함수

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

    (tab: tabs.Tab) => void