chrome.windows

설명

chrome.windows API를 사용하여 브라우저 창과 상호작용합니다. 이 API를 사용하여 브라우저에서 창을 만들고 수정하고 재정렬할 수 있습니다.

권한

요청 시 windows.Window에는 tabs.Tab 객체의 배열이 포함됩니다. tabs.Tab의 url, pendingUrl, title 또는 favIconUrl 속성에 액세스해야 하는 경우 매니페스트에서 "tabs" 권한을 선언해야 합니다. 예를 들면 다음과 같습니다.

{
  "name": "My extension",
  ...
  "permissions": ["tabs"],
  ...
}

개념 및 사용법

현재 창

확장 프로그램 시스템의 많은 함수는 windowId 인수를 선택적으로 취하며, 기본값은 현재 기간입니다.

현재 창은 현재 실행 중인 코드가 포함된 창입니다. 이 창은 최상위 창 또는 포커스가 맞춰진 창과 다를 수 있음을 인식하는 것이 중요합니다.

예를 들어 확장 프로그램이 단일 HTML 파일에서 탭이나 창을 몇 개 만들고 HTML 파일에 tabs.query() 호출이 포함되어 있다고 가정해 보겠습니다. 현재 창은 최상위 창이 무엇인지에 관계없이 호출한 페이지가 포함된 창입니다.

서비스 워커의 경우 현재 기간의 값이 마지막 활성 기간으로 대체됩니다. 상황에 따라 백그라운드 페이지를 위한 현재 창이 없을 수도 있습니다.

예

이 API를 사용해 보려면 chrome-extension-samples 저장소의 windows API 예시를 설치하세요.

각 창에 하나의 탭이 있는 두 개의 창

유형

CreateType

Chrome 44 이상

생성할 브라우저 창의 유형을 지정합니다. '패널'은 지원 중단되었으며 Chrome OS의 허용 목록에 있는 기존 확장 프로그램에서만 사용할 수 있습니다.

열거형

"normal"
창을 표준 창으로 지정합니다.

"popup"
창을 팝업 창으로 지정합니다.

"panel"
창을 패널로 지정합니다.

QueryOptions

Chrome 88 이상

속성

• populate

  부울 선택사항

  true인 경우 windows.Window 객체에는 tabs.Tab 객체 목록이 포함된 tabs 속성이 있습니다. 확장 프로그램의 매니페스트 파일에 "tabs" 권한이 포함된 경우 Tab 객체에는 url, pendingUrl, title, favIconUrl 속성만 포함됩니다.

• windowTypes

  WindowType[] 선택사항

  설정되면 반환되는 windows.Window는 유형을 기준으로 필터링됩니다. 설정하지 않으면 기본 필터가 ['normal', 'popup']로 설정됩니다.

Window

속성

• alwaysOnTop

  boolean

  창이 항상 맨 위에 표시되도록 설정할지 여부입니다.

• 집중

  boolean

  창이 현재 포커스가 맞춰진 창인지 여부입니다.

• 키

  number 선택사항

  프레임을 포함한 창의 높이입니다(단위: 픽셀). 경우에 따라 창에 height 속성이 할당되지 않을 수도 있습니다(예: sessions API에서 닫힌 창을 쿼리할 때).

• id

  number 선택사항

  창의 ID입니다. 창 ID는 브라우저 세션 내에서 고유합니다. 경우에 따라 창에 ID 속성이 할당되지 않을 수도 있습니다. 예를 들어 sessions API를 사용하여 창을 쿼리할 때 세션 ID가 있을 수 있습니다.

• 시크릿 모드

  boolean

  창이 시크릿 모드인지 여부

• 왼쪽

  number 선택사항

  화면 왼쪽 가장자리로부터 창의 오프셋(픽셀)입니다. 경우에 따라 창에 left 속성이 할당되지 않을 수도 있습니다(예: sessions API에서 닫힌 창을 쿼리할 때).

