chrome.windows

Deskripsi

Gunakan chrome.windows API untuk berinteraksi dengan jendela browser. Anda dapat menggunakan API ini untuk membuat, memodifikasi, dan mengatur ulang jendela di browser.

Izin

Saat diminta, windows.Window berisi array objek tabs.Tab. Anda harus deklarasikan izin "tabs" dalam manifes jika Anda memerlukan akses ke url, pendingUrl, title, atau favIconUrl properti tabs.Tab. Contoh:

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

Konsep dan penggunaan

Jendela saat ini

Banyak fungsi di sistem ekstensi menggunakan argumen windowId opsional, yang defaultnya adalah jendela saat ini.

Jendela saat ini adalah jendela yang berisi kode yang sedang dieksekusi. Penting penting untuk menyadari bahwa ini bisa berbeda dari jendela paling atas atau terfokus.

Misalnya, sebuah ekstensi membuat beberapa tab atau jendela dari satu file HTML, dan bahwa File HTML berisi panggilan ke tabs.query(). Jendela saat ini adalah jendela yang berisi yang melakukan panggilan, apa pun jendela paling atas.

Dalam kasus service worker, nilai periode saat ini kembali ke nilai jendela aktif terakhir jendela. Dalam beberapa situasi, mungkin tidak ada jendela aktif untuk halaman latar belakang.

Contoh

Untuk mencoba API ini, instal contoh windows API dari chrome-extension-samples repositori resource.

Dua jendela, masing-masing dengan satu tab
Dua jendela, masing-masing dengan satu tab.

Jenis

CreateType

Chrome 44 dan yang lebih baru

Menentukan jenis jendela browser yang akan dibuat. 'panel' tidak digunakan lagi dan hanya tersedia untuk ekstensi lama yang diizinkan di Chrome OS.

Enum

"normal"
Menentukan jendela sebagai jendela standar.

"popup"
Menentukan jendela sebagai jendela pop-up.

"panel"
Menentukan jendela sebagai panel.

QueryOptions

Chrome 88 dan yang lebih baru

Properti

  • mengisi

    boolean opsional

    Jika benar, objek windows.Window memiliki properti tabs yang berisi daftar objek tabs.Tab. Objek Tab hanya berisi properti url, pendingUrl, title, dan favIconUrl jika file manifes ekstensi menyertakan izin "tabs".

  • windowTypes

    WindowType[] opsional

    Jika ditetapkan, windows.Window yang ditampilkan akan difilter berdasarkan jenisnya. Jika tidak disetel, filter default akan disetel ke ['normal', 'popup'].

Window

Properti

  • alwaysOnTop

    boolean

    Apakah jendela disetel agar selalu berada di atas.

  • terfokus

    boolean

    Apakah jendela saat ini merupakan jendela yang difokuskan.

  • tinggi

    angka opsional

    Tinggi jendela, termasuk bingkai, dalam piksel. Dalam beberapa situasi, jendela mungkin tidak diberi properti height; misalnya, saat membuat kueri untuk jendela yang ditutup dari sessions API.

  • id

    angka opsional

    ID jendela. ID jendela bersifat unik dalam sesi browser. Dalam beberapa situasi, jendela mungkin tidak diberi properti ID; misalnya, saat membuat kueri periode menggunakan sessions API, dalam hal ini ID sesi mungkin ada.

  • samaran

    boolean

    Apakah jendela sedang dalam mode samaran.

  • kiri

    angka opsional

    Offset jendela dari tepi kiri layar dalam piksel. Dalam beberapa situasi, jendela mungkin tidak diberi properti left; misalnya, saat membuat kueri untuk jendela yang ditutup dari sessions API.

  • sessionId

    string opsional

    ID sesi yang digunakan untuk mengidentifikasi jendela secara unik, yang diperoleh dari sessions API.

  • dengan status tersembunyi akhir

    WindowState opsional

    Status jendela browser ini.

  • tab

    Tab[] opsional

    Array objek tabs.Tab yang mewakili tab saat ini di jendela.

  • atas

    angka opsional

    Offset jendela dari tepi atas layar dalam piksel. Dalam beberapa situasi, jendela mungkin tidak diberi properti top; misalnya, saat membuat kueri untuk jendela yang ditutup dari sessions API.

  • jenis

    WindowType opsional

    Jenis jendela browser ini.

  • lebar

    angka opsional

    Lebar jendela, termasuk bingkai, dalam piksel. Dalam beberapa situasi, jendela mungkin tidak diberi properti width; misalnya, saat membuat kueri untuk jendela yang ditutup dari sessions API.

WindowState

Chrome 44 dan yang lebih baru

Status jendela browser ini. Dalam beberapa situasi, jendela mungkin tidak diberi properti state; misalnya, saat membuat kueri untuk jendela yang ditutup dari sessions API.

