chrome.windows (original) (raw)

คำอธิบาย

ใช้ 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 แท็บ

ประเภท

CreateType

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

ค่าแจกแจง

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

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

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

QueryOptions

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

• ป้อนข้อมูล
  บูลีน ไม่บังคับ
  หากเป็นจริง ออบเจ็กต์ windows.Window จะมีพร็อพเพอร์ตี้ tabs ที่มีรายการออบเจ็กต์ tabs.Tab ออบเจ็กต์ Tab จะมีพร็อพเพอร์ตี้ url, pendingUrl, title และ favIconUrl ก็ต่อเมื่อไฟล์ Manifest ของส่วนขยายมีสิทธิ์ "tabs"
• windowTypes
  WindowType[] ไม่บังคับ
  หากตั้งค่าไว้ ระบบจะกรอง windows.Window ที่แสดงตามประเภท หากไม่ได้ตั้งค่าไว้ ระบบจะตั้งค่าตัวกรองเริ่มต้นเป็น ['normal', 'popup']

Window

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

• ไม่ว่าจะตั้งค่าหน้าต่างให้แสดงที่ด้านบนเสมอหรือไม่
• หน้าต่างเป็นหน้าต่างที่โฟกัสในปัจจุบันหรือไม่
• ส่วนสูง
  หมายเลข ไม่บังคับ
  ความสูงของหน้าต่างรวมถึงกรอบเป็นพิกเซล ในบางกรณี ระบบอาจไม่กำหนดพร็อพเพอร์ตี้ height ให้กับหน้าต่าง เช่น เมื่อค้นหาหน้าต่างที่ปิดจาก API sessions
• รหัสของหน้าต่าง รหัสหน้าต่างจะไม่ซ้ำกันภายในเซสชันของเบราว์เซอร์ ในบางกรณี ระบบอาจไม่กําหนดพร็อพเพอร์ตี้ ID ให้กับช่วงเวลา เช่น เมื่อทําการค้นหาช่วงเวลาโดยใช้ API sessions ในกรณีนี้อาจมีรหัสเซสชัน
• หน้าต่างเป็นโหมดไม่ระบุตัวตนหรือไม่
• ออฟเซ็ตของหน้าต่างจากขอบด้านซ้ายของหน้าจอเป็นพิกเซล ในบางกรณี ระบบอาจไม่กำหนดพร็อพเพอร์ตี้ left ให้กับหน้าต่าง เช่น เมื่อค้นหาหน้าต่างที่ปิดจาก API sessions
• sessionId
  สตริง ไม่บังคับ
  รหัสเซสชันที่ใช้ในการระบุหน้าต่างโดยไม่ซ้ำกัน ซึ่งได้จาก API sessions
• รัฐ
  WindowState ไม่บังคับ
  สถานะของหน้าต่างเบราว์เซอร์นี้
• อาร์เรย์ของออบเจ็กต์ tabs.Tab ที่แสดงแท็บปัจจุบันในหน้าต่าง
• ออฟเซ็ตของหน้าต่างจากขอบด้านบนของหน้าจอเป็นพิกเซล ในบางกรณี ระบบอาจไม่กำหนดพร็อพเพอร์ตี้ top ให้กับหน้าต่าง เช่น เมื่อค้นหาหน้าต่างที่ปิดจาก API sessions
• ประเภท
  WindowType ไม่บังคับ
  ประเภทของหน้าต่างเบราว์เซอร์นี้
• ความกว้าง
  หมายเลข ไม่บังคับ
  ความกว้างของหน้าต่างรวมถึงกรอบเป็นพิกเซล ในบางกรณี ระบบอาจไม่กำหนดพร็อพเพอร์ตี้ width ให้กับหน้าต่าง เช่น เมื่อค้นหาหน้าต่างที่ปิดจาก API sessions

WindowState

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

ค่าแจกแจง

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

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

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

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

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

WindowType

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

ค่าแจกแจง

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

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

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

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

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

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

WINDOW_ID_NONE

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

เมธอด

create()

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

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

พารามิเตอร์

• createData
  object ไม่บังคับ
  • หาก true จะเปิดหน้าต่างที่ใช้งานอยู่ หาก false จะเปิดหน้าต่างที่ไม่ได้ใช้งาน
  • ส่วนสูง
    หมายเลข ไม่บังคับ
    ความสูงเป็นพิกเซลของหน้าต่างใหม่ รวมถึงเฟรม หากไม่ได้ระบุไว้ ระบบจะใช้ความสูงตามธรรมชาติเป็นค่าเริ่มต้น
  • ไม่ระบุตัวตน
    บูลีน ไม่บังคับ
    ระบุว่าหน้าต่างใหม่ควรเป็นหน้าต่างที่ไม่ระบุตัวตนหรือไม่
  • จำนวนพิกเซลที่ใช้กำหนดตำแหน่งหน้าต่างใหม่จากขอบด้านซ้ายของหน้าจอ หากไม่ได้ระบุ ระบบจะชดเชยหน้าต่างใหม่จากหน้าต่างที่โฟกัสล่าสุดโดยอัตโนมัติ ระบบจะไม่สนใจค่านี้สำหรับแผง
  • setSelfAsOpener
    บูลีน ไม่บังคับ
    หาก true ระบบจะตั้งค่า "window.opener" ของหน้าต่างที่สร้างขึ้นใหม่เป็นผู้เรียกและอยู่ในหน่วยของบริบทการเรียกดูที่เกี่ยวข้องเดียวกันกับผู้เรียก
  • รัฐ
    WindowState ไม่บังคับ
    สถานะเริ่มต้นของหน้าต่าง สถานะ minimized, maximized และ fullscreen จะใช้ร่วมกับ left, top, width หรือ height ไม่ได้
  • รหัสของแท็บที่จะเพิ่มลงในหน้าต่างใหม่
  • จำนวนพิกเซลในการวางตำแหน่งหน้าต่างใหม่จากขอบด้านบนของหน้าจอ หากไม่ได้ระบุ ระบบจะชดเชยหน้าต่างใหม่จากหน้าต่างที่โฟกัสล่าสุดโดยอัตโนมัติ ระบบจะไม่สนใจค่านี้สำหรับแผง
  • ประเภท
    CreateType ไม่บังคับ
    ระบุประเภทหน้าต่างเบราว์เซอร์ที่จะสร้าง
  • URL
    string | string[] ไม่บังคับ
    URL หรืออาร์เรย์ของ URL ที่จะเปิดเป็นแท็บในหน้าต่าง URL แบบเต็มต้องมี Scheme เช่น "http://www.google.com" ไม่ใช่ "www.google.com" URL ที่ไม่มีคุณสมบัติครบถ้วนจะถือว่าเป็น URL สัมพัทธ์ภายในส่วนขยาย ค่าเริ่มต้นจะเป็นหน้าแท็บใหม่
  • ความกว้าง
    หมายเลข ไม่บังคับ
    ความกว้างเป็นพิกเซลของหน้าต่างใหม่ รวมถึงเฟรม หากไม่ได้ระบุไว้ ระบบจะใช้ความกว้างตามธรรมชาติเป็นค่าเริ่มต้น

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

• Promise<Window | undefined>

get()

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

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

พารามิเตอร์

• queryOptions
  QueryOptions ไม่บังคับ

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

getAll()

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

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

พารามิเตอร์

• queryOptions
  QueryOptions ไม่บังคับ

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

พารามิเตอร์

• queryOptions
  QueryOptions ไม่บังคับ

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

getLastFocused()

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

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

พารามิเตอร์

• queryOptions
  QueryOptions ไม่บังคับ

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

remove()

chrome.windows.remove(
  windowId: number,
): Promise

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

พารามิเตอร์

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

update()

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

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

พารามิเตอร์

• • drawAttention
    บูลีน ไม่บังคับ
    หาก true จะทำให้หน้าต่างแสดงในลักษณะที่ดึงดูดความสนใจของผู้ใช้ไปยังหน้าต่างนั้นโดยไม่เปลี่ยนหน้าต่างที่โฟกัส โดยเอฟเฟกต์จะคงอยู่จนกว่าผู้ใช้จะเปลี่ยนโฟกัสไปที่หน้าต่าง ตัวเลือกนี้จะไม่มีผลหากหน้าต่างมีโฟกัสอยู่แล้ว ตั้งค่าเป็น false เพื่อยกเลิกคำขอ drawAttention ก่อนหน้า
  • หาก true จะนำหน้าต่างมาไว้ด้านหน้า ใช้ร่วมกับสถานะ "ย่อ" ไม่ได้ หาก false จะนำหน้าต่างถัดไปในลำดับ Z มาไว้ด้านหน้า ใช้ร่วมกับสถานะ "เต็มหน้าจอ" หรือ "ขยายใหญ่สุด" ไม่ได้
  • ส่วนสูง
    หมายเลข ไม่บังคับ
    ความสูงที่จะใช้ปรับขนาดหน้าต่างเป็นพิกเซล ระบบจะไม่สนใจค่านี้สำหรับแผง
  • ออฟเซ็ตจากขอบด้านซ้ายของหน้าจอเพื่อย้ายหน้าต่างเป็นพิกเซล ระบบจะไม่สนใจค่านี้สำหรับแผง
  • รัฐ
    WindowState ไม่บังคับ
    สถานะใหม่ของหน้าต่าง สถานะ "ย่อ" "ขยาย" และ "เต็มหน้าจอ" จะใช้ร่วมกับ "left" "top" "width" หรือ "height" ไม่ได้
  • ออฟเซ็ตจากขอบด้านบนของหน้าจอเพื่อย้ายหน้าต่างไปยังพิกเซล ระบบจะไม่สนใจค่านี้สำหรับแผง
  • ความกว้าง
    หมายเลข ไม่บังคับ
    ความกว้างที่จะใช้ปรับขนาดหน้าต่างในหน่วยพิกเซล ระบบจะไม่สนใจค่านี้สำหรับแผง

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

กิจกรรม

onBoundsChanged

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

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

พารามิเตอร์

• พารามิเตอร์ callback มีลักษณะดังนี้
  (window: Window) => void

onCreated

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

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

พารามิเตอร์

• พารามิเตอร์ callback มีลักษณะดังนี้
  (window: Window) => void
  • รายละเอียดของหน้าต่างที่สร้างขึ้น
• • เงื่อนไขที่ประเภทของหน้าต่างที่สร้างขึ้นต้องเป็นไปตาม โดยค่าเริ่มต้น จะเป็นไปตาม ['normal', 'popup']

onFocusChanged

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

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

พารามิเตอร์

• พารามิเตอร์ callback มีลักษณะดังนี้
  (windowId: number) => void
  • รหัสของหน้าต่างที่เพิ่งโฟกัส
• • เงื่อนไขที่ต้องเป็นไปตามเมื่อนำประเภทหน้าต่างออก โดยค่าเริ่มต้น จะเป็นไปตาม ['normal', 'popup']

onRemoved

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

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

พารามิเตอร์

• พารามิเตอร์ callback มีลักษณะดังนี้
  (windowId: number) => void
  • รหัสของหน้าต่างที่นำออก
• • เงื่อนไขที่ต้องเป็นไปตามเมื่อนำประเภทหน้าต่างออก โดยค่าเริ่มต้น จะเป็นไปตาม ['normal', 'popup']