• sessionId

  문자열 선택사항

  창을 고유하게 식별하는 데 사용되는 세션 ID로, sessions API에서 가져옵니다.

• state

  WindowState (선택사항)

  이 브라우저 창의 상태입니다.

• 탭

  Tab[] 선택사항

  창의 현재 탭을 나타내는 tabs.Tab 객체의 배열입니다.

• 상단

  number 선택사항

  화면 상단 가장자리부터 창 오프셋(픽셀)입니다. 경우에 따라 창에 top 속성이 할당되지 않을 수도 있습니다(예: sessions API에서 닫힌 창을 쿼리할 때).

• 유형

  WindowType (선택사항)

  브라우저 창의 유형입니다.

• 너비

  number 선택사항

  프레임을 포함한 창의 너비(픽셀)입니다. 경우에 따라 창에 width 속성이 할당되지 않을 수도 있습니다(예: sessions API에서 닫힌 창을 쿼리할 때).

WindowState

Chrome 44 이상

이 브라우저 창의 상태입니다. 경우에 따라 창에 state 속성이 할당되지 않을 수도 있습니다(예: sessions API에서 닫힌 창을 쿼리할 때).

열거형

"normal"
일반 창 상태 (최소화, 최대화 또는 전체 화면 아님).

"minimized"
최소화된 창 상태.

"maximized"
창 상태 최대화

"fullscreen"
전체 화면 창 상태

"locked-fullscreen"
잠긴 전체화면 창 상태입니다. 이 전체 화면 상태는 사용자 작업으로 종료할 수 없으며 Chrome OS의 허용 목록에 있는 확장 프로그램에서만 사용할 수 있습니다.

WindowType

Chrome 44 이상

브라우저 창의 유형입니다. 예를 들어 sessions API에서 닫힌 창을 쿼리할 때처럼 창에 type 속성이 할당되지 않을 수도 있습니다.

열거형

"normal"
일반 브라우저 창

"popup"
브라우저 팝업입니다.

"panel"
이 API에서는 지원 중단되었습니다. Chrome 앱 패널 스타일 창입니다. 확장 프로그램은 자체 패널 창만 볼 수 있습니다.

"app"
이 API에서 지원 중단되었습니다. Chrome 앱 창입니다. 확장 프로그램은 앱 자체 창만 볼 수 있습니다.

"devtools"
개발자 도구 창

속성

WINDOW_ID_CURRENT

현재 창을 나타내는 windowId 값입니다.

값

-2

WINDOW_ID_NONE

Chrome 브라우저 창이 없음을 나타내는 windowId 값입니다.

값

-1

방법

create()

프로미스

chrome.windows.create(
  createData?: object,
  callback?: function,
)

크기, 위치 또는 기본 URL을 선택적으로 입력하여 새 브라우저 창을 만듭니다 (열림).

매개변수

