chrome.windows

תיאור

אפשר להשתמש ב-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.

Enum

‫'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.

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

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

    • ממוקד

      boolean אופציונלי

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

    • גובה

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

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

    • מצב פרטי

      boolean אופציונלי

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

    • שמאלה

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

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

    • setSelfAsOpener

      boolean אופציונלי

      ‫Chrome 64+‎

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

    • הסמוי הסופי

      ‫WindowState אופציונלי

      ‫Chrome 44 ואילך

      המצב ההתחלתי של החלון. אי אפשר לשלב את המצבים minimized, maximized ו-fullscreen עם המצבים left, top, width או height.

    • tabId

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

      המזהה של הכרטיסייה שרוצים להוסיף לחלון החדש.

    • עליון

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

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

    • סוג

      ‫CreateType אופציונלי

      מציין איזה סוג של חלון דפדפן ליצור.

    • כתובת אתר

      מחרוזת | מערך של מחרוזות אופציונלי

      כתובת URL או מערך של כתובות URL שייפתחו ככרטיסיות בחלון. כתובות URL מלאות חייבות לכלול סכימה, למשל http://www.google.com, ולא www.google.com. כתובות URL לא מלאות נחשבות יחסיות בתוך התוסף. ברירת המחדל היא דף הכרטיסייה החדשה.

    • רוחב

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

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

  • callback

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

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

    (window?: Window) => void

    • חלון

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

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

החזרות

  • ‫Promise<Window | undefined>

    ‫Chrome 88 ואילך

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

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 ואילך

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

getAll()

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

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

פרמטרים

  • queryOptions

    ‫QueryOptions אופציונלי

    ‫Chrome 88 ואילך
  • callback

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

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

    (windows: Window[]) => void

החזרות

  • Promise<Window[]>

    ‫Chrome 88 ואילך

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

getCurrent()

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

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

פרמטרים

  • queryOptions

    ‫QueryOptions אופציונלי

    ‫Chrome 88 ואילך
  • callback

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

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

    (window: Window) => void

החזרות

  • Promise<Window>

    ‫Chrome 88 ואילך

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

getLastFocused()

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

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

פרמטרים

  • queryOptions

    ‫QueryOptions אופציונלי

    ‫Chrome 88 ואילך
  • callback

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

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

    (window: Window) => void

החזרות

  • Promise<Window>

    ‫Chrome 88 ואילך

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

remove()

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

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

פרמטרים

  • windowId

    number

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 88 ואילך

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

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 ואילך

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

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