תיאור
שימוש ב-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 OS.
טיפוסים בני מנייה (enum)
"רגיל"
מציין את החלון כחלון רגיל.
"חלון קופץ"
מציין את החלון כחלון קופץ.
"panel"
מציין את החלון כלוח.
QueryOptions
תכונות
-
לאכלס
בוליאני אופציונלי
אם הערך הוא 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
המצב של חלון הדפדפן הזה. במקרים מסוימים, יכול להיות שחלון לא יוקצה לנכס state
. לדוגמה, כשמריצים שאילתות על חלונות סגורים מ-sessions
API.
טיפוסים בני מנייה (enum)
'רגיל'
מצב חלון רגיל (לא ממוזער, מוגדל או מסך מלא).
"מוקטן"
מצב חלון ממוזער.
"מקסימלי"
מצב חלון מוגדל.
"מסך מלא"
מצב חלון מסך מלא.
"locked-fullscreen"
מצב החלון במסך מלא נעול. לא ניתן לצאת ממצב מסך מלא זה על ידי פעולת משתמש, והוא זמין רק לתוספים ברשימת ההיתרים ב-Chrome OS.
WindowType
סוג חלון הדפדפן הזה. במקרים מסוימים, יכול להיות שלא יוקצה מאפיין type
לחלון. לדוגמה, כשמריצים שאילתות על חלונות סגורים מ-API של sessions
.
טיפוסים בני מנייה (enum)
"רגיל"
חלון דפדפן רגיל.
"חלון קופץ"
חלון קופץ בדפדפן.
"panel"
הוצא משימוש ב-API זה. חלון בסגנון חלונית של אפליקציית Chrome. לתוספים יש רק חלונות של לוחות משלהם.
"app"
הוצא משימוש ב-API הזה. חלון של אפליקציית Chrome. תוספים יכולים לראות רק את החלונות של האפליקציה שלהם.
"devtools"
חלון כלים למפתחים.
תכונות
WINDOW_ID_CURRENT
ערך windowId שמייצג את החלון הנוכחי.
ערך
-2
WINDOW_ID_NONE
ערך windowId שמייצג את היעד ללא חלון של דפדפן Chrome.
ערך
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[] אופציונלי
כתובת URL או מערך של כתובות URL לפתיחה ככרטיסיות בחלון. כתובות URL שמוגדרות באופן מלא חייבות לכלול סכמה, לדוגמה: 'http://www.google.com', לא 'www.google.com'. כתובות URL שאינן כשירות באופן מלא נחשבות כיחסיות בתוך התוסף. ברירת המחדל היא דף הכרטיסייה החדשה.
-
רוחב
מספר אופציונלי
הרוחב בפיקסלים של החלון החדש, כולל המסגרת. אם לא מגדירים רוחב, ברירת המחדל היא רוחב טבעי.
-
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(window?: Window) => void
-
חלון
חלון אופציונלי
מכילה פרטים על החלון שנוצר.
-
החזרות
-
Promise<Window | undefined>
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
-
חלון
-
החזרות
-
הבטחה<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
number
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 88 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
update()
chrome.windows.update(
windowId: number,
updateInfo: object,
callback?: function,
)
עדכון המאפיינים של חלון. צריך לציין רק את המאפיינים שרוצים לשנות. מאפיינים שלא צוינו לא ישתנו.
פרמטרים
-
windowId
number
-
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.windows.onBoundsChanged.addListener(
callback: function,
)
מופעל כשמשנים גודל של חלון; אירוע זה נשלח רק כאשר הגבולות החדשים נדרשים, ולא עבור שינויים שמתבצעים.
onCreated
chrome.windows.onCreated.addListener(
callback: function,
filters?: object,
)
מופעל כשחלון נוצר.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
Chrome 46 ואילךהפרמטר
callback
נראה כך:(window: Window) => void
-
חלון
פרטים על החלון שנוצר.
-
-
מסננים
אובייקט אופציונלי
-
windowTypes
התנאים שסוג החלון נוצר חייבים לעמוד בהם. כברירת מחדל, הוא עומד ב
['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
התנאים שסוג החלון שמסירים צריכים לעמוד בהם. כברירת מחדל, הוא עומד ב
['normal', 'popup']
.
-
onRemoved
chrome.windows.onRemoved.addListener(
callback: function,
filters?: object,
)
מופעל כשחלון מוסר (נסגר).
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
Chrome 46 ואילךהפרמטר
callback
נראה כך:(windowId: number) => void
-
windowId
number
המזהה של החלון שהוסר.
-
-
מסננים
אובייקט אופציונלי
-
windowTypes
התנאים שסוג החלון שמסירים צריכים לעמוד בהם. כברירת מחדל, הוא עומד ב
['normal', 'popup']
.
-