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"
מצב חלון במסך מלא.

‫'locked-fullscreen'
מצב חלון במסך מלא נעול. המשתמשים לא יכולים לצאת ממצב המסך המלא הזה, והוא זמין רק לתוספים שנכללים ברשימת ההיתרים ב-ChromeOS.

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()

chrome.windows.create(
  createData?: object,
): 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 לא מלאות נחשבות יחסיות בתוך התוסף. ברירת המחדל היא דף הכרטיסייה החדשה.

    • רוחב

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

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

החזרות

  • ‫Promise<Window | undefined>

    ‫Chrome 88 ואילך

get()

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

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

פרמטרים

  • windowId

    number

  • queryOptions

    ‫QueryOptions אופציונלי

    ‫Chrome 88 ואילך

החזרות

  • Promise<Window>

    ‫Chrome 88 ואילך

getAll()

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

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

פרמטרים

  • queryOptions

    ‫QueryOptions אופציונלי

    ‫Chrome 88 ואילך

החזרות

  • Promise<Window[]>

    ‫Chrome 88 ואילך

getCurrent()

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

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

פרמטרים

  • queryOptions

    ‫QueryOptions אופציונלי

    ‫Chrome 88 ואילך

החזרות

  • Promise<Window>

    ‫Chrome 88 ואילך

getLastFocused()

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

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

פרמטרים

  • queryOptions

    ‫QueryOptions אופציונלי

    ‫Chrome 88 ואילך

החזרות

  • Promise<Window>

    ‫Chrome 88 ואילך

remove()

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

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

פרמטרים

  • windowId

    number

החזרות

  • Promise<void>

    ‫Chrome 88 ואילך

update()

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

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

פרמטרים

  • windowId

    number

  • updateInfo

    אובייקט

    • drawAttention

      ‫boolean אופציונלי

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

    • ממוקד

      ‫boolean אופציונלי

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

    • גובה

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

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

    • שמאלה

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

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

    • הסמוי הסופי

      ‫WindowState אופציונלי

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

    • עליון

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

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

    • רוחב

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

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

החזרות

  • Promise<Window>

    ‫Chrome 88 ואילך

אירועים

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