chrome.windows

תיאור

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

הרשאות

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

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

מושגים ושימוש

החלון הנוכחי

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

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

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

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

דוגמאות

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

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

סוגים

CreateType

Chrome 44 ואילך

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

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

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

"חלון קופץ"
מציין את החלון כחלון קופץ.

"panel"
מציין את החלון כלוח.

QueryOptions

Chrome 88 ומעלה

תכונות

  • לאכלס

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

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

  • windowTypes

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

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

Window

תכונות

  • alwaysOnTop

    boolean

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

  • ממוקד

    boolean

    אם החלון הוא החלון שנמצא כרגע במוקד.

  • גובה

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

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

  • id

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

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

  • גלישה פרטית

    boolean

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

  • שמאלה

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

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

  • sessionId

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

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

  • state

    WindowState אופציונלי

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

  • כרטיסיות

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

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

  • ראשונה

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

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

  • סוג

    WindowType אופציונלי

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

  • רוחב

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

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

WindowState

Chrome 44 ואילך

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

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

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

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

"מקסימלי"
מצב חלון מוגדל.

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

"locked-fullscreen"
מצב החלון במסך מלא נעול. לא ניתן לצאת ממצב מסך מלא זה על ידי פעולת משתמש, והוא זמין רק לתוספים ברשימת ההיתרים ב-Chrome OS.

WindowType

Chrome 44 ואילך

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

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

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

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

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

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

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

תכונות

WINDOW_ID_CURRENT

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

Value

-2

WINDOW_ID_NONE

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

Value

1-

שיטות

create()

הבטחה 
chrome.windows.create(
  createData?: object,
  callback?: function,
)

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

פרמטרים

  • createData

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

    • ממוקד

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

      אם הערך הוא true, ייפתח חלון פעיל. אם false, פותח חלון לא פעיל.

    • גובה

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

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

    • גלישה פרטית

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

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

    • שמאלה

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

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

    • setSelfAsOpener

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

      Chrome 64 ומעלה

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

    • state

      WindowState אופציונלי

      Chrome 44 ואילך

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

    • tabId

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

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

    • ראשונה

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

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

    • סוג

      CreateType אופציונלי

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

    • כתובת אתר

      string|string[] optional

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

    • רוחב

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

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

  • קריאה חוזרת (callback)

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

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

    (window?: Window)=>void

    • חלון

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

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

החזרות

  • הבטחה<חלון|לא מוגדר>

    Chrome 88 ומעלה

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

get()

הבטחה 
chrome.windows.get(
  windowId: number,
  queryOptions?: QueryOptions,
  callback?: function,
)

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

פרמטרים

  • windowId

    מספר

  • queryOptions

    QueryOptions אופציונלי

    Chrome 88 ומעלה
  • קריאה חוזרת (callback)

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

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

    (window: Window)=>void

החזרות

  • הבטחה<Window>

    Chrome 88 ומעלה

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

getAll()

הבטחה 
chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
)

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

פרמטרים

  • queryOptions

    QueryOptions אופציונלי

    Chrome 88 ומעלה
  • קריאה חוזרת (callback)

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

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

    (windows: Window[])=>void

החזרות

  • הבטחה<חלון[]>

    Chrome 88 ומעלה

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

getCurrent()

הבטחה 
chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
)

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

פרמטרים

  • queryOptions

    QueryOptions אופציונלי

    Chrome 88 ומעלה
  • קריאה חוזרת (callback)

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

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

    (window: Window)=>void

החזרות

  • הבטחה<Window>

    Chrome 88 ומעלה

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

getLastFocused()

הבטחה 
chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
)

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

פרמטרים

  • queryOptions

    QueryOptions אופציונלי

    Chrome 88 ומעלה
  • קריאה חוזרת (callback)

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

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

    (window: Window)=>void

החזרות

  • הבטחה<Window>

    Chrome 88 ומעלה

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

remove()

הבטחה 
chrome.windows.remove(
  windowId: number,
  callback?: function,
)

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

פרמטרים

  • windowId

    מספר

  • קריאה חוזרת (callback)

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

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 88 ומעלה

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

update()

הבטחה 
chrome.windows.update(
  windowId: number,
  updateInfo: object,
  callback?: function,
)

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

פרמטרים

  • windowId

    מספר

  • updateInfo

    אובייקט

    • drawAttention

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

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

    • ממוקד

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

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

    • גובה

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

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

    • שמאלה

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

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

    • state

      WindowState אופציונלי

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

    • ראשונה

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

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

    • רוחב

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

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

  • קריאה חוזרת (callback)

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

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

    (window: Window)=>void

החזרות

  • הבטחה<Window>

    Chrome 88 ומעלה

    יש תמיכה בהבטחות במניפסט מגרסה 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

      מספר

      המזהה של החלון הנוכחי.

  • מסננים

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

    • windowTypes

      WindowType[]

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

onRemoved

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

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

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    Chrome 46 ואילך

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

    (windowId: number)=>void

    • windowId

      מספר

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

  • מסננים

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

    • windowTypes

      WindowType[]

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