chrome.windows

Deskripsi

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

Izin

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

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

Konsep dan penggunaan

Jendela saat ini

Banyak fungsi dalam sistem ekstensi menggunakan argumen windowId opsional, yang secara default disetel ke jendela saat ini.

Jendela saat ini adalah jendela yang berisi kode yang sedang dieksekusi. Penting untuk disadari bahwa ini mungkin berbeda dengan jendela paling atas atau yang difokuskan.

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

Dalam kasus pekerja layanan, nilai jendela saat ini akan kembali ke jendela aktif terakhir. Dalam kondisi tertentu, mungkin tidak ada jendela aktif untuk halaman latar belakang.

Contoh

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

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

Jenis

CreateType

Chrome 44+

Menentukan jenis jendela browser yang akan dibuat. 'panel' tidak digunakan lagi dan hanya tersedia untuk ekstensi yang diizinkan yang sudah ada 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 di atas.

  • terfokus

    boolean

    Apakah jendela saat ini adalah jendela yang difokuskan.

  • tinggi

    nomor opsional

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

  • id

    nomor opsional

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

  • samaran

    boolean

    Apakah jendela dalam mode samaran.

  • left

    nomor opsional

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

  • sessionId

    string opsional

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

  • state

    WindowState opsional

    Status jendela browser ini.

  • tab

    Tab[] opsional

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

  • paruh pertama inning

    nomor opsional

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

  • tipe

    WindowType opsional

    Jenis jendela browser ini.

  • lebar

    nomor opsional

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

WindowState

Chrome 44+

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

Enum

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

"diminimalkan"
Status jendela yang diminimalkan.

"maximized"
Status jendela yang diperbesar.

"fullscreen"
Status jendela layar penuh.

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

WindowType

Chrome 44+

Ini adalah jenis jendela browser. Dalam beberapa situasi, jendela mungkin tidak diberi properti type; misalnya, saat mengkueri jendela tertutup dari API sessions.

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 jendela aplikasinya sendiri.

"devtools"
Jendela Developer Tools.

Properti

WINDOW_ID_CURRENT

Nilai windowId yang mewakili jendela saat ini.

Nilai

-2

WINDOW_ID_NONE

Nilai windowId yang mewakili tidak adanya jendela browser Chrome.

Nilai

-1

Metode

create()

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

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

Parameter

  • createData

    objek opsional

    • terfokus

      boolean opsional

      Jika true, membuka jendela aktif. Jika false, membuka jendela tidak aktif.

    • tinggi

      nomor opsional

      Tinggi dalam piksel jendela baru, termasuk bingkai. Jika tidak ditentukan, tinggi alami akan disetel secara default.

    • samaran

      boolean opsional

      Apakah jendela baru akan berupa jendela samaran.

    • left

      nomor opsional

      Jumlah piksel untuk memosisikan jendela baru dari tepi kiri layar. Jika tidak ditentukan, jendela baru akan di-offset secara natural 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 akan ditetapkan ke pemanggil dan berada di unit konteks penjelajahan terkait yang sama dengan pemanggil.

    • state

      WindowState opsional

      Chrome 44+

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

    • tabId

      nomor opsional

      ID tab yang akan ditambahkan ke jendela baru.

    • paruh pertama inning

      nomor opsional

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

    • tipe

      CreateType opsional

      Menentukan jenis jendela browser yang akan dibuat.

    • url

      string|string[] optional

      URL atau array URL yang akan 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 akan dianggap relatif dalam ekstensi. Default-nya adalah Halaman Tab Baru.

    • lebar

      nomor opsional

      Lebar dalam piksel jendela baru, termasuk bingkai. Jika tidak ditentukan, lebar default akan ditetapkan ke lebar alami.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (window?: Window)=>void

    • jendela

      Jendela opsional

      Berisi detail tentang jendela yang dibuat.

Hasil

  • Promise<Window|undefined>

    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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

get()

Promise 
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: 

    (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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

getAll()

Promise 
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: 

    (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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

getCurrent()

Promise 
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: 

    (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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

getLastFocused()

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

Mendapatkan jendela yang paling akhir difokuskan — biasanya jendela 'di atas'.

Parameter

  • queryOptions

    QueryOptions opsional

    Chrome 88 dan yang lebih baru
  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

remove()

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

Menutup (menutup) jendela dan semua tab di dalamnya.

Parameter

  • windowId

    angka

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    ()=>void

Hasil

  • Promise<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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

update()

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

Memperbarui properti jendela. Hanya menentukan properti yang akan diubah; properti yang tidak ditentukan 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 berlaku hingga pengguna mengubah fokus ke jendela. Opsi ini tidak 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, menampilkan jendela berikutnya dalam urutan z ke depan; tidak dapat digabungkan dengan status 'layar penuh' atau 'dimaksimalkan'.

    • tinggi

      nomor opsional

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

    • left

      nomor opsional

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

    • state

      WindowState opsional

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

    • paruh pertama inning

      nomor opsional

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

    • lebar

      nomor opsional

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

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

Peristiwa

onBoundsChanged

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

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

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti: 

    (window: Window)=>void

onCreated

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

Diaktifkan saat jendela dibuat.

Parameter

  • callback

    fungsi

    Chrome 46+

    Parameter callback terlihat seperti: 

    (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: Di beberapa pengelola jendela Linux, WINDOW_ID_NONE selalu dikirim tepat sebelum pengalihan dari satu jendela Chrome ke jendela Chrome lainnya.

Parameter

  • callback

    fungsi

    Chrome 46+

    Parameter callback terlihat seperti: 

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

    Parameter callback terlihat seperti: 

    (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'].