chrome.windows

refresh date: 2026-09-25 robots: noindex

설명

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() 호출이 포함되어 있다고 가정해 보겠습니다. 현재 창은 최상위 창이 무엇이든 관계없이 호출을 수행한 페이지가 포함된 창입니다.

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

예

창 2개(각 창에 탭 1개 포함)

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

유형

CreateType

Chrome 44 이상

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

열거형

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

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

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

QueryOptions

Chrome 88 이상

속성

  • populate

    불리언 선택사항

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

  • windowTypes

    WindowType[] 선택사항

    설정하면 반환된 windows.Window가 유형에 따라 필터링됩니다. 설정하지 않으면 기본 필터가 ['normal', 'popup']로 설정됩니다.

Window

속성

  • alwaysOnTop

    부울

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

  • 집중

    부울

    창이 현재 포커스가 설정된 창인지 여부입니다.

  • 높이

    number 선택사항

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

  • id

    number 선택사항

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

  • incognito

    부울

    창이 시크릿 모드인지 여부입니다.

  • 왼쪽

    number 선택사항

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

  • sessionId

    문자열 선택사항

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

  • 주

    WindowState 선택사항

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

  • tabs

    Tab[] 선택사항

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

  • 상단

    number 선택사항

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

  • 유형

    WindowType 선택사항

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

  • 너비

    number 선택사항

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

WindowState

Chrome 44 이상

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

열거형

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

'minimized'
최소화된 창 상태입니다.

'maximized'
최대화된 창 상태입니다.

'fullscreen'
전체 화면 창 상태입니다.

WindowType

Chrome 44 이상

브라우저 창의 유형입니다. 경우에 따라 창에 type 속성이 할당되지 않을 수 있습니다(예: sessions API에서 닫힌 창을 쿼리하는 경우).

열거형

'normal'
일반 브라우저 창입니다.

'popup'
브라우저 팝업

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

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

'devtools'
개발자 도구 창

속성

WINDOW_ID_CURRENT

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

값

-2

WINDOW_ID_NONE

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

값

-1

메서드

create()

Promise 
chrome.windows.create(
  createData?: object,
  callback?: function,
): Promise<Window | undefined>

제공된 선택적 크기, 위치 또는 기본 URL을 사용하여 새 브라우저 창을 만듭니다 (엽니다).

매개변수

  • createData

    객체 선택사항

    • 집중

      불리언 선택사항

      true인 경우 활성 창을 엽니다. false인 경우 비활성 창을 엽니다.

    • 높이

      number 선택사항

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

    • incognito

      불리언 선택사항

      새 창이 시크릿 창이어야 하는지 여부입니다.

    • 왼쪽

      number 선택사항

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

    • setSelfAsOpener

      불리언 선택사항

      Chrome 64 이상

      true인 경우 새로 생성된 창의 'window.opener'가 호출자로 설정되고 호출자와 동일한 관련 탐색 컨텍스트 단위에 있습니다.

    • 주

      WindowState 선택사항

      Chrome 44 이상

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

    • tabId

      number 선택사항

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

    • 상단

      number 선택사항

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

    • 유형

      CreateType 선택사항

      만들 브라우저 창의 유형을 지정합니다.

    • URL

      string | string[] 선택사항

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

    • 너비

      number 선택사항

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

  • callback

    함수 선택사항

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

    (window?: Window) => void

    • 창

      기간 선택사항

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

반환 값

  • Promise<Window | undefined>

    Chrome 88 이상

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

get()

Promise 
chrome.windows.get(
  windowId: number,
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

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

매개변수

  • windowId

    숫자

  • queryOptions

    QueryOptions 선택사항

    Chrome 88 이상
  • callback

    함수 선택사항

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

    (window: Window) => void

반환 값

  • Promise<Window>

    Chrome 88 이상

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

getAll()

Promise 
chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window[]>

모든 창을 가져옵니다.

매개변수

  • queryOptions

    QueryOptions 선택사항

    Chrome 88 이상
  • callback

    함수 선택사항

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

    (windows: Window[]) => void

    • windows

      창[]

반환 값

  • Promise<Window[]>

    Chrome 88 이상

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

getCurrent()

Promise 
chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

현재 창을 가져옵니다.

매개변수

  • queryOptions

    QueryOptions 선택사항

    Chrome 88 이상
  • callback

    함수 선택사항

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

    (window: Window) => void

반환 값

  • Promise<Window>

    Chrome 88 이상

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

getLastFocused()

Promise 
chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

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

매개변수

  • queryOptions

    QueryOptions 선택사항

    Chrome 88 이상
  • callback

    함수 선택사항

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

    (window: Window) => void

반환 값

  • Promise<Window>

    Chrome 88 이상

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

remove()

Promise 
chrome.windows.remove(
  windowId: number,
  callback?: function,
): Promise<void>

창과 창 안의 모든 탭을 삭제 (닫기)합니다.

매개변수

  • windowId

    숫자

  • callback

    함수 선택사항

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

    () => void

반환 값

  • 약속<void>

    Chrome 88 이상

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

update()

Promise 
chrome.windows.update(
  windowId: number,
  updateInfo: object,
  callback?: function,
): Promise<Window>

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

매개변수

  • windowId

    숫자

  • updateInfo

    객체

    • drawAttention

      불리언 선택사항

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

    • 집중

      불리언 선택사항

      true인 경우 창을 앞으로 가져옵니다. 'minimized' 상태와 결합할 수 없습니다. false인 경우 z 순서의 다음 창을 앞으로 가져옵니다. 'fullscreen' 또는 'maximized' 상태와 결합할 수 없습니다.

    • 높이

      number 선택사항

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

    • 왼쪽

      number 선택사항

      화면의 왼쪽 가장자리에서 창을 이동할 오프셋(픽셀)입니다. 패널의 경우 이 값이 무시됩니다.

    • 주

      WindowState 선택사항

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

    • 상단

      number 선택사항

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

    • 너비

      number 선택사항

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

  • callback

    함수 선택사항

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

    (window: Window) => void

반환 값

  • Promise<Window>

    Chrome 88 이상

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

이벤트

onBoundsChanged

Chrome 86 이상 
chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

창 크기가 조절될 때 실행됩니다. 이 이벤트는 새 경계가 커밋될 때만 전달되며 진행 중인 변경사항에는 전달되지 않습니다.

매개변수

  • callback

    함수

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

    (window: Window) => void

onCreated

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

창이 생성될 때 실행됩니다.

매개변수

  • callback

    함수

    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가 전송됩니다.

매개변수

  • callback

    함수

    Chrome 46 이상

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

    (windowId: number) => void

    • windowId

      숫자

      새로 포커스가 지정된 창의 ID입니다.

  • 필터

    객체 선택사항

    • windowTypes

      WindowType[]

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

onRemoved

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

창이 삭제 (닫힘)될 때 실행됩니다.

매개변수

  • callback

    함수

    Chrome 46 이상

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

    (windowId: number) => void

    • windowId

      숫자

      삭제된 창의 ID입니다.

  • 필터

    객체 선택사항

    • windowTypes

      WindowType[]

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