chrome.windows

refresh date: 2026-09-25 robots: noindex

תיאור

משתמשים ב-API של chrome.windows כדי לבצע פעולות בחלונות של הדפדפן. אתם יכולים להשתמש ב-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.

טיפוסים בני מנייה (enum)

"normal"
מגדיר את החלון כחלון רגיל.

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

"panel"
מגדיר את החלון כחלונית.

QueryOptions

‫Chrome מגרסה 88 ואילך

מאפיינים

• לאכלס

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

  אם הערך הוא 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.

• מדינה (State)

  WindowState אופציונלי

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

• כרטיסיות

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

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

• עליון

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

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

• סוג

  ‫WindowType אופציונלי

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

• רוחב

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

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

WindowState

‫Chrome מגרסה 44 ואילך

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

טיפוסים בני מנייה (enum)

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

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

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

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

WindowType

‫Chrome מגרסה 44 ואילך

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

טיפוסים בני מנייה (enum)

"normal"
חלון דפדפן רגיל.

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

"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

  object optional

  • ממוקד

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

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

  • גובה

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

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

  • גלישה בסתר

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

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

  • שמאלה

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

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

  • setSelfAsOpener

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

    ‫Chrome מגרסה 64 ואילך

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

  • מדינה (State)

    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

  function optional

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

  (window?: Window) => void

  • חלון

    חלון אופציונלי

    מכיל פרטים על החלון שנוצר.

החזרות

• Promise<Window | undefined>

  ‫Chrome מגרסה 88 ואילך

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

get()

Promise

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

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

פרמטרים

• windowId

  number

• queryOptions

  QueryOptions אופציונלי

  ‫Chrome מגרסה 88 ואילך
• callback

  function optional

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

  (window: Window) => void

  • חלון

    חלון

החזרות

• Promise<Window>

  ‫Chrome מגרסה 88 ואילך

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

getAll()

Promise

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

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

פרמטרים

• queryOptions

  QueryOptions אופציונלי

  ‫Chrome מגרסה 88 ואילך
• callback

  function optional

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

  (windows: Window[]) => void

  • חלונות

    חלון[]

החזרות

• Promise<Window[]>

  ‫Chrome מגרסה 88 ואילך

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

getCurrent()

Promise

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

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

פרמטרים

• queryOptions

  QueryOptions אופציונלי

  ‫Chrome מגרסה 88 ואילך
• callback

  function optional

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

  (window: Window) => void

  • חלון

    חלון

החזרות

• Promise<Window>

  ‫Chrome מגרסה 88 ואילך

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

getLastFocused()

Promise

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

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

פרמטרים

• queryOptions

  QueryOptions אופציונלי

  ‫Chrome מגרסה 88 ואילך
• callback

  function optional

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

  (window: Window) => void

  • חלון

    חלון

החזרות

• Promise<Window>

  ‫Chrome מגרסה 88 ואילך

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

remove()

Promise

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

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

פרמטרים

• windowId

  number

• callback

  function optional

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

  () => void

החזרות

• Promise<void>

  ‫Chrome מגרסה 88 ואילך

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

update()

Promise

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

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

פרמטרים

• windowId

  number

• updateInfo

  אובייקט

  • drawAttention

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

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

  • ממוקד

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

    אם הערך הוא true, החלון מועבר לחזית. אי אפשר לשלב את הערך הזה עם המצב "ממוזער". אם הערך הוא false, החלון הבא בסדר ה-Z מועבר לחזית. אי אפשר לשלב את הערך הזה עם המצבים fullscreen או maximized.

  • גובה

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

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

  • שמאלה

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

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

  • מדינה (State)

    WindowState אופציונלי

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

  • עליון

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

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

  • רוחב

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

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

• callback

  function optional

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

  (window: Window) => void

  • חלון

    חלון

החזרות

• Promise<Window>

  ‫Chrome מגרסה 88 ואילך

  הבטחות נתמכות רק ב-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

  • חלון

    חלון

    פרטי החלון שנוצר.

• מסננים

  object optional

  • 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

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

• מסננים

  object optional

  • windowTypes

    WindowType[]

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

onRemoved

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

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

פרמטרים

• callback

  פונקציה

  ‫Chrome מגרסה 46 ואילך

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

  (windowId: number) => void

  • windowId

    number

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

• מסננים

  object optional

  • windowTypes

    WindowType[]

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