• createData

  객체 선택사항

  • 집중

    부울 선택사항

    true인 경우 활성 창이 열립니다. false인 경우 비활성 창이 열립니다.

  • 키

    number 선택사항

    프레임을 포함한 새 창의 높이(픽셀)입니다. 지정되지 않은 경우 기본값은 자연스러운 높이입니다.

  • 시크릿 모드

    부울 선택사항

    새 창을 시크릿 창으로 표시할지 여부입니다.

  • 왼쪽

    number 선택사항

    화면의 왼쪽 가장자리를 기준으로 새 창을 배치할 픽셀 수입니다. 지정하지 않으면 새 창이 마지막으로 포커스가 맞춰진 창으로부터 자연스럽게 오프셋됩니다. 패널의 경우 이 값은 무시됩니다.

  • setSelfAsOpener

    부울 선택사항

    Chrome 64 이상

    true이면 새로 생성된 창의 'window.opener'가 호출자로 설정되고 호출자와 동일한 관련 브라우징 컨텍스트 단위에 포함됩니다.

  • state

    WindowState (선택사항)

    Chrome 44 이상

    창의 초기 상태입니다. minimized, maximized, fullscreen 상태는 left, top, width 또는 height와 결합할 수 없습니다.

  • tabId

    number 선택사항

    새 창에 추가할 탭의 ID입니다.

  • 상단

    number 선택사항

    화면의 상단 가장자리를 기준으로 새 창을 배치할 픽셀 수입니다. 지정하지 않으면 새 창이 마지막으로 포커스가 맞춰진 창으로부터 자연스럽게 오프셋됩니다. 패널의 경우 이 값은 무시됩니다.

  • 유형

    CreateType 선택사항

    생성할 브라우저 창의 유형을 지정합니다.

  • url

    string|string[] optional

    창에서 탭으로 열 URL 또는 URL의 배열입니다. 정규화된 URL에는 스키마를 포함해야 합니다(예: 'www.google.com'이 아닌 'http://www.google.com'입니다. 정규화된 URL이 아닌 URL은 확장 프로그램 내에서 상대 URL로 간주됩니다. 기본값은 새 탭 페이지입니다.

  • 너비

    number 선택사항

    프레임을 포함한 새 창의 너비(픽셀)입니다. 지정하지 않으면 기본 너비로 설정됩니다.

• 콜백

  함수 선택사항

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

  (window?: Window)=>void

  • 창

    기간 선택사항

    생성된 창에 관한 세부정보를 포함합니다.

반환 값

• 프로미스<Window|undefined>

  Chrome 88 이상

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

get()

프로미스

chrome.windows.get(
  windowId: number,
  queryOptions?: QueryOptions,
  callback?: function,
)

창에 대한 세부정보를 가져옵니다.

매개변수

• windowId

  숫자

• queryOptions

  QueryOptions 선택사항

  Chrome 88 이상
• 콜백

  함수 선택사항

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

  (window: Window)=>void

  • 창

    창

반환 값

• 프로미스<Window>

  Chrome 88 이상

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

getAll()

프로미스

chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
)

모든 창을 가져옵니다.

매개변수

• queryOptions

  QueryOptions 선택사항

  Chrome 88 이상
• 콜백

  함수 선택사항

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

  (windows: Window[])=>void

  • 창문

    창[]

반환 값

• 프로미스<창[]>

  Chrome 88 이상

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

getCurrent()

프로미스

chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
)

현재 창을 가져옵니다.

매개변수

• queryOptions

  QueryOptions 선택사항

  Chrome 88 이상
• 콜백

  함수 선택사항

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

  (window: Window)=>void

  • 창

    창

반환 값

• 프로미스<Window>

  Chrome 88 이상

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

getLastFocused()

프로미스

chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
)

가장 최근에 포커스가 맞춰진 창(일반적으로 '상단'의 창)을 가져옵니다.

매개변수

• queryOptions

  QueryOptions 선택사항

  Chrome 88 이상
• 콜백

  함수 선택사항

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

  (window: Window)=>void

  • 창

    창

반환 값

• 프로미스<Window>

  Chrome 88 이상

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

remove()

프로미스

chrome.windows.remove(
  windowId: number,
  callback?: function,
)

창과 창 내부의 모든 탭을 삭제 (닫습니다).

매개변수

• windowId

  숫자

• 콜백

  함수 선택사항

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

  ()=>void

반환 값

• Promise<void>

  Chrome 88 이상

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

update()

프로미스

chrome.windows.update(
  windowId: number,
  updateInfo: object,
  callback?: function,
)

창의 속성을 업데이트합니다. 변경할 속성만 지정합니다. 지정되지 않은 속성은 변경되지 않습니다.

매개변수

• windowId

  숫자

• updateInfo

  객체

  • drawAttention

    부울 선택사항

    true인 경우 포커스가 맞춰진 창을 변경하지 않고 창에 사용자의 관심을 끄는 방식으로 창이 표시됩니다. 효과는 사용자가 창으로 포커스를 변경할 때까지 지속됩니다. 창에 이미 포커스가 있으면 이 옵션은 아무런 영향을 미치지 않습니다. 이전 drawAttention 요청을 취소하려면 false로 설정합니다.

  • 집중

    부울 선택사항

    true인 경우 창을 앞으로 가져옵니다. '최소화됨' 상태와 결합할 수 없습니다. false인 경우 z 순서의 다음 창을 앞으로 가져옵니다. '전체화면' 또는 '최대화됨' 상태와 결합할 수 없습니다.

  • 키

    number 선택사항

    창 크기를 조절할 높이입니다(단위: 픽셀). 패널의 경우 이 값은 무시됩니다.

  • 왼쪽

    number 선택사항

    창을 이동할 화면의 왼쪽 가장자리로부터의 오프셋입니다(단위: 픽셀). 패널의 경우 이 값은 무시됩니다.

  • state

    WindowState (선택사항)

    창의 새 상태입니다. '최소화됨', '최대화됨', '전체 화면' 상태는 '왼쪽', '상단', '너비' 또는 '높이'와 결합할 수 없습니다.

  • 상단

    number 선택사항

    창을 이동할 화면의 상단 가장자리로부터의 오프셋입니다(단위: 픽셀). 패널의 경우 이 값은 무시됩니다.

  • 너비

    number 선택사항

    창 크기를 조절할 너비입니다(단위: 픽셀). 패널의 경우 이 값은 무시됩니다.

• 콜백

  함수 선택사항

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

  (window: Window)=>void

  • 창

    창

반환 값

• 프로미스<Window>

  Chrome 88 이상

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

이벤트

onBoundsChanged

Chrome 86 이상

chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

창 크기가 조절되면 발생합니다. 이 이벤트는 새 경계가 커밋되는 경우에만 전달되고 진행 중인 변경에는 전달되지 않습니다.

매개변수

• 콜백

  기능

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

  (window: Window)=>void

  • 창

    창

onCreated

chrome.windows.onCreated.addListener(
  callback: function,
  filters?: object,
)

창이 생성되면 실행됩니다.

매개변수

• 콜백

  기능

  Chrome 46 이상

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

  (window: Window)=>void

  • 창

    창

    생성된 창의 세부정보입니다.

• 필터

  객체 선택사항

  • windowTypes

    WindowType[]

    생성 중인 창의 유형이 충족해야 하는 조건입니다. 기본적으로 ['normal', 'popup']를 충족합니다.

onFocusChanged

chrome.windows.onFocusChanged.addListener(
  callback: function,
  filters?: object,
)

현재 포커스가 설정된 창이 변경되면 실행됩니다. 모든 Chrome 창에 포커스가 없으면 chrome.windows.WINDOW_ID_NONE를 반환합니다. 참고: 일부 Linux 창 관리자의 경우 Chrome 창 간에 전환 직전에 항상 WINDOW_ID_NONE가 전송됩니다.

매개변수

• 콜백

  기능

  Chrome 46 이상

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

  (windowId: number)=>void

  • windowId

    숫자

    새로 포커스가 맞춰진 창의 ID입니다.

• 필터

  객체 선택사항

  • windowTypes

    WindowType[]

    삭제할 창 유형이 충족해야 하는 조건입니다. 기본적으로 ['normal', 'popup']를 충족합니다.

onRemoved

chrome.windows.onRemoved.addListener(
  callback: function,
  filters?: object,
)

창이 삭제 (닫히면)되면 실행됩니다.

매개변수

• 콜백

  기능

  Chrome 46 이상

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

  (windowId: number)=>void

  • windowId

    숫자

    삭제된 창의 ID입니다.

• 필터

  객체 선택사항

  • windowTypes

    WindowType[]

    삭제할 창 유형이 충족해야 하는 조건입니다. 기본적으로 ['normal', 'popup']를 충족합니다.