이 페이지는 Cloud Translation API를 통해 번역되었습니다.

chrome.sidePanel

설명

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

권한

sidePanel

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

manifest.json:

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

가용성

Chrome 114 이상 MV3 이상

개념 및 사용법

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

측면 패널 드롭다운 메뉴 — </ph> 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.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
});

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

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

측면 패널 사용자 환경

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

측면 패널 열기

사용자가 측면 패널을 열 수 있도록 하려면 작업 아이콘을 함께 사용하세요. sidePanel.setPanelBehavior()와 함께 사용할 수 있습니다. 또는 다음과 같은 사용자 상호작용 후에 sidePanel.open()를 호출합니다.

액션 클릭
단축키
컨텍스트 메뉴
확장 프로그램 페이지 또는 콘텐츠 스크립트에서의 사용자 동작

측면 패널 고정하기

측면 패널이 열리면 측면 패널 툴바에 핀 아이콘이 표시됩니다. 아이콘을 클릭하면 확장 프로그램의 작업 아이콘이 고정됩니다. 작업 아이콘을 클릭하면 고정하면 작업 아이콘에 대해 기본 작업이 수행되며 측면 패널을 엽니다.

예

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

유형

GetPanelOptions

속성

tabId

숫자 선택사항

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

OpenOptions

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

속성

tabId

숫자 선택사항

측면 패널을 열 탭입니다. 해당 탭에 탭별 측면 패널이 있는 경우 패널은 해당 탭에만 열립니다. 탭별 패널이 없는 경우 글로벌 패널은 지정된 탭에서 열리고, 현재 열려 있는 탭별 패널이 없는 다른 탭에서 열립니다. 이렇게 하면 해당 탭에서 현재 활성화된 측면 패널 (전체 또는 탭 전용)이 재정의됩니다. 이 항목 또는 windowId를 하나 이상 제공해야 합니다.
windowId

숫자 선택사항

측면 패널을 열 창입니다. 이는 확장 프로그램에 탭과 무관한 전역 측면 패널이 있거나 tabId도 지정된 경우에만 적용됩니다. 이렇게 하면 사용자가 지정된 창에서 현재 활성화된 전역 측면 패널이 재정의됩니다. 이 항목 또는 tabId를 하나 이상 제공해야 합니다.

PanelBehavior

속성

openPanelOnActionClick

불리언 선택사항

확장 프로그램 아이콘을 클릭하면 측면 패널에 확장 프로그램 항목이 표시되도록 전환할 수 있습니다. 기본값은 false입니다.

PanelOptions

속성

사용 설정됨

불리언 선택사항

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

문자열(선택사항)

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

숫자 선택사항

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

SidePanel

속성

default_path

문자열

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

메서드

getOptions()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.

chrome.sidePanel.getOptions(
  options: GetPanelOptions,
  callback?: function,
)

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

매개변수

옵션

GetPanelOptions

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

함수 선택사항

callback 매개변수는 다음과 같습니다.
```
(options: PanelOptions) => void
```
- 옵션
  
  PanelOptions

반환 값

Promise<PanelOptions>

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

getPanelBehavior()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.

chrome.sidePanel.getPanelBehavior(
  callback?: function,
)

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

매개변수

콜백

함수 선택사항

callback 매개변수는 다음과 같습니다.
```
(behavior: PanelBehavior) => void
```
- 이해할 수 있습니다.
  
  PanelBehavior

반환 값

Promise<PanelBehavior>

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

open()

<ph type="x-smartling-placeholder"></ph> 프로미스 Chrome 116 이상

chrome.sidePanel.open(
  options: OpenOptions,
  callback?: function,
)

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

매개변수

옵션

OpenOptions

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

함수 선택사항

callback 매개변수는 다음과 같습니다.
```
() => void
```

반환 값

프로미스<void>

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

setOptions()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.

chrome.sidePanel.setOptions(
  options: PanelOptions,
  callback?: function,
)

측면 패널을 구성합니다.

매개변수

옵션

PanelOptions

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

함수 선택사항

callback 매개변수는 다음과 같습니다.
```
() => void
```

반환 값

프로미스<void>

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

setPanelBehavior()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.

chrome.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
  callback?: function,
)

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

매개변수

이해할 수 있습니다.

PanelBehavior

설정할 새 동작입니다.
콜백

함수 선택사항

callback 매개변수는 다음과 같습니다.
```
() => void
```

반환 값

프로미스<void>

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