Enum

"normal"
Status jendela normal (tidak diperkecil, dimaksimalkan, atau layar penuh).

"diminimalkan"
Status jendela diminimalkan.

"dimaksimalkan"
Status jendela diperbesar.

"fullscreen"
Status jendela layar penuh.

"layar penuh terkunci"
Status jendela layar penuh terkunci. Status layar penuh ini tidak dapat ditutup dengan tindakan pengguna dan hanya tersedia untuk ekstensi yang diizinkan di ChromeOS.

WindowType

Chrome 44 dan yang lebih baru

Jenis jendela browser ini. Dalam beberapa situasi, jendela mungkin tidak diberi properti type; misalnya, saat membuat kueri untuk jendela yang ditutup dari sessions API.

Enum

"normal"
Jendela browser biasa.

"popup"
Pop-up browser.

"panel"
Tidak digunakan lagi di API ini. Jendela bergaya panel Aplikasi Chrome. Ekstensi hanya dapat melihat jendela panelnya sendiri.

"app"
Tidak digunakan lagi di API ini. Jendela Aplikasi Chrome. Ekstensi hanya dapat melihat jendelanya sendiri.

"devtools"
Jendela Developer Tools.

Properti

WINDOW_ID_CURRENT

Nilai windowId yang merepresentasikan window saat ini.

Nilai

-2

WINDOW_ID_NONE

Nilai windowId yang menunjukkan tidak adanya jendela browser Chrome.

Nilai

-1

Metode

create()

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

Membuat (membuka) jendela browser baru dengan ukuran opsional, posisi, atau URL default yang disediakan.

Parameter

  • createData

    objek opsional

    • terfokus

      boolean opsional

      Jika true, jendela aktif akan terbuka. Jika false, jendela tidak aktif akan terbuka.

    • tinggi

      angka opsional

      Tinggi jendela baru dalam piksel, termasuk bingkai. Jika tidak ditentukan, defaultnya adalah tinggi alami.

    • samaran

      boolean opsional

      Apakah jendela baru harus berupa jendela samaran atau tidak.

    • kiri

      angka opsional

      Jumlah piksel untuk memosisikan jendela baru dari tepi kiri layar. Jika tidak ditentukan, jendela baru akan di-offset secara alami dari jendela yang terakhir difokuskan. Nilai ini diabaikan untuk panel.

    • setSelfAsOpener

      boolean opsional

      Chrome 64 dan yang lebih baru

      Jika true, 'window.opener' jendela yang baru dibuat disetel ke pemanggil dan berada di unit konteks penjelajahan terkait yang sama dengan pemanggil.

    • dengan status tersembunyi akhir

      WindowState opsional

      Chrome 44 dan yang lebih baru

      Status awal jendela. Status minimized, maximized, dan fullscreen tidak dapat digabungkan dengan left, top, width, atau height.

    • tabId

      angka opsional

      ID tab yang akan ditambahkan ke jendela baru.

    • atas

      angka opsional

      Jumlah piksel untuk memosisikan jendela baru dari tepi atas layar. Jika tidak ditentukan, jendela baru akan di-offset secara alami dari jendela yang terakhir difokuskan. Nilai ini diabaikan untuk panel.

    • jenis

      CreateType opsional

      Menentukan jenis jendela browser yang akan dibuat.

    • url

      string | string[] opsional

      URL atau array URL untuk dibuka sebagai tab di jendela. URL yang sepenuhnya memenuhi syarat harus menyertakan skema, misalnya, 'http://www.google.com', bukan 'www.google.com'. URL yang tidak sepenuhnya memenuhi syarat dianggap relatif dalam ekstensi. Setelan default-nya adalah Halaman Tab Baru.

    • lebar

      angka opsional

      Lebar jendela baru dalam piksel, termasuk bingkai. Jika tidak ditentukan, setelan defaultnya adalah lebar alami.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (window?: Window) => void

    • jendela

      Jendela opsional

      Berisi detail tentang jendela yang dibuat.

Hasil

  • Promise<Window | tidak terdefinisi>

    Chrome 88 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

get()

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

Mendapatkan detail tentang jendela.

Parameter

  • windowId

    angka

  • queryOptions

    QueryOptions opsional

    Chrome 88 dan yang lebih baru
  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (window: Window) => void

Hasil

  • Promise<Window>

    Chrome 88 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

getAll()

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

Mendapatkan semua jendela.

Parameter

  • queryOptions

    QueryOptions opsional

    Chrome 88 dan yang lebih baru
  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (windows: Window[]) => void

Hasil

  • Promise<Window[]>

    Chrome 88 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

getCurrent()

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

Mendapatkan jendela saat ini.

Parameter

  • queryOptions

    QueryOptions opsional

    Chrome 88 dan yang lebih baru
  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (window: Window) => void

Hasil

  • Promise<Window>

    Chrome 88 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

getLastFocused()

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

Mendapatkan jendela yang terakhir difokuskan — biasanya jendela 'di atas'.

Parameter

  • queryOptions

    QueryOptions opsional

    Chrome 88 dan yang lebih baru
  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (window: Window) => void

Hasil

  • Promise<Window>

    Chrome 88 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

remove()

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

Menghapus (menutup) jendela dan semua tab di dalamnya.

Parameter

  • windowId

    angka

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • Janji<void>

    Chrome 88 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

update()

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

Memperbarui properti jendela. Menentukan hanya properti yang akan diubah; properti yang tidak ditetapkan tidak berubah.

Parameter

  • windowId

    angka

  • updateInfo

    objek

    • drawAttention

      boolean opsional

      Jika true, menyebabkan jendela ditampilkan dengan cara yang menarik perhatian pengguna ke jendela, tanpa mengubah jendela yang difokuskan. Efek akan berlaku hingga pengguna mengubah fokus ke jendela. Opsi ini tidak akan berpengaruh jika jendela sudah memiliki fokus. Tetapkan ke false untuk membatalkan permintaan drawAttention sebelumnya.

    • terfokus

      boolean opsional

      Jika true, membawa jendela ke depan; tidak dapat digabungkan dengan status 'diminimalkan'. Jika false, memindahkan jendela berikutnya dalam urutan z ke depan; tidak dapat digabungkan dengan status 'fullscreen' atau 'dimaksimalkan'.

    • tinggi

      angka opsional

      Tinggi untuk mengubah ukuran jendela dalam piksel. Nilai ini diabaikan untuk panel.

    • kiri

      angka opsional

      Offset dari tepi kiri layar untuk memindahkan jendela dalam piksel. Nilai ini diabaikan untuk panel.

    • dengan status tersembunyi akhir

      WindowState opsional

      Status baru jendela. 'diminimalkan', 'dimaksimalkan', dan 'layar penuh' status tidak dapat digabungkan dengan 'left', 'top', 'width', atau 'height'.

    • atas

      angka opsional

      Offset dari tepi atas layar untuk memindahkan jendela dalam piksel. Nilai ini diabaikan untuk panel.

    • lebar

      angka opsional

      Lebar untuk mengubah ukuran jendela dalam piksel. Nilai ini diabaikan untuk panel.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (window: Window) => void

Hasil

  • Promise&lt;Window&gt;

    Chrome 88 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

Acara

onBoundsChanged

Chrome 86 dan yang lebih baru 
chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

Diaktifkan saat jendela diubah ukurannya; peristiwa ini hanya dikirimkan saat batas baru di-commit, dan bukan untuk perubahan yang sedang berlangsung.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    (window: Window) => void

onCreated

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

Diaktifkan saat jendela dibuat.

Parameter

  • callback

    fungsi

    Chrome 46 dan yang lebih baru

    Parameter callback terlihat seperti ini: 

    (window: Window) => void

    • jendela

      Jendela

      Detail jendela yang dibuat.

  • filter

    objek opsional

    • windowTypes

      WindowType[]

      Kondisi yang harus dipenuhi oleh jenis jendela yang dibuat. Secara default, atribut ini memenuhi ['normal', 'popup'].

onFocusChanged

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

Diaktifkan saat jendela yang saat ini difokuskan berubah. Menampilkan chrome.windows.WINDOW_ID_NONE jika semua jendela Chrome kehilangan fokus. Catatan: Pada beberapa pengelola jendela Linux, WINDOW_ID_NONE selalu dikirim tepat sebelum peralihan dari satu jendela Chrome ke jendela Chrome lainnya.

Parameter

  • callback

    fungsi

    Chrome 46 dan yang lebih baru

    Parameter callback terlihat seperti ini: 

    (windowId: number) => void

    • windowId

      angka

      ID jendela yang baru difokuskan.

  • filter

    objek opsional

    • windowTypes

      WindowType[]

      Kondisi yang harus dipenuhi oleh jenis jendela yang dihapus. Secara default, atribut ini memenuhi ['normal', 'popup'].

onRemoved

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

Diaktifkan saat jendela dihapus (ditutup).

Parameter

  • callback

    fungsi

    Chrome 46 dan yang lebih baru

    Parameter callback terlihat seperti ini: 

    (windowId: number) => void

    • windowId

      angka

      ID jendela yang dihapus.

  • filter

    objek opsional

    • windowTypes

      WindowType[]

      Kondisi yang harus dipenuhi oleh jenis jendela yang dihapus. Secara default, atribut ini memenuhi ['normal', 'popup'].