chrome.windows

תאריך הרענון: 2026-09-25 robots: noindex

תיאור

משתמשים ב-chrome.windows API כדי ליצור אינטראקציה עם חלונות דפדפן. אתם יכולים להשתמש ב-API הזה כדי ליצור חלונות בדפדפן, לשנות אותם ולסדר אותם מחדש.

מניפסט

כשמבקשים, windows.Window מכיל מערך של אובייקטים מסוג tabs.Tab. אם אתם צריכים גישה למאפיינים url,‏ pendingUrl, ‏ title או favIconUrl של tabs.Tab, אתם צריכים להצהיר על ההרשאה "tabs" במניפסט. לדוגמה:

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

החלון הנוכחי

הרבה פונקציות במערכת התוספים מקבלות ארגומנט אופציונלי windowId, שברירת המחדל שלו היא החלון הנוכחי.

החלון הנוכחי הוא החלון שמכיל את הקוד שמופעל כרגע. חשוב להבין שהחלון הזה יכול להיות שונה מהחלון העליון או מהחלון הממוקד.

לדוגמה, נניח שהתוסף יוצר כמה כרטיסיות או חלונות מקובץ HTML יחיד, וקובץ ה-HTML מכיל קריאה ל-tabs.query(). החלון הנוכחי הוא החלון שמכיל את הדף שיצר את הקריאה, לא משנה מה החלון העליון.

במקרה של service workers, הערך של החלון הנוכחי חוזר לחלון הפעיל האחרון. במקרים מסוימים, יכול להיות שלא יהיה חלון נוכחי לדפי רקע.

דוגמאות

שני חלונות, כל אחד עם כרטיסייה אחת

כדי לנסות את ה-API הזה, מתקינים את הדוגמה ל-API של Windows ממאגר chrome-extension-samples.

סוגים

CreateType

‫Chrome 44 ואילך

מציין איזה סוג של חלון דפדפן ליצור. הערך 'panel' הוצא משימוש והוא זמין רק לתוספים קיימים שנכללים ברשימת ההיתרים ב-ChromeOS.

ספירה

‫'normal'
מציין שהחלון הוא חלון רגיל.

‫'popup'
מגדיר את החלון כחלון קופץ.

‫panel
מציין שהחלון הוא חלונית.

QueryOptions

‫Chrome 88 ואילך

מאפיינים

  • לאכלס

    ‫boolean אופציונלי

    אם הערך הוא true, לאובייקט windows.Window יש מאפיין tabs שמכיל רשימה של אובייקטים מסוג tabs.Tab. האובייקטים Tab מכילים רק את המאפיינים url,‏ pendingUrl,‏ title ו-favIconUrl אם קובץ המניפסט של התוסף כולל את ההרשאה "tabs".

  • windowTypes

    ‫WindowType[] אופציונלי

    אם המאפיין מוגדר, הערך windows.Window שמוחזר מסונן לפי הסוג שלו. אם לא מגדירים את המסנן, ברירת המחדל היא ['normal', 'popup'].

Window

מאפיינים

  • alwaysOnTop

    בוליאני

    האם החלון מוגדר להופיע תמיד בחלק העליון.

  • ממוקד

    בוליאני

    האם החלון הוא החלון הממוקד כרגע.

  • גובה

    מספר אופציונלי

    גובה החלון, כולל המסגרת, בפיקסלים. במקרים מסוימים, יכול להיות שלא יוקצה לנכס חלון height. לדוגמה, כשמבצעים שאילתה על חלונות סגורים באמצעות API של sessions.

  • id [מזהה]

    מספר אופציונלי

    המזהה של החלון. מזהי החלונות הם ייחודיים בסשן דפדפן. במקרים מסוימים, יכול להיות שלא יוקצה חלון לנכס ID, למשל כשמבצעים שאילתה על חלונות באמצעות ה-API של sessions. במקרה כזה, יכול להיות שיהיה מזהה סשן.

  • פרטי

    בוליאני

    האם החלון הוא פרטי.

  • שמאלה

    מספר אופציונלי

    ההיסט של החלון מהקצה הימני של המסך בפיקסלים. במקרים מסוימים, יכול להיות שלא יוקצה לנכס חלון left. לדוגמה, כשמבצעים שאילתה על חלונות סגורים באמצעות API של sessions.

  • sessionId

    מחרוזת אופציונלי

    מזהה הסשן שמשמש לזיהוי ייחודי של חלון, ומתקבל מ-API‏ sessions.

  • הסמוי הסופי

    ‫WindowState אופציונלי

    המצב של חלון הדפדפן הזה.

  • כרטיסיות

    ‫Tab[] אופציונלי

    מערך של אובייקטים מסוג tabs.Tab שמייצגים את הכרטיסיות הנוכחיות בחלון.

  • עליון

    מספר אופציונלי

    ההיסט של החלון מהקצה העליון של המסך בפיקסלים. במקרים מסוימים, יכול להיות שלא יוקצה לנכס חלון top. לדוגמה, כשמבצעים שאילתה על חלונות סגורים באמצעות API של sessions.

  • סוג

    ‫WindowType אופציונלי

    סוג חלון הדפדפן.

  • רוחב

    מספר אופציונלי

    רוחב החלון, כולל המסגרת, בפיקסלים. במקרים מסוימים, יכול להיות שלא יוקצה חלון עם מאפיין width. לדוגמה, כשמבצעים שאילתה על חלונות סגורים באמצעות API‏ sessions.

WindowState

‫Chrome 44 ואילך

המצב של חלון הדפדפן הזה. במקרים מסוימים, יכול להיות שלא יוקצה לנכס חלון state. לדוגמה, כשמבצעים שאילתה על חלונות סגורים באמצעות API של sessions.

ספירה

‫'normal'
מצב חלון רגיל (לא ממוזער, לא מוגדל ולא במסך מלא).

‫'minimized'
מצב חלון ממוזער.

‫"maximized"
מצב חלון מוגדל.

‫"fullscreen"
מצב חלון במסך מלא.

WindowType

‫Chrome 44 ואילך

סוג חלון הדפדפן. בנסיבות מסוימות, יכול להיות שלא יוקצה לחלון מאפיין type. לדוגמה, כשמבצעים שאילתה לגבי חלונות סגורים באמצעות API‏ sessions.

ספירה

‫'normal'
חלון דפדפן רגיל.

"חלון קופץ"
חלון קופץ בדפדפן.

‫panel
יצא משימוש ב-API הזה. חלון בסגנון חלונית של אפליקציית Chrome. תוספים יכולים לראות רק את חלונות החלונית שלהם.

‫app
יצא משימוש ב-API הזה. חלון של אפליקציית Chrome. תוספים יכולים לראות רק את החלונות של האפליקציה שלהם.

‫devtools
חלון של כלים למפתחים.

מאפיינים

WINDOW_ID_CURRENT

הערך windowId שמייצג את החלון הנוכחי.

ערך

‫-2

WINDOW_ID_NONE

הערך של windowId שמייצג את העובדה שאין חלון של דפדפן Chrome.

ערך

‫-1

Methods

create()

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

יוצר (פותח) חלון חדש בדפדפן עם גודל, מיקום או כתובת URL שסופקו כברירת מחדל.

פרמטרים

  • createData

    אובייקט אופציונלי

    • ממוקד

      ‫boolean אופציונלי

      אם true, נפתח חלון פעיל. אם false, נפתח חלון לא פעיל.

    • גובה

      מספר אופציונלי

      הגובה בפיקסלים של החלון החדש, כולל המסגרת. אם לא מציינים ערך, ברירת המחדל היא גובה טבעי.

    • פרטי

      ‫boolean אופציונלי

      האם החלון החדש צריך להיות חלון פרטי.

    • שמאלה

      מספר אופציונלי

      מספר הפיקסלים למיקום החלון החדש מהקצה השמאלי של המסך. אם לא מציינים את המיקום, החלון החדש מוזז באופן טבעי מהחלון האחרון שהיה בפוקוס. המערכת מתעלמת מהערך הזה בחלוניות.

    • setSelfAsOpener

      ‫boolean אופציונלי

      ‫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 | undefined>

    ‫Chrome 88 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

get()

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

קבלת פרטים על חלון.

פרמטרים

  • windowId

    number

  • queryOptions

    ‫QueryOptions אופציונלי

    ‫Chrome 88 ואילך
  • callback

    פונקציה אופציונלית

    הפרמטר callback נראה כך: 

    (window: Window) => void

החזרות

  • Promise<Window>

    ‫Chrome 88 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getAll()

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

מקבל את כל החלונות.

פרמטרים

  • queryOptions

    ‫QueryOptions אופציונלי

    ‫Chrome 88 ואילך
  • callback

    פונקציה אופציונלית

    הפרמטר callback נראה כך: 

    (windows: Window[]) => void

החזרות

  • Promise<Window[]>

    ‫Chrome 88 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getCurrent()

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

הפונקציה מחזירה את החלון הנוכחי.

פרמטרים

  • queryOptions

    ‫QueryOptions אופציונלי

    ‫Chrome 88 ואילך
  • callback

    פונקציה אופציונלית

    הפרמטר callback נראה כך: 

    (window: Window) => void

החזרות

  • Promise<Window>

    ‫Chrome 88 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getLastFocused()

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

מחזירה את החלון שהיה בפוקוס לאחרונה – בדרך כלל החלון 'העליון'.

פרמטרים

  • queryOptions

    ‫QueryOptions אופציונלי

    ‫Chrome 88 ואילך
  • callback

    פונקציה אופציונלית

    הפרמטר callback נראה כך: 

    (window: Window) => void

החזרות

  • Promise<Window>

    ‫Chrome 88 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

remove()

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

מסיר (סוגר) חלון ואת כל הכרטיסיות שבתוכו.

פרמטרים

  • windowId

    number

  • callback

    פונקציה אופציונלית

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    ‫Chrome 88 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

update()

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

מעדכן את המאפיינים של חלון. מציינים רק את המאפיינים שרוצים לשנות. המאפיינים שלא צוינו לא משתנים.

פרמטרים

  • windowId

    number

  • updateInfo

    אובייקט

    • drawAttention

      ‫boolean אופציונלי

      אם true, החלון יוצג באופן שימשוך את תשומת הלב של המשתמש לחלון, בלי לשנות את החלון הממוקד. ההשפעה נמשכת עד שהמשתמש מעביר את המיקוד לחלון. לאפשרות הזו אין השפעה אם החלון כבר מודגש. מגדירים את הערך false כדי לבטל בקשת drawAttention קודמת.

    • ממוקד

      ‫boolean אופציונלי

      אם true, החלון מועבר לחזית. אי אפשר לשלב את האפשרות הזו עם המצב 'מוזער'. ‫false, מעביר את החלון הבא בסדר z לחזית. אי אפשר לשלב את הפעולה הזו עם המצב 'מסך מלא' או 'מוגדל'.

    • גובה

      מספר אופציונלי

      הגובה שאליו יש לשנות את גודל החלון בפיקסלים. המערכת מתעלמת מהערך הזה בחלוניות.

    • שמאלה

      מספר אופציונלי

      ההיסט מהקצה השמאלי של המסך שאליו החלון יועבר, בפיקסלים. המערכת מתעלמת מהערך הזה בחלוניות.

    • הסמוי הסופי

      ‫WindowState אופציונלי

      הסטטוס החדש של החלון. אי אפשר לשלב את המצבים 'מוזער', 'מורחב' ו 'מסך מלא' עם 'ימינה', 'למעלה', 'רוחב' או 'גובה'.

    • עליון

      מספר אופציונלי

      ההיסט מהקצה העליון של המסך שאליו רוצים להעביר את החלון, בפיקסלים. המערכת מתעלמת מהערך הזה בחלוניות.

    • רוחב

      מספר אופציונלי

      הרוחב שאליו יש לשנות את גודל החלון בפיקסלים. המערכת מתעלמת מהערך הזה בחלוניות.

  • callback

    פונקציה אופציונלית

    הפרמטר callback נראה כך: 

    (window: Window) => void

החזרות

  • Promise<Window>

    ‫Chrome 88 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

אירועים

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

      number

      המזהה של החלון החדש שהמיקוד עבר אליו.

  • מסננים

    אובייקט אופציונלי

    • windowTypes

      ‫WindowType[]

      תנאים שסוג החלון שמוסר צריך לעמוד בהם. כברירת מחדל, הוא עומד בדרישות של ['normal', 'popup'].

onRemoved

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

האירוע מופעל כשחלון מוסר (נסגר).

פרמטרים

  • callback

    פונקציה

    ‫Chrome 46 ואילך

    הפרמטר callback נראה כך: 

    (windowId: number) => void

    • windowId

      number

      המזהה של החלון שהוסר.

  • מסננים

    אובייקט אופציונלי

    • windowTypes

      ‫WindowType[]

      תנאים שסוג החלון שמוסר צריך לעמוד בהם. כברירת מחדל, הוא עומד בדרישות של ['normal', 'popup'].