설명
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 OS의 허용 목록에 있는 기존 확장 프로그램에서만 사용할 수 있습니다.
enum
"normal"
창을 표준 창으로 지정합니다.
"popup"
창을 팝업 창으로 지정합니다.
"panel"
창을 패널로 지정합니다.
QueryOptions
속성
-
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
이 브라우저 창의 상태입니다. 경우에 따라 창에 state
속성이 할당되지 않을 수도 있습니다(예: sessions
API에서 닫힌 창을 쿼리할 때).
enum
"normal"
일반 창 상태 (최소화, 최대화 또는 전체 화면 아님).
"minimized"
최소화된 창 상태.
"maximized"
창 상태 최대화
"fullscreen"
전체 화면 창 상태
"locked-fullscreen"
잠긴 전체화면 창 상태입니다. 이 전체 화면 상태는 사용자 작업으로 종료할 수 없으며 Chrome OS의 허용 목록에 있는 확장 프로그램에서만 사용할 수 있습니다.
WindowType
브라우저 창의 유형입니다. 예를 들어 sessions
API에서 닫힌 창을 쿼리할 때처럼 창에 type
속성이 할당되지 않을 수도 있습니다.
enum
"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[] 선택사항
창에서 탭으로 열 URL 또는 URL의 배열입니다. 정규화된 URL에는 스키마를 포함해야 합니다(예: 'www.google.com'이 아닌 'http://www.google.com'입니다. 정규화된 URL이 아닌 URL은 확장 프로그램 내에서 상대 URL로 간주됩니다. 기본값은 새 탭 페이지입니다.
-
너비
number 선택사항
프레임을 포함한 새 창의 너비(픽셀)입니다. 지정하지 않으면 기본 너비로 설정됩니다.
-
-
callback
함수 선택사항
callback
매개변수는 다음과 같습니다.(window?: Window) => void
-
창
기간 선택사항
생성된 창에 관한 세부정보를 포함합니다.
-
반환 값
-
Promise<Window | undefined>
Chrome 88 이상프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
get()
chrome.windows.get(
windowId: number,
queryOptions?: QueryOptions,
callback?: function,
)
창에 대한 세부정보를 가져옵니다.
매개변수
-
windowId
숫자
-
queryOptions
QueryOptions 선택사항
Chrome 88 이상 -
callback
함수 선택사항
callback
매개변수는 다음과 같습니다.(window: Window) => void
-
창
-
반환 값
-
프로미스<Window>
Chrome 88 이상프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
getAll()
chrome.windows.getAll(
queryOptions?: QueryOptions,
callback?: function,
)
모든 창을 가져옵니다.
매개변수
-
queryOptions
QueryOptions 선택사항
Chrome 88 이상 -
callback
함수 선택사항
callback
매개변수는 다음과 같습니다.(windows: Window[]) => void
-
창문
창[]
-
반환 값
-
프로미스<창[]>
Chrome 88 이상프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
getCurrent()
chrome.windows.getCurrent(
queryOptions?: QueryOptions,
callback?: function,
)
현재 창을 가져옵니다.
매개변수
-
queryOptions
QueryOptions 선택사항
Chrome 88 이상 -
callback
함수 선택사항
callback
매개변수는 다음과 같습니다.(window: Window) => void
-
창
-
반환 값
-
프로미스<Window>
Chrome 88 이상프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
getLastFocused()
chrome.windows.getLastFocused(
queryOptions?: QueryOptions,
callback?: function,
)
가장 최근에 포커스가 맞춰진 창(일반적으로 '상단'의 창)을 가져옵니다.
매개변수
-
queryOptions
QueryOptions 선택사항
Chrome 88 이상 -
callback
함수 선택사항
callback
매개변수는 다음과 같습니다.(window: Window) => void
-
창
-
반환 값
-
프로미스<Window>
Chrome 88 이상프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
remove()
chrome.windows.remove(
windowId: number,
callback?: function,
)
창과 창 내부의 모든 탭을 삭제 (닫습니다).
매개변수
-
windowId
숫자
-
callback
함수 선택사항
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
함수 선택사항
callback
매개변수는 다음과 같습니다.(window: Window) => void
-
창
-
반환 값
-
프로미스<Window>
Chrome 88 이상프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
이벤트
onBoundsChanged
chrome.windows.onBoundsChanged.addListener(
callback: function,
)
창 크기가 조절되면 발생합니다. 이 이벤트는 새 경계가 커밋되는 경우에만 전달되고 진행 중인 변경에는 전달되지 않습니다.
onCreated
chrome.windows.onCreated.addListener(
callback: function,
filters?: object,
)
창이 생성되면 실행됩니다.
매개변수
-
callback
기능
Chrome 46 이상callback
매개변수는 다음과 같습니다.(window: Window) => void
-
창
생성된 창의 세부정보입니다.
-
-
필터
객체 선택사항
-
windowTypes
생성 중인 창의 유형이 충족해야 하는 조건입니다. 기본적으로
['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
삭제할 창 유형이 충족해야 하는 조건입니다. 기본적으로
['normal', 'popup']
를 충족합니다.
-
onRemoved
chrome.windows.onRemoved.addListener(
callback: function,
filters?: object,
)
창이 삭제 (닫히면)되면 실행됩니다.
매개변수
-
callback
기능
Chrome 46 이상callback
매개변수는 다음과 같습니다.(windowId: number) => void
-
windowId
숫자
삭제된 창의 ID입니다.
-
-
필터
객체 선택사항
-
windowTypes
삭제할 창 유형이 충족해야 하는 조건입니다. 기본적으로
['normal', 'popup']
를 충족합니다.
-