browser.windows

คำอธิบาย

ใช้ chrome.windows API เพื่อโต้ตอบกับหน้าต่างเบราว์เซอร์ คุณสามารถใช้ API นี้เพื่อสร้าง แก้ไข และจัดเรียงหน้าต่างใหม่ในเบราว์เซอร์ได้

สิทธิ์

เมื่อมีการขอ windows.Window จะมีอาร์เรย์ของออบเจ็กต์ tabs.Tab คุณต้องประกาศสิทธิ์ "tabs" ในไฟล์ Manifest หากต้องการเข้าถึงพร็อพเพอร์ตี้ url, pendingUrl, title หรือ favIconUrl ของ tabs.Tab เช่น

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

แนวคิดและการใช้งาน

หน้าต่างปัจจุบัน

ฟังก์ชันหลายรายการในระบบส่วนขยายจะใช้อาร์กิวเมนต์ windowId ที่ไม่บังคับ ซึ่งค่าเริ่มต้นจะเป็นหน้าต่างปัจจุบัน

หน้าต่างปัจจุบันคือหน้าต่างที่มีโค้ดที่กำลังทำงานอยู่ โปรดทราบว่าหน้าต่างนี้อาจแตกต่างจากหน้าต่างบนสุดหรือหน้าต่างที่โฟกัสอยู่

ตัวอย่างเช่น สมมติว่าส่วนขยายสร้างแท็บหรือหน้าต่าง 2-3 รายการจากไฟล์ HTML ไฟล์เดียว และไฟล์ HTML นั้นมีการเรียกใช้ tabs.query() หน้าต่างปัจจุบันคือหน้าต่างที่มีหน้าเว็บที่ทำการเรียก ไม่ว่าหน้าต่างบนสุดจะเป็นหน้าต่างใดก็ตาม

ในกรณีของ Service Worker ค่าของหน้าต่างปัจจุบันจะกลับไปเป็นหน้าต่างที่ใช้งานล่าสุด ในบางกรณี อาจไม่มีหน้าต่างปัจจุบันสำหรับหน้าพื้นหลัง

ตัวอย่าง

หากต้องการลองใช้ API นี้ ให้ติดตั้งตัวอย่าง Windows API จากที่เก็บ chrome-extension-samples

หน้าต่าง 2 หน้าต่าง โดยแต่ละหน้าต่างมี 1 แท็บ

ประเภท

CreateType

Chrome 44 ขึ้นไป browser.* ตั้งแต่ Chrome 148

ระบุประเภทของหน้าต่างเบราว์เซอร์ที่จะสร้าง เลิกใช้งาน "แผง" แล้ว และใช้ได้เฉพาะกับส่วนขยายที่อยู่ในรายการที่อนุญาตที่มีอยู่บน ChromeOS เท่านั้น

ค่าแจกแจง

"normal"
ระบุหน้าต่างเป็นหน้าต่างมาตรฐาน

"popup"
ระบุหน้าต่างเป็นหน้าต่างป๊อปอัป

"panel"
ระบุหน้าต่างเป็นแผง

QueryOptions

Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

พร็อพเพอร์ตี้

• ป้อนข้อมูล

  บูลีน ไม่บังคับ

  หากเป็นจริง ออบเจ็กต์ windows.Window จะมีพร็อพเพอร์ตี้ tabs ที่มีรายการออบเจ็กต์ tabs.Tab ออบเจ็กต์ Tab จะมีเฉพาะพร็อพเพอร์ตี้ url, pendingUrl, title และ favIconUrl หากไฟล์ Manifest ของส่วนขยายมีสิทธิ์ "tabs"

• windowTypes

  WindowType[] ไม่บังคับ

  หากตั้งค่าไว้ ระบบจะกรอง windows.Window ที่แสดงผลตามประเภท หากไม่ได้ตั้งค่า ระบบจะตั้งค่าตัวกรองเริ่มต้นเป็น ['normal', 'popup']

Window

พร็อพเพอร์ตี้

• alwaysOnTop

  บูลีน

  หน้าต่างตั้งค่าให้อยู่ด้านบนเสมอหรือไม่

• โฟกัสอยู่

  บูลีน

  หน้าต่างเป็นหน้าต่างที่โฟกัสอยู่หรือไม่

• ความสูง

  number ไม่บังคับ

  ความสูงของหน้าต่าง รวมถึงเฟรม มีหน่วยเป็นพิกเซล ในบางกรณี หน้าต่างอาจไม่ได้รับการกำหนดพร็อพเพอร์ตี้ height เช่น เมื่อค้นหาหน้าต่างที่ปิดจาก sessions API

• id

  number ไม่บังคับ

  รหัสของหน้าต่าง รหัสหน้าต่างจะไม่ซ้ำกันภายในเซสชันของเบราว์เซอร์ ในบางกรณี หน้าต่างอาจไม่ได้รับการกำหนดพร็อพเพอร์ตี้ ID เช่น เมื่อค้นหาหน้าต่างโดยใช้ sessions API ซึ่งในกรณีนี้อาจมีรหัสเซสชันอยู่

• ไม่ระบุตัวตน

  บูลีน

  หน้าต่างเป็นแบบไม่ระบุตัวตนหรือไม่

• ซ้าย

  number ไม่บังคับ

  ออฟเซ็ตของหน้าต่างจากขอบด้านซ้ายของหน้าจอในหน่วยพิกเซล ในบางกรณี หน้าต่างอาจไม่ได้รับการกำหนดพร็อพเพอร์ตี้ left เช่น เมื่อค้นหาหน้าต่างที่ปิดจาก sessions API

• sessionId

  สตริง ไม่บังคับ

  รหัสเซสชันที่ใช้ในการระบุหน้าต่างโดยไม่ซ้ำกัน ซึ่งได้มาจาก sessions API

• รัฐ

  WindowState ไม่บังคับ

  สถานะของหน้าต่างเบราว์เซอร์นี้

• tabs

  Tab[] ไม่บังคับ

  อาร์เรย์ของออบเจ็กต์ tabs.Tab ที่แสดงถึงแท็บปัจจุบันในหน้าต่าง

• ด้านบน

  number ไม่บังคับ

  ออฟเซ็ตของหน้าต่างจากขอบด้านบนของหน้าจอในหน่วยพิกเซล ในบางกรณี หน้าต่างอาจไม่ได้รับการกำหนดพร็อพเพอร์ตี้ top เช่น เมื่อค้นหาหน้าต่างที่ปิดจาก sessions API

• ประเภท

  WindowType ไม่บังคับ

  ประเภทของหน้าต่างเบราว์เซอร์นี้

• ความกว้าง

  number ไม่บังคับ

  ความกว้างของหน้าต่าง รวมถึงเฟรม ในหน่วยพิกเซล ในบางกรณี หน้าต่างอาจไม่ได้รับการกำหนดพร็อพเพอร์ตี้ width เช่น เมื่อค้นหาหน้าต่างที่ปิดจาก sessions API

WindowState

Chrome 44 ขึ้นไป browser.* ตั้งแต่ Chrome 148

สถานะของหน้าต่างเบราว์เซอร์นี้ ในบางกรณี หน้าต่างอาจไม่ได้รับการกำหนดพร็อพเพอร์ตี้ state เช่น เมื่อค้นหาหน้าต่างที่ปิดจาก sessions API

ค่าแจกแจง

"normal"
สถานะหน้าต่างปกติ (ไม่ได้ย่อ ขยายใหญ่สุด หรือเต็มหน้าจอ)

"minimized"
สถานะหน้าต่างที่ย่อ

"maximized"
สถานะหน้าต่างที่ขยายใหญ่สุด

"fullscreen"
สถานะหน้าต่างแบบเต็มหน้าจอ

WindowType

Chrome 44 ขึ้นไป browser.* ตั้งแต่ Chrome 148

ประเภทของหน้าต่างเบราว์เซอร์นี้ ในบางกรณี หน้าต่างอาจไม่ได้รับการกำหนดพร็อพเพอร์ตี้ type เช่น เมื่อค้นหาหน้าต่างที่ปิดจาก sessions API

ค่าแจกแจง

"normal"
หน้าต่างเบราว์เซอร์ปกติ

"popup"
ป๊อปอัปเบราว์เซอร์

"panel"
เลิกใช้งานใน API นี้ หน้าต่างสไตล์แผงของแอป Chrome ส่วนขยายจะเห็นได้เฉพาะหน้าต่างแผงของตนเองเท่านั้น

"app"
เลิกใช้งานใน API นี้ หน้าต่างแอป Chrome ส่วนขยายจะเห็นได้เฉพาะหน้าต่างแอปของตนเองเท่านั้น

"devtools"
หน้าต่างเครื่องมือสำหรับนักพัฒนาซอฟต์แวร์

พร็อพเพอร์ตี้

WINDOW_ID_CURRENT

ค่า windowId ที่แสดงหน้าต่างปัจจุบัน

ค่า

-2

WINDOW_ID_NONE

ค่า windowId ที่แสดงถึงการไม่มีหน้าต่างเบราว์เซอร์ Chrome

ค่า

-1

เมธอด

create()

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

สร้าง (เปิด) หน้าต่างเบราว์เซอร์ใหม่ที่มีขนาด ตำแหน่ง หรือ URL เริ่มต้น (ไม่บังคับ) ที่ระบุไว้

พารามิเตอร์

• createData

  object ไม่บังคับ

  • โฟกัสอยู่

    บูลีน ไม่บังคับ

    หาก true ให้เปิดหน้าต่างที่ใช้งานอยู่ หากเป็น false ระบบจะเปิดหน้าต่างที่ไม่ได้ใช้งาน

  • ความสูง

    number ไม่บังคับ

    ความสูงเป็นพิกเซลของหน้าต่างใหม่ รวมถึงเฟรม หากไม่ได้ระบุไว้ ระบบจะใช้ความสูงตามธรรมชาติเป็นค่าเริ่มต้น

  • ไม่ระบุตัวตน

    บูลีน ไม่บังคับ

    หน้าต่างใหม่ควรเป็นหน้าต่างที่ไม่ระบุตัวตนหรือไม่

  • ซ้าย

    number ไม่บังคับ

    จำนวนพิกเซลเพื่อจัดตำแหน่งหน้าต่างใหม่จากขอบด้านซ้ายของหน้าจอ หากไม่ได้ระบุ หน้าต่างใหม่จะออฟเซ็ตจากหน้าต่างที่โฟกัสล่าสุดโดยอัตโนมัติ ระบบจะไม่สนใจค่านี้สำหรับแผง

  • setSelfAsOpener

    บูลีน ไม่บังคับ

    เบราว์เซอร์ Chrome 64 ขึ้นไป * ตั้งแต่ Chrome 148

    หาก true ระบบจะตั้งค่า "window.opener" ของหน้าต่างที่สร้างขึ้นใหม่เป็นผู้เรียก และอยู่ในหน่วยของบริบทการท่องเว็บที่เกี่ยวข้องเดียวกันกับผู้เรียก

  • รัฐ

    WindowState ไม่บังคับ

    Chrome 44 ขึ้นไป browser.* ตั้งแต่ Chrome 148

    สถานะเริ่มต้นของหน้าต่าง สถานะ minimized, maximized และ fullscreen ไม่สามารถใช้ร่วมกับ left, top, width หรือ height

  • tabId

    number ไม่บังคับ

    รหัสของแท็บที่จะเพิ่มลงในหน้าต่างใหม่

  • ด้านบน

    number ไม่บังคับ

    จำนวนพิกเซลเพื่อจัดตำแหน่งหน้าต่างใหม่จากขอบด้านบนของหน้าจอ หากไม่ได้ระบุ หน้าต่างใหม่จะออฟเซ็ตจากหน้าต่างที่โฟกัสล่าสุดโดยอัตโนมัติ ระบบจะไม่สนใจค่านี้สำหรับแผง

  • ประเภท

    CreateType ไม่บังคับ

    ระบุประเภทของหน้าต่างเบราว์เซอร์ที่จะสร้าง

  • URL

    string | string[] ไม่บังคับ

    URL หรืออาร์เรย์ของ URL ที่จะเปิดเป็นแท็บในหน้าต่าง URL ที่สมบูรณ์ในตัวเองต้องมีรูปแบบ เช่น "http://www.google.com" ไม่ใช่ "www.google.com" URL ที่ไม่สมบูรณ์จะถือว่าเกี่ยวข้องภายในส่วนขยาย ค่าเริ่มต้นคือหน้าแท็บใหม่

  • ความกว้าง

    number ไม่บังคับ

    ความกว้างเป็นพิกเซลของหน้าต่างใหม่ รวมถึงเฟรม หากไม่ได้ระบุไว้ ระบบจะใช้ความกว้างตามธรรมชาติเป็นค่าเริ่มต้น

การคืนสินค้า

• Promise<Window | undefined>

  Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

get()

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

ดูรายละเอียดเกี่ยวกับหน้าต่าง

พารามิเตอร์

• windowId

  ตัวเลข

• queryOptions

  QueryOptions ไม่บังคับ

  Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

การคืนสินค้า

• Promise<Window>

  Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

getAll()

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

รับหน้าต่างทั้งหมด

พารามิเตอร์

• queryOptions

  QueryOptions ไม่บังคับ

  Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

การคืนสินค้า

• Promise<Window[]>

  Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

getCurrent()

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

รับหน้าต่างปัจจุบัน

พารามิเตอร์

• queryOptions

  QueryOptions ไม่บังคับ

  Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

การคืนสินค้า

• Promise<Window>

  Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

getLastFocused()

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

รับหน้าต่างที่โฟกัสล่าสุด ซึ่งโดยปกติจะเป็นหน้าต่าง "ด้านบน"

พารามิเตอร์

• queryOptions

  QueryOptions ไม่บังคับ

  Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

การคืนสินค้า

• Promise<Window>

  Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

remove()

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

นำ (ปิด) หน้าต่างและแท็บทั้งหมดภายในหน้าต่างออก

พารามิเตอร์

• windowId

  ตัวเลข

การคืนสินค้า

• Promise<void>

  Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

update()

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

อัปเดตพร็อพเพอร์ตี้ของหน้าต่าง ระบุเฉพาะพร็อพเพอร์ตี้ที่จะเปลี่ยนแปลง พร็อพเพอร์ตี้ที่ไม่ได้ระบุจะไม่มีการเปลี่ยนแปลง

พารามิเตอร์

• windowId

  ตัวเลข

• updateInfo

  ออบเจ็กต์

  • drawAttention

    บูลีน ไม่บังคับ

    หากเป็น true จะทำให้หน้าต่างแสดงในลักษณะที่ดึงดูดความสนใจของผู้ใช้ไปยังหน้าต่าง โดยไม่เปลี่ยนหน้าต่างที่โฟกัส เอฟเฟกต์จะคงอยู่จนกว่าผู้ใช้จะเปลี่ยนโฟกัสไปที่หน้าต่าง ตัวเลือกนี้จะไม่มีผลหากหน้าต่างโฟกัสอยู่แล้ว ตั้งค่าเป็น false เพื่อยกเลิกคำขอ drawAttention ก่อนหน้า

  • โฟกัสอยู่

    บูลีน ไม่บังคับ

    หากเป็น true จะนำหน้าต่างมาไว้ด้านหน้า โดยใช้ร่วมกับสถานะ "ย่อ" ไม่ได้ หากเป็น false จะนำหน้าต่างถัดไปในลำดับ Z มาไว้ด้านหน้า โดยไม่สามารถใช้ร่วมกับสถานะ "เต็มหน้าจอ" หรือ "ขยายใหญ่สุด" ได้

  • ความสูง

    number ไม่บังคับ

    ความสูงที่ต้องการปรับขนาดหน้าต่างเป็นพิกเซล ระบบจะไม่สนใจค่านี้สำหรับแผง

  • ซ้าย

    number ไม่บังคับ

    ออฟเซ็ตจากขอบด้านซ้ายของหน้าจอเพื่อย้ายหน้าต่างเป็นพิกเซล ระบบจะไม่สนใจค่านี้สำหรับแผง

  • รัฐ

    WindowState ไม่บังคับ

    สถานะใหม่ของหน้าต่าง สถานะ "ย่อ" "ขยาย" และ "เต็มหน้าจอ" ไม่สามารถใช้ร่วมกับ "ซ้าย" "บน" "ความกว้าง" หรือ "ความสูง" ได้

  • ด้านบน

    number ไม่บังคับ

    ออฟเซ็ตจากขอบด้านบนของหน้าจอเพื่อย้ายหน้าต่างไปเป็นพิกเซล ระบบจะไม่สนใจค่านี้สำหรับแผง

  • ความกว้าง

    number ไม่บังคับ

    ความกว้างที่จะปรับขนาดหน้าต่างเป็นพิกเซล ระบบจะไม่สนใจค่านี้สำหรับแผง

การคืนสินค้า

• Promise<Window>

  Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

กิจกรรม

onBoundsChanged

Chrome 86 ขึ้นไป browser.* ตั้งแต่ Chrome 148

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

เริ่มทำงานเมื่อมีการปรับขนาดหน้าต่าง ระบบจะส่งเหตุการณ์นี้เมื่อมีการยืนยันขอบเขตใหม่เท่านั้น และจะไม่ส่งสำหรับการเปลี่ยนแปลงที่อยู่ระหว่างดำเนินการ

พารามิเตอร์

• callback

  ฟังก์ชัน

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  (window: Window) => void

  • หน้าต่าง

    หน้าต่าง

onCreated

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

เริ่มทำงานเมื่อสร้างหน้าต่าง

พารามิเตอร์

• callback

  ฟังก์ชัน

  Chrome 46 ขึ้นไป browser.* ตั้งแต่ Chrome 148

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  (window: Window) => void

  • หน้าต่าง

    หน้าต่าง

    รายละเอียดของหน้าต่างที่สร้างขึ้น

• ตัวกรอง

  object ไม่บังคับ

  • windowTypes

    WindowType[]

    เงื่อนไขที่ประเภทของหน้าต่างที่สร้างขึ้นต้องเป็นไปตาม โดยค่าเริ่มต้นจะเป็นไปตาม ['normal', 'popup']

onFocusChanged

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

เริ่มทำงานเมื่อหน้าต่างที่โฟกัสอยู่ในปัจจุบันมีการเปลี่ยนแปลง แสดงผล chrome.windows.WINDOW_ID_NONE หากหน้าต่าง Chrome ทั้งหมดสูญเสียโฟกัส หมายเหตุ: ในตัวจัดการหน้าต่าง Linux บางตัว ระบบจะส่ง WINDOW_ID_NONE ทันทีก่อนที่จะเปลี่ยนจากหน้าต่าง Chrome หนึ่งไปยังอีกหน้าต่างหนึ่งเสมอ

พารามิเตอร์

• callback

  ฟังก์ชัน

  Chrome 46 ขึ้นไป browser.* ตั้งแต่ Chrome 148

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  (windowId: number) => void

  • windowId

    ตัวเลข

    รหัสของหน้าต่างที่โฟกัสใหม่

• ตัวกรอง

  object ไม่บังคับ

  • windowTypes

    WindowType[]

    เงื่อนไขที่ประเภทของกรอบเวลาที่นำออกต้องเป็นไปตาม โดยค่าเริ่มต้นจะเป็นไปตาม ['normal', 'popup']

onRemoved

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

เริ่มทำงานเมื่อมีการนำหน้าต่างออก (ปิด)

พารามิเตอร์

• callback

  ฟังก์ชัน

  Chrome 46 ขึ้นไป browser.* ตั้งแต่ Chrome 148

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  (windowId: number) => void

  • windowId

    ตัวเลข

    รหัสของหน้าต่างที่นำออก

• ตัวกรอง

  object ไม่บังคับ

  • windowTypes

    WindowType[]

    เงื่อนไขที่ประเภทของกรอบเวลาที่นำออกต้องเป็นไปตาม โดยค่าเริ่มต้นจะเป็นไปตาม ['normal', 'popup']