chrome.windows

refresh date: 2026-09-25 robots: noindex

คำอธิบาย

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

ไฟล์ Manifest

เมื่อมีการขอ 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 ค่าของหน้าต่างปัจจุบันจะกลับไปเป็นหน้าต่างที่ใช้งานล่าสุด ในบางกรณี อาจไม่มีหน้าต่างปัจจุบันสำหรับหน้าพื้นหลัง

ตัวอย่าง

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

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

ประเภท

CreateType

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

"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

    บูลีน

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

  • มีสมาธิ

    บูลีน

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

  • ความสูง

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

    ความสูงของหน้าต่างรวมถึงกรอบเป็นพิกเซล ในบางกรณี ระบบอาจไม่กำหนดพร็อพเพอร์ตี้ 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

ค่าแจกแจง

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

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

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

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

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

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

WINDOW_ID_CURRENT

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

ค่า

-2

WINDOW_ID_NONE

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

ค่า

-1

เมธอด

create()

Promise 
chrome.windows.create(
  createData?: object,
  callback?: function,
): 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 ที่เกี่ยวข้องภายในส่วนขยาย ค่าเริ่มต้นคือหน้าแท็บใหม่

    • ความกว้าง

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

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

  • callback

    ฟังก์ชัน ไม่บังคับ

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

    (window?: Window) => void

    • หน้าต่าง

      หน้าต่าง ไม่บังคับ

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

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

  • Promise<Window | undefined>

    Chrome 88 ขึ้นไป

    ระบบรองรับเฉพาะ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้การเรียกกลับ

get()

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

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

พารามิเตอร์

  • windowId

    ตัวเลข

  • queryOptions

    QueryOptions ไม่บังคับ

    Chrome 88 ขึ้นไป
  • callback

    ฟังก์ชัน ไม่บังคับ

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

    (window: Window) => void

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

  • Promise<Window>

    Chrome 88 ขึ้นไป

    ระบบรองรับเฉพาะ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้การเรียกกลับ

getAll()

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

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

พารามิเตอร์

  • queryOptions

    QueryOptions ไม่บังคับ

    Chrome 88 ขึ้นไป
  • callback

    ฟังก์ชัน ไม่บังคับ

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

    (windows: Window[]) => void

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

  • Promise<Window[]>

    Chrome 88 ขึ้นไป

    ระบบรองรับเฉพาะ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้การเรียกกลับ

getCurrent()

Promise 
chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

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

พารามิเตอร์

  • queryOptions

    QueryOptions ไม่บังคับ

    Chrome 88 ขึ้นไป
  • callback

    ฟังก์ชัน ไม่บังคับ

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

    (window: Window) => void

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

  • Promise<Window>

    Chrome 88 ขึ้นไป

    ระบบรองรับเฉพาะ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้การเรียกกลับ

getLastFocused()

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

รับหน้าต่างที่โฟกัสล่าสุด ซึ่งโดยปกติคือหน้าต่าง "ด้านบน"

พารามิเตอร์

  • queryOptions

    QueryOptions ไม่บังคับ

    Chrome 88 ขึ้นไป
  • callback

    ฟังก์ชัน ไม่บังคับ

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

    (window: Window) => void

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

  • Promise<Window>

    Chrome 88 ขึ้นไป

    ระบบรองรับเฉพาะ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้การเรียกกลับ

remove()

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

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

พารามิเตอร์

  • windowId

    ตัวเลข

  • callback

    ฟังก์ชัน ไม่บังคับ

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

    () => void

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

  • Promise<void>

    Chrome 88 ขึ้นไป

    ระบบรองรับเฉพาะ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้การเรียกกลับ

update()

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

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

พารามิเตอร์

  • windowId

    ตัวเลข

  • updateInfo

    ออบเจ็กต์

    • drawAttention

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

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

    • มีสมาธิ

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

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

    • ความสูง

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

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

    • ซ้าย

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

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

    • รัฐ

      WindowState ไม่บังคับ

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

    • ด้านบน

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

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

    • ความกว้าง

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

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

  • callback

    ฟังก์ชัน ไม่บังคับ

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

    (window: Window) => void

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

  • Promise<Window>

    Chrome 88 ขึ้นไป

    ระบบรองรับเฉพาะ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้การเรียกกลับ

กิจกรรม

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