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

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 이상

만들 브라우저 창의 유형을 지정합니다. '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

부울

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

부울

창이 현재 포커스가 있는 창인지 여부입니다.
높이

번호 선택사항

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

번호 선택사항

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

부울

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

번호 선택사항

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

문자열 선택사항

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

WindowState 선택사항

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

Tab[] 선택사항

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

번호 선택사항

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

WindowType 선택사항

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

번호 선택사항

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

WindowState

Chrome 44 이상

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

열거형

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

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

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

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

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

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()

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

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

매개변수

createData

객체 선택사항
- 집중
  
  불리언 선택사항
  
  true인 경우 활성 창을 엽니다. false인 경우 비활성 창이 열립니다.
- 높이
  
  번호 선택사항
  
  프레임을 포함한 새 창의 높이(픽셀)입니다. 지정되지 않은 경우 기본값은 자연스러운 높이입니다.
- 시크릿 모드
  
  불리언 선택사항
  
  새 창이 시크릿 창이어야 하는지 여부입니다.
- 왼쪽
  
  번호 선택사항
  
  화면 왼쪽 가장자리에서 새 창을 배치할 픽셀 수입니다. 지정하지 않으면 새 창이 마지막으로 포커스가 맞춰진 창에서 자연스럽게 오프셋됩니다. 이 값은 패널에서 무시됩니다.
- setSelfAsOpener
  
  불리언 선택사항
  
  Chrome 64 이상
  
  true인 경우 새로 생성된 창의 'window.opener'가 호출자로 설정되고 호출자와 동일한 관련 탐색 컨텍스트 단위에 있습니다.
- 주
  
  WindowState 선택사항
  
  Chrome 44 이상
  
  창의 초기 상태입니다. minimized, maximized, fullscreen 상태는 left, top, width, height와 결합할 수 없습니다.
- tabId
  
  번호 선택사항
  
  새 창에 추가할 탭의 ID입니다.
- 상단
  
  번호 선택사항
  
  화면 상단 가장자리에서 새 창을 배치할 픽셀 수입니다. 지정하지 않으면 새 창이 마지막으로 포커스가 맞춰진 창에서 자연스럽게 오프셋됩니다. 이 값은 패널에서 무시됩니다.
- 유형
  
  CreateType 선택사항
  
  만들 브라우저 창의 유형을 지정합니다.
- URL
  
  문자열 | 문자열[] 선택사항
  
  창에서 탭으로 열 URL 또는 URL 배열입니다. 정규화된 URL에는 스킴이 포함되어야 합니다(예: 'www.google.com'이 아닌 'http://www.google.com' 정규화되지 않은 URL은 확장 프로그램 내에서 상대적으로 간주됩니다. 기본값은 새 탭 페이지입니다.
- 너비
  
  번호 선택사항
  
  프레임을 포함한 새 창의 너비(픽셀)입니다. 지정되지 않은 경우 기본값은 자연 너비입니다.

반환 값

Promise<Window | undefined>

Chrome 88 이상

get()

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

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

매개변수

windowId

숫자
queryOptions

QueryOptions 선택사항

Chrome 88 이상

반환 값

Promise<Window>

Chrome 88 이상

getAll()

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

모든 창을 가져옵니다.

매개변수

queryOptions

QueryOptions 선택사항

Chrome 88 이상

반환 값

Promise<Window[]>

Chrome 88 이상

getCurrent()

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

현재 창을 가져옵니다.

매개변수

queryOptions

QueryOptions 선택사항

Chrome 88 이상

반환 값

Promise<Window>

Chrome 88 이상

getLastFocused()

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

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

매개변수

queryOptions

QueryOptions 선택사항

Chrome 88 이상

반환 값

Promise<Window>

Chrome 88 이상

remove()

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

창과 그 안의 모든 탭을 닫습니다.

매개변수

windowId

숫자

반환 값

Promise<void>

Chrome 88 이상

update()

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

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

매개변수

windowId

숫자
updateInfo

객체
- drawAttention
  
  불리언 선택사항
  
  true인 경우 포커스가 맞춰진 창을 변경하지 않고 사용자의 주의를 끄는 방식으로 창이 표시됩니다. 이 효과는 사용자가 포커스를 창으로 변경할 때까지 지속됩니다. 창에 이미 포커스가 있는 경우 이 옵션은 아무런 영향을 미치지 않습니다. 이전 drawAttention 요청을 취소하려면 false로 설정합니다.
- 집중
  
  불리언 선택사항
  
  true: 창을 맨 앞으로 가져옵니다. '최소화됨' 상태와 결합할 수 없습니다. false: z-순서에서 다음 창을 앞으로 가져옵니다. '전체 화면' 또는 '최대화' 상태와 결합할 수 없습니다.
- 높이
  
  번호 선택사항
  
  창의 크기를 조정할 높이(픽셀)입니다. 이 값은 패널에서 무시됩니다.
- 왼쪽
  
  번호 선택사항
  
  창을 이동할 화면의 왼쪽 가장자리로부터의 오프셋(픽셀)입니다. 이 값은 패널에서 무시됩니다.
- 주
  
  WindowState 선택사항
  
  창의 새 상태입니다. 'minimized', 'maximized', 'fullscreen' 상태는 'left', 'top', 'width', 'height'와 결합할 수 없습니다.
- 상단
  
  번호 선택사항
  
  창을 이동할 화면 상단 가장자리까지의 오프셋(픽셀)입니다. 이 값은 패널에서 무시됩니다.
- 너비
  
  번호 선택사항
  
  창의 크기를 조정할 너비(픽셀)입니다. 이 값은 패널에서 무시됩니다.

반환 값

Promise<Window>

Chrome 88 이상

이벤트

onBoundsChanged

Chrome 86 이상

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

창의 크기가 조절될 때 발생합니다. 이 이벤트는 새로운 경계가 커밋될 때만 디스패치되며 진행 중인 변경사항에는 디스패치되지 않습니다.

매개변수

callback

함수

callback 매개변수는 다음과 같습니다.
```
(window: Window) => void
```
- 창
  
  Window

onCreated

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

창이 생성될 때 발생합니다.

매개변수

callback

함수

Chrome 46 이상

callback 매개변수는 다음과 같습니다.
```
(window: Window) => void
```
- 창
  
  Window
  
  생성된 창의 세부정보입니다.
필터

객체 선택사항
- 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']를 충족합니다.

chrome.windows 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

설명

권한

개념 및 사용

현재 창

예

유형

CreateType

열거형

QueryOptions

속성

Window

속성

WindowState

열거형

WindowType

열거형

속성

WINDOW_ID_CURRENT

값

WINDOW_ID_NONE

값

메서드

create()

매개변수

반환 값

get()

매개변수

반환 값

getAll()

매개변수

반환 값

getCurrent()

매개변수

반환 값

getLastFocused()

매개변수

반환 값

remove()

매개변수

반환 값

update()

매개변수

반환 값

이벤트

onBoundsChanged

매개변수

onCreated

매개변수

onFocusChanged

매개변수

onRemoved

매개변수

chrome.windows