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

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

예

창 2개(각 창에 탭 1개)

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

유형

CreateType

Chrome 44 이상

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

열거형

'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(숫자) 선택사항

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

  • id

    number(숫자) 선택사항

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

  • 시크릿 모드

    부울

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

  • 왼쪽

    number(숫자) 선택사항

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

  • sessionId

    문자열 선택사항

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

  • 주

    WindowState 선택사항

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

  • tabs

    탭[] 선택사항

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

  • 상단

    number(숫자) 선택사항

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

  • 유형

    WindowType 선택사항

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

  • 너비

    number(숫자) 선택사항

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

WindowState

Chrome 44 이상

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

열거형

'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(숫자) 선택사항

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

    • 시크릿 모드

      불리언 선택사항

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

    • 왼쪽

      number(숫자) 선택사항

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

    • setSelfAsOpener

      불리언 선택사항

      Chrome 64 이상

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

    • 주

      WindowState 선택사항

      Chrome 44 이상

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

    • tabId

      number(숫자) 선택사항

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

    • 상단

      number(숫자) 선택사항

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

    • 유형

      CreateType 선택사항

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

    • URL

      문자열 | 문자열[] 선택사항

      창에서 탭으로 열 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

반환 값

  • 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

반환 값

  • Promise<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: 창을 맨 앞으로 가져옵니다. '최소화' 상태와 결합할 수 없습니다. false는 z-순서에서 다음 창을 앞으로 가져옵니다. '전체 화면' 또는 '최대화' 상태와 결합할 수 없습니다.

    • 높이

      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 창 관리자에서는 WINDOW_ID_NONE가 한 Chrome 창에서 다른 창으로 전환되기 직전에 항상 전송됩니다.

매개변수

  • 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']를 충족합니다.