chrome.windows

คำอธิบาย

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

ไฟล์ Manifest

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

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

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

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

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

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

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

ตัวอย่าง

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

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

ประเภท

CreateType

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

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

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

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

QueryOptions

Chrome เวอร์ชัน 88 ขึ้นไป

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

  • ป้อนข้อมูล

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

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

  • windowTypes

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

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

Window

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

  • alwaysOnTop

    boolean

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

  • มีสมาธิ

    boolean

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

  • ส่วนสูง

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

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

  • id

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

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

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

    boolean

    ดูว่าหน้าต่างอยู่ในโหมดไม่ระบุตัวตนหรือไม่

  • ซ้าย

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

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

  • sessionId

    string ไม่บังคับ

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

  • รัฐ

    WindowState ไม่บังคับ

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

  • แท็บ

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

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

  • ด้านบน

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

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

  • ประเภท

    WindowType ไม่บังคับ

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

  • ความกว้าง

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

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

WindowState

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

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

"ย่อเล็กสุด"
สถานะหน้าต่างย่อเล็กสุด

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

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

"ล็อก-เต็มหน้าจอ"
สถานะหน้าต่างเต็มหน้าจอล็อกอยู่ การดำเนินการของผู้ใช้ออกจากสถานะเต็มหน้าจอนี้ไม่ได้ และจะใช้ได้กับส่วนขยายจากรายการที่อนุญาตใน Chrome OS เท่านั้น

WindowType

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

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

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

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

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

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

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

WINDOW_ID_CURRENT

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

ค่า

-2

WINDOW_ID_NONE

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

ค่า

-1

เมธอด

create()

สัญญา 
chrome.windows.create(
  createData?: object,
  callback?: function,
)

สร้าง (เปิด) หน้าต่างเบราว์เซอร์ใหม่ซึ่งระบุขนาด ตำแหน่ง หรือ 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 ที่ไม่ตรงตามข้อกำหนดจะถือว่ามีความเกี่ยวข้องภายในส่วนขยาย ค่าเริ่มต้นจะเป็นหน้าแท็บใหม่

    • ความกว้าง

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

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

  • Callback

    ไม่บังคับ

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

    (window?: Window) => void

    • หน้าต่าง

      กรอบเวลา ไม่บังคับ

      มีรายละเอียดเกี่ยวกับหน้าต่างที่สร้างขึ้น

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

  • Promise<Window | ไม่ระบุ>

    Chrome เวอร์ชัน 88 ขึ้นไป

    Promise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback

get()

สัญญา 
chrome.windows.get(
  windowId: number,
  queryOptions?: QueryOptions,
  callback?: function,
)

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

พารามิเตอร์

  • windowId

    ตัวเลข

  • queryOptions

    QueryOptions ไม่บังคับ

    Chrome เวอร์ชัน 88 ขึ้นไป
  • Callback

    ไม่บังคับ

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

    (window: Window) => void

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

  • Promise<Window>

    Chrome เวอร์ชัน 88 ขึ้นไป

    Promise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback

getAll()

สัญญา 
chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
)

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

พารามิเตอร์

  • queryOptions

    QueryOptions ไม่บังคับ

    Chrome เวอร์ชัน 88 ขึ้นไป
  • Callback

    ไม่บังคับ

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

    (windows: Window[]) => void

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

  • Promise<Window[]>

    Chrome เวอร์ชัน 88 ขึ้นไป

    Promise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback

getCurrent()

สัญญา 
chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
)

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

พารามิเตอร์

  • queryOptions

    QueryOptions ไม่บังคับ

    Chrome เวอร์ชัน 88 ขึ้นไป
  • Callback

    ไม่บังคับ

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

    (window: Window) => void

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

  • Promise<Window>

    Chrome เวอร์ชัน 88 ขึ้นไป

    Promise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback

getLastFocused()

สัญญา 
chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
)

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

พารามิเตอร์

  • queryOptions

    QueryOptions ไม่บังคับ

    Chrome เวอร์ชัน 88 ขึ้นไป
  • Callback

    ไม่บังคับ

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

    (window: Window) => void

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

  • Promise<Window>

    Chrome เวอร์ชัน 88 ขึ้นไป

    Promise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback

remove()

สัญญา 
chrome.windows.remove(
  windowId: number,
  callback?: function,
)

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

พารามิเตอร์

  • windowId

    ตัวเลข

  • Callback

    ไม่บังคับ

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

    () => void

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

  • คำมั่นสัญญา<โมฆะ>

    Chrome เวอร์ชัน 88 ขึ้นไป

    Promise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback

update()

สัญญา 
chrome.windows.update(
  windowId: number,
  updateInfo: object,
  callback?: function,
)

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

พารามิเตอร์

  • windowId

    ตัวเลข

  • updateInfo

    ออบเจ็กต์

    • drawAttention

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

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

    • มีสมาธิ

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

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

    • ส่วนสูง

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

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

    • ซ้าย

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

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

    • รัฐ

      WindowState ไม่บังคับ

      สถานะใหม่ของหน้าต่าง "ย่อเล็กสุด" "ขยายใหญ่สุด" และ "เต็มหน้าจอ" ไม่สามารถรวมสถานะกับ "left" "top" "width" หรือ "height"

    • ด้านบน

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

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

    • ความกว้าง

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

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

  • Callback

    ไม่บังคับ

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

    (window: Window) => void

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

  • Promise&lt;Window&gt;

    Chrome เวอร์ชัน 88 ขึ้นไป

    Promise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback

กิจกรรม

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