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 work, הערך של החלון הנוכחי חוזר לערך הפעיל האחרון חלון. בנסיבות מסוימות, ייתכן שאין חלון נוכחי לדפי רקע.

דוגמאות

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

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

סוגים

CreateType

Chrome 44 ואילך

מציינת איזה סוג של חלון דפדפן ליצור. 'panel' הוצאה משימוש וזמינה רק לתוספים קיימים שנמצאים ברשימת ההיתרים ב-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

    בוליאני

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

  • ממוקד

    בוליאני

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

  • גובה

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

    גובה החלון, כולל המסגרת, בפיקסלים. בנסיבות מסוימות לא ניתן להקצות לחלון נכס 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

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

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

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

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

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

WindowType

Chrome 44 ואילך

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

Enum

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

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

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

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

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

מאפיינים

WINDOW_ID_CURRENT

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

ערך

-2

WINDOW_ID_NONE

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

ערך

-1

שיטות

create()

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

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

פרמטרים

  • createData

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

    • ממוקד

      ערך בוליאני אופציונלי

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

    • גובה

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

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

    • גלישה פרטית

      ערך בוליאני אופציונלי

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

    • שמאלי

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

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

    • setSelfAsOpener

      ערך בוליאני אופציונלי

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

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

    • הסמוי הסופי

      WindowState אופציונלי

      Chrome 44 ואילך

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

    • tabId

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

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

    • עליון

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

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

    • סוג

      CreateType אופציונלי

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

    • כתובת אתר

      string | string[] אופציונלי

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

    • רוחב

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

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

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

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

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

    (window?: Window) => void

    • חלון

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

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

החזרות

  • Promise<Window | לא מוגדר>

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

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

get()

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

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

פרמטרים

  • windowId

    number

  • queryOptions

    QueryOptions אופציונלי

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

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

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

    (window: Window) => void

החזרות

  • Promise<Window>

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

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

getAll()

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

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

פרמטרים

  • queryOptions

    QueryOptions אופציונלי

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

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

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

    (windows: Window[]) => void

החזרות

  • Promise<Window[]>

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

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

getCurrent()

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

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

פרמטרים

  • queryOptions

    QueryOptions אופציונלי

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

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

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

    (window: Window) => void

החזרות

  • Promise<Window>

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

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

getLastFocused()

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

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

פרמטרים

  • queryOptions

    QueryOptions אופציונלי

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

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

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

    (window: Window) => void

החזרות

  • Promise<Window>

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

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

remove()

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

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

פרמטרים

  • windowId

    number

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

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

update()

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

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

פרמטרים

  • windowId

    number

  • updateInfo

    אובייקט

    • drawAttention

      ערך בוליאני אופציונלי

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

    • ממוקד

      ערך בוליאני אופציונלי

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

    • גובה

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

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

    • שמאלי

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

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

    • הסמוי הסופי

      WindowState אופציונלי

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

    • עליון

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

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

    • רוחב

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

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

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

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

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

    (window: Window) => void

החזרות

  • Promise&lt;Window&gt;

    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

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