chrome.sidePanel

설명

chrome.sidePanel API를 사용하여 브라우저의 측면 패널에 웹페이지의 기본 콘텐츠와 함께 콘텐츠를 호스팅합니다.

권한

sidePanel

측면 패널 API를 사용하려면 확장 프로그램 매니페스트 파일에 "sidePanel" 권한을 추가합니다.

manifest.json:

{
  "name": "My side panel extension",
  ...
  "permissions": [
    "sidePanel"
  ]
}

지원 대상

Chrome 114 이상 MV3 이상

개념 및 사용법

Side Panel API를 사용하면 확장 프로그램이 측면 패널에 자체 UI를 표시하여 사용자의 탐색 여정을 보완하는 지속적인 환경을 지원할 수 있습니다.

측면 패널 드롭다운 메뉴
Chrome 브라우저 측면 패널 UI.

일부 기능은 다음과 같습니다.

  • 탭 간에 이동할 때 측면 패널은 열려 있습니다 (설정된 경우).
  • 특정 웹사이트에서만 사용할 수 있습니다.
  • 확장 프로그램 페이지인 측면 패널은 모든 Chrome API에 액세스할 수 있습니다.
  • 사용자는 Chrome 설정에서 패널을 어느 쪽에 표시할지 지정할 수 있습니다.

사용 사례

다음 섹션에서는 Side Panel API의 몇 가지 일반적인 사용 사례를 보여줍니다. 전체 확장 프로그램 예는 확장 프로그램 샘플을 참고하세요.

모든 사이트에 동일한 측면 패널 표시

처음에 매니페스트의 "side_panel" 키에 있는 "default_path" 속성에서 측면 패널을 설정하여 모든 사이트에서 동일한 측면 패널을 표시할 수 있습니다. 확장 프로그램 디렉터리 내의 상대 경로를 가리켜야 합니다.

manifest.json:

{
  "name": "My side panel extension",
  ...
  "side_panel": {
    "default_path": "sidepanel.html"
  }
  ...
}

sidepanel.html:

<!DOCTYPE html>
<html>
  <head>
    <title>My Sidepanel</title>
  </head>
  <body>
    <h1>All sites sidepanel extension</h1>
    <p>This side panel is enabled on all sites</p>
  </body>
</html>

특정 사이트에서 측면 패널 사용 설정

확장 프로그램에서 sidepanel.setOptions()를 사용하여 특정 탭에서 측면 패널을 사용 설정할 수 있습니다. 이 예에서는 chrome.tabs.onUpdated()를 사용하여 탭에 적용된 모든 업데이트를 리슨합니다. URL이 www.google.com인지 확인하고 측면 패널을 사용 설정합니다. 그렇지 않으면 기능이 사용 중지됩니다.

service-worker.js:

const GOOGLE_ORIGIN = 'https://www.google.com';

chrome.tabs.onUpdated.addListener(async (tabId, info, tab) => {
  if (!tab.url) return;
  const url = new URL(tab.url);
  // Enables the side panel on google.com
  if (url.origin === GOOGLE_ORIGIN) {
    await chrome.sidePanel.setOptions({
      tabId,
      path: 'sidepanel.html',
      enabled: true
    });
  } else {
    // Disables the side panel on all other sites
    await chrome.sidePanel.setOptions({
      tabId,
      enabled: false
    });
  }
});

사용자가 측면 패널이 사용 설정되지 않은 탭으로 일시적으로 전환하면 측면 패널이 숨겨집니다. 사용자가 이전에 열려 있던 탭으로 전환할 때 자동으로 다시 표시됩니다.

사용자가 측면 패널이 사용 설정되지 않은 사이트로 이동하면 측면 패널이 닫히고 측면 패널 드롭다운 메뉴에 확장 프로그램이 표시되지 않습니다.

전체 예는 탭별 측면 패널 샘플을 참고하세요.

툴바 아이콘을 클릭하여 측면 패널 열기

개발자는 사용자가 sidePanel.setPanelBehavior()로 작업 툴바 아이콘을 클릭하여 측면 패널을 열도록 허용할 수 있습니다. 먼저 매니페스트에서 "action" 키를 선언합니다.

manifest.json:

{
  "name": "My side panel extension",
  ...
   "action": {
    "default_title": "Click to open panel"
  },
  ...
}

이제 이전 예에 다음 코드를 추가합니다.

service-worker.js:

const GOOGLE_ORIGIN = 'https://www.google.com';

// Allows users to open the side panel by clicking on the action toolbar icon
chrome.sidePanel
  .setPanelBehavior({ openPanelOnActionClick: true })
  .catch((error) => console.error(error));
...

사용자 상호작용 시 프로그래매틱 방식으로 측면 패널 열기

Chrome 116에 sidePanel.open()가 도입되었습니다. 확장 프로그램에서 작업 아이콘 클릭과 같은 확장 프로그램 사용자 동작을 통해 측면 패널을 열 수 있습니다. 또는 확장 프로그램 페이지 또는 콘텐츠 스크립트에서의 사용자 상호작용(예: 버튼 클릭)입니다. 전체 데모는 측면 패널 열기 샘플 확장 프로그램을 참고하세요.

다음 코드는 사용자가 컨텍스트 메뉴를 클릭할 때 현재 창에서 전역 측면 패널을 여는 방법을 보여줍니다. sidePanel.open()를 사용할 때는 애플리케이션이 열려야 하는 컨텍스트를 선택해야 합니다. windowId를 사용하여 전역 측면 패널을 엽니다. 또는 측면 패널을 특정 탭에서만 열도록 tabId를 설정합니다.

service-worker.js:

chrome.runtime.onInstalled.addListener(() => {
  chrome.contextMenus.create({
    id: 'openSidePanel',
    title: 'Open side panel',
    contexts: ['all']
  });
});

chrome.contextMenus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === 'openSidePanel') {
    // This will open the panel in all the pages on the current window.
    chrome.sidePanel.open({ windowId: tab.windowId });
  }
});

다른 패널로 전환

확장 프로그램은 sidepanel.getOptions()를 사용하여 현재 측면 패널을 가져올 수 있습니다. 다음 예에서는 runtime.onInstalled()에 시작 측면 패널을 설정합니다. 그런 다음 사용자가 다른 탭으로 이동하면 기본 측면 패널로 대체됩니다.

service-worker.js:

const welcomePage = 'sidepanels/welcome-sp.html';
const mainPage = 'sidepanels/main-sp.html';

chrome.runtime.onInstalled.addListener(() => {
  chrome.sidePanel.setOptions({ path: welcomePage });
});

chrome.tabs.onActivated.addListener(async ({ tabId }) => {
  const { path } = await chrome.sidePanel.getOptions({ tabId });
  if (path === welcomePage) {
    chrome.sidePanel.setOptions({ path: mainPage });
  }
});

전체 샘플은 여러 측면 패널을 참고하세요.

측면 패널 사용자 환경

Chrome의 내장 측면 패널이 먼저 사용자에게 표시됩니다. 각 측면 패널에는 측면 패널 메뉴에 확장 프로그램 아이콘이 표시됩니다. 아이콘이 포함되어 있지 않으면 확장 프로그램 이름의 첫 글자와 함께 자리표시자 아이콘이 표시됩니다.

측면 패널 열기

측면 패널 메뉴로 이동
사용자는 측면 패널 메뉴에서 사용 가능한 측면 패널을 찾을 수 있습니다. 그런 다음 드롭다운 메뉴에서 광고 확장을 선택하면 됩니다.
측면 패널 드롭다운 메뉴
Chrome 브라우저 측면 패널 UI.
사용자 동작을 통해 열기

다음과 같은 sidePanel.open() 및 sidePanel.setPanelBehavior()를 사용한 사용자 상호작용을 통해 측면 패널을 열 수 있습니다.

예

Side Panel API 확장 프로그램 데모를 더 보려면 다음 확장 프로그램을 살펴보세요.

유형

GetPanelOptions

속성

  • tabId

    number 선택사항

    지정하면 지정된 탭의 측면 패널 옵션이 반환됩니다. 그렇지 않으면 기본 측면 패널 옵션 (특정 설정이 없는 탭에 사용됨)을 반환합니다.

OpenOptions

Chrome 116 이상

속성

  • tabId

    number 선택사항

    측면 패널을 열 탭입니다. 해당하는 탭에 탭별 측면 패널이 있는 경우 이 패널은 해당 탭에 대해서만 열립니다. 탭별 패널이 없는 경우 전체 패널이 지정된 탭과 현재 열려 있는 탭별 패널이 없는 다른 모든 탭에서 열립니다. 이렇게 하면 해당 탭에서 현재 활성화되어 있는 측면 패널 (전역 패널 또는 탭별)이 모두 재정의됩니다. 이 중 하나 또는 windowId가 제공되어야 합니다.

  • windowId

    number 선택사항

    측면 패널을 열 창입니다. 이는 확장 프로그램에 전역 (탭 이외의 항목) 측면 패널이 있거나 tabId도 지정된 경우에만 적용됩니다. 이렇게 하면 사용자가 지정된 창에서 연 모든 활성 전역 측면 패널이 재정의됩니다. 이 중 하나 또는 tabId가 제공되어야 합니다.

PanelBehavior

속성

  • openPanelOnActionClick

    부울 선택사항

    확장 프로그램 아이콘을 클릭할 때 측면 패널에 확장 프로그램 항목을 표시할지 여부를 나타냅니다. 기본값은 거짓입니다.

PanelOptions

속성

  • 사용 설정됨

    부울 선택사항

    측면 패널 사용 설정 여부입니다. 이는 선택사항입니다. 기본값은 true입니다.

  • 경로

    문자열 선택사항

    사용할 측면 패널 HTML 파일의 경로입니다. 확장 프로그램 패키지 내의 로컬 리소스여야 합니다.

  • tabId

    number 선택사항

    지정하면 이 ID가 있는 탭에만 측면 패널 옵션이 적용됩니다. 이 옵션을 생략하면 기본 동작 (특정 설정이 없는 탭에 사용)을 설정합니다. 참고: 이 tabId와 기본 tabId에 동일한 경로가 설정되어 있으면 이 tabId의 패널은 기본 tabId의 패널과 다른 인스턴스가 됩니다.

SidePanel

속성

  • default_path

    string

    측면 패널 표시를 위해 개발자가 지정한 경로입니다.

방법

getOptions()

프로미스 
chrome.sidePanel.getOptions(
  options: GetPanelOptions,
  callback?: function,
)

활성 패널 구성을 반환합니다.

매개변수

  • 구성을 반환할 컨텍스트를 지정합니다.

  • 콜백

    함수 선택사항

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

    (options: PanelOptions)=>void

반환 값

  • Promise<PanelOptions>

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

getPanelBehavior()

프로미스 
chrome.sidePanel.getPanelBehavior(
  callback?: function,
)

확장 프로그램의 현재 측면 패널 동작을 반환합니다.

매개변수

  • 콜백

    함수 선택사항

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

    (behavior: PanelBehavior)=>void

반환 값

  • Promise<PanelBehavior>

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

open()

Promise Chrome 116 이상 
chrome.sidePanel.open(
  options: OpenOptions,
  callback?: function,
)

확장 프로그램의 측면 패널을 엽니다. 사용자 작업에 대한 응답으로만 호출될 수 있습니다.

매개변수

  • 옵션

    OpenOptions

    측면 패널을 열 컨텍스트를 지정합니다.

  • 콜백

    함수 선택사항

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

    ()=>void

반환 값

  • Promise<void>

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

setOptions()

프로미스 
chrome.sidePanel.setOptions(
  options: PanelOptions,
  callback?: function,
)

측면 패널을 구성합니다.

매개변수

  • 옵션

    PanelOptions

    패널에 적용할 구성 옵션입니다.

  • 콜백

    함수 선택사항

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

    ()=>void

반환 값

  • Promise<void>

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

setPanelBehavior()

프로미스 
chrome.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
  callback?: function,
)

확장 프로그램의 측면 패널 동작을 구성합니다. upsert 작업입니다.

매개변수

  • 이해할 수 있습니다.

    PanelBehavior

    설정할 새 동작입니다.

  • 콜백

    함수 선택사항

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

    ()=>void

반환 값

  • Promise<void>

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