chrome.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 นี้ ให้ติดตั้งตัวอย่าง API ของ Windows จากที่เก็บchrome-extension-samples

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

ประเภท

CreateType

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

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

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

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

QueryOptions

Chrome 88 ขึ้นไป

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

  • ป้อนข้อมูล

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

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

  • windowTypes

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

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

Window

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

  • alwaysOnTop

    บูลีน

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

  • มีสมาธิ

    บูลีน

    หน้าต่างเป็นหน้าต่างที่โฟกัสในปัจจุบันหรือไม่

  • ส่วนสูง

    หมายเลข ไม่บังคับ

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

  • id

    หมายเลข ไม่บังคับ

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

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

    บูลีน

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

  • ซ้าย

    หมายเลข ไม่บังคับ

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

  • sessionId

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

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

  • รัฐ

    WindowState ไม่บังคับ

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

  • tabs

    แท็บ[] ไม่บังคับ

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

  • ด้านบน

    หมายเลข ไม่บังคับ

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

  • ประเภท

    WindowType ไม่บังคับ

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

  • ความกว้าง

    หมายเลข ไม่บังคับ

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

WindowState

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

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

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

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

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

WindowType

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

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

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

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

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

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

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

WINDOW_ID_CURRENT

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

ค่า

-2

WINDOW_ID_NONE

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

ค่า

-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

      หมายเลข ไม่บังคับ

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

    • ด้านบน

      หมายเลข ไม่บังคับ

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

    • ประเภท

      CreateType ไม่บังคับ

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

    • URL

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

      URL หรืออาร์เรย์ของ URL ที่จะเปิดเป็นแท็บในหน้าต่าง URL ที่สมบูรณ์ในตัวเองต้องมีรูปแบบ เช่น "http://www.google.com" ไม่ใช่ "www.google.com" ระบบจะถือว่า URL ที่ไม่มีคุณสมบัติครบถ้วนเป็น 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 ทำให้หน้าต่างแสดงในลักษณะที่ดึงดูดความสนใจของผู้ใช้ไปยังหน้าต่างนั้นโดยไม่เปลี่ยนหน้าต่างที่โฟกัส เอฟเฟกต์จะคงอยู่จนกว่าผู้ใช้จะเปลี่ยนโฟกัสไปที่หน้าต่าง ตัวเลือกนี้จะไม่มีผลหากหน้าต่างมีโฟกัสอยู่แล้ว ตั้งค่าเป็น false เพื่อยกเลิกคำขอ drawAttention ก่อนหน้า

    • มีสมาธิ

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

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

    • ส่วนสูง

      หมายเลข ไม่บังคับ

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

    • ซ้าย

      หมายเลข ไม่บังคับ

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

    • รัฐ

      WindowState ไม่บังคับ

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

    • ด้านบน

      หมายเลข ไม่บังคับ

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

    • ความกว้าง

      หมายเลข ไม่บังคับ

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

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

  • Promise<Window>

    Chrome 88 ขึ้นไป

กิจกรรม

onBoundsChanged

Chrome 86 ขึ้นไป 
chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (window: Window) => void

onCreated

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

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

    Chrome 46 ขึ้นไป

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

    (window: Window) => void

    • หน้าต่าง

      หน้าต่าง

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

  • ตัวกรอง

    ออบเจ็กต์ ไม่บังคับ

    • windowTypes

      WindowType[]

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

onFocusChanged

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

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

    Chrome 46 ขึ้นไป

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

    (windowId: number) => void

    • windowId

      ตัวเลข

      รหัสของหน้าต่างที่เพิ่งโฟกัส

  • ตัวกรอง

    ออบเจ็กต์ ไม่บังคับ

    • windowTypes

      WindowType[]

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

onRemoved

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

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

    Chrome 46 ขึ้นไป

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

    (windowId: number) => void

    • windowId

      ตัวเลข

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

  • ตัวกรอง

    ออบเจ็กต์ ไม่บังคับ

    • windowTypes

      WindowType[]

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