chrome.app.window

תיאור

משתמשים ב-API‏ chrome.app.window כדי ליצור חלונות. לחלונות יש מסגרת אופציונלית עם סרגל כותרת ופקדי גודל. הם לא משויכים לאף חלון בדפדפן Chrome. בדוגמה למצב חלון אפשר לראות הדגמה של האפשרויות האלה.

סוגים

AppWindow

מאפיינים

  • contentWindow

    חלון

    אובייקט ה-JavaScript 'window' של הצאצא שנוצר.

  • id [מזהה]

    מחרוזת

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

  • innerBounds

    גבולות

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

  • outerBounds

    גבולות

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

  • clearAttention

    void

    הסרת המיקוד מהחלון.

    הפונקציה clearAttention נראית כך: 

    () => {...}

  • סגירה

    void

    סגור את החלון.

    הפונקציה close נראית כך: 

    () => {...}

  • drawAttention

    void

    למשוך את תשומת הלב לחלון.

    הפונקציה drawAttention נראית כך: 

    () => {...}

  • מיקוד

    void

    להתמקד בחלון.

    הפונקציה focus נראית כך: 

    () => {...}

  • מסך מלא

    void

    החלון נפתח במסך מלא.

    המשתמש יוכל לשחזר את החלון בלחיצה על ESC. אפליקציה יכולה למנוע יציאה ממצב מסך מלא כשמקישים על ESC. כדי לעשות את זה, היא צריכה לבקש את ההרשאה app.window.fullscreen.overrideEsc ולבטל את האירוע באמצעות קריאה ל-‎.preventDefault()‎ ב-keydown וב-keyup handlers, באופן הבא:

    window.onkeydown = window.onkeyup = function(e) { if (e.keyCode == 27 /* ESC *\/) { e.preventDefault(); } };

    הערה: window.fullscreen() יגרום לכל החלון לעבור למסך מלא, ולא נדרשת תנועה של המשתמש. אפשר גם להשתמש ב-HTML5 fullscreen API כדי להיכנס למצב מסך מלא (פרטים נוספים זמינים במאמר בנושא ממשקי Web API).

    הפונקציה fullscreen נראית כך: 

    () => {...}

  • getBounds

    void

    הוצא משימוש

    צריך להשתמש ב-innerBounds או ב-outerBounds.

    אחזור הגבולות הפנימיים של החלון כאובייקט ContentBounds.

    הפונקציה getBounds נראית כך: 

    () => {...}

  • הסתר

    void

    מסתירים את החלון. אם החלון כבר מוסתר, לא קורה כלום.

    הפונקציה hide נראית כך: 

    () => {...}

  • isAlwaysOnTop

    void

    האם החלון תמיד למעלה?

    הפונקציה isAlwaysOnTop נראית כך: 

    () => {...}

    • החזרות

      בוליאני

  • isFullscreen

    void

    האם החלון מוצג במסך מלא? הערך יהיה True אם החלון נוצר במסך מלא או הועבר למסך מלא באמצעות ממשקי ה-API של AppWindow או HTML5.

    הפונקציה isFullscreen נראית כך: 

    () => {...}

    • החזרות

      בוליאני

  • isMaximized

    void

    האם החלון מוגדל?

    הפונקציה isMaximized נראית כך: 

    () => {...}

    • החזרות

      בוליאני

  • isMinimized

    void

    האם החלון ממוזער?

    הפונקציה isMinimized נראית כך: 

    () => {...}

    • החזרות

      בוליאני

  • הגדלה

    void

    מגדילים את החלון.

    הפונקציה maximize נראית כך: 

    () => {...}

  • מזעור

    void

    מזעור החלון.

    הפונקציה minimize נראית כך: 

    () => {...}

  • moveTo

    void

    הוצא משימוש ב-Chrome 43

    צריך להשתמש ב-outerBounds.

    העברת החלון למיקום (left, top).

    הפונקציה moveTo נראית כך: 

    (left: number, top: number) => {...}

    • שמאלה

      number

    • עליון

      number

  • resizeTo

    void

    הוצא משימוש ב-Chrome 43

    צריך להשתמש ב-outerBounds.

    משנים את גודל החלון ל-widthxheight פיקסלים.

    הפונקציה resizeTo נראית כך: 

    (width: number, height: number) => {...}

    • רוחב

      number

    • גובה

      number

  • שחזור

    void

    שחזור החלון, יציאה ממצב של הגדלה, מזעור או מסך מלא.

    הפונקציה restore נראית כך: 

    () => {...}

  • setAlwaysOnTop

    void

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

    הפונקציה setAlwaysOnTop נראית כך: 

    (alwaysOnTop: boolean) => {...}

    • alwaysOnTop

      בוליאני

  • setBounds

    void

    הוצא משימוש

    צריך להשתמש ב-innerBounds או ב-outerBounds.

    הגדרת הגבולות הפנימיים של החלון.

    הפונקציה setBounds נראית כך: 

    (bounds: ContentBounds) => {...}

  • setVisibleOnAllWorkspaces

    void

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

    הפונקציה setVisibleOnAllWorkspaces נראית כך: 

    (alwaysVisible: boolean) => {...}

    • alwaysVisible

      בוליאני

  • הצג

    void

    מציגים את החלון. אם החלון כבר גלוי, לא קורה כלום. אם המדיניות focused מוגדרת כ-true או לא מוגדרת, החלון יתמקד.

    הפונקציה show נראית כך: 

    (focused?: boolean) => {...}

    • ממוקד

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

Bounds

מאפיינים

  • גובה

    number

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

  • שמאלה

    number

    אפשר להשתמש במאפיין הזה כדי לקרוא או לכתוב את קואורדינטת ה-X הנוכחית של התוכן או החלון.

  • maxHeight

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

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

  • maxWidth

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

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

  • minHeight

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

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

  • minWidth

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

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

  • עליון

    number

    אפשר להשתמש במאפיין הזה כדי לקרוא או לכתוב את קואורדינטת ה-Y הנוכחית של התוכן או החלון.

  • רוחב

    number

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

  • setMaximumSize

    void

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

    הפונקציה setMaximumSize נראית כך: 

    (maxWidth: number, maxHeight: number) => {...}

    • maxWidth

      number

    • maxHeight

      number

  • setMinimumSize

    void

    מגדירים את מגבלות הגודל המינימלי של התוכן או החלון. כדי להסיר את המגבלה, אפשר להגדיר את הרוחב או הגובה המינימליים ל-null. ערך של undefined לא ישנה את המגבלה.

    הפונקציה setMinimumSize נראית כך: 

    (minWidth: number, minHeight: number) => {...}

    • minWidth

      number

    • minHeight

      number

  • setPosition

    void

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

    הפונקציה setPosition נראית כך: 

    (left: number, top: number) => {...}

    • שמאלה

      number

    • עליון

      number

  • setSize

    void

    הגדרת הרוחב והגובה של התוכן או החלון.

    הפונקציה setSize נראית כך: 

    (width: number, height: number) => {...}

    • רוחב

      number

    • גובה

      number

BoundsSpecification

מאפיינים

  • גובה

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

    הגובה של התוכן או החלון.

  • שמאלה

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

    קואורדינטת ה-X של התוכן או החלון.

  • maxHeight

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

    הגובה המקסימלי של התוכן או החלון.

  • maxWidth

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

    הרוחב המקסימלי של התוכן או החלון.

  • minHeight

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

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

  • minWidth

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

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

  • עליון

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

    קואורדינטת ה-Y של התוכן או החלון.

  • רוחב

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

    רוחב התוכן או החלון.

ContentBounds

מאפיינים

  • גובה

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

  • שמאלה

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

  • עליון

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

  • רוחב

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

CreateWindowOptions

מאפיינים

  • alwaysOnTop

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

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

    כדי לשנות את המאפיין הזה אחרי היצירה, צריך להפעיל את setAlwaysOnTop() בחלון.

  • גבולות

    ‫ContentBounds אופציונלי

    הוצא משימוש

    צריך להשתמש ב-innerBounds או ב-outerBounds.

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

  • ממוקד

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

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

  • פריים

    string | FrameOptions optional

    סוג המסגרת: none או chrome (ברירת המחדל היא chrome). ב-none, אפשר להשתמש במאפיין ה-CSS‏ -webkit-app-region כדי להחיל יכולת גרירה על חלון האפליקציה. אפשר להשתמש ב--webkit-app-region: drag כדי לסמן אזורים שניתן לגרור. אפשר להשתמש ב-no-drag כדי להשבית את הסגנון הזה ברכיבים מקוננים.

    השימוש ב-FrameOptions הוא חדש ב-M36.

  • מוסתר

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

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

  • סימן השאלה

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

    ‫Chrome מגרסה 54 ואילך

    כתובת ה-URL של סמל החלון. לחלון יכול להיות סמל משלו אם הערך של showInShelf מוגדר כ-true. כתובת ה-URL צריכה להיות כתובת URL גלובלית או כתובת URL מקומית של תוסף.

  • id [מזהה]

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

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

  • innerBounds

    BoundsSpecification אופציונלי

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

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

    המאפיין הזה חדש ב-Chrome 36.

  • maxHeight

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

    הוצא משימוש

    צריך להשתמש ב-innerBounds או ב-outerBounds.

    הגובה המקסימלי של החלון.

  • maxWidth

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

    הוצא משימוש

    צריך להשתמש ב-innerBounds או ב-outerBounds.

    הרוחב המקסימלי של החלון.

  • minHeight

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

    הוצא משימוש

    צריך להשתמש ב-innerBounds או ב-outerBounds.

    הגובה המינימלי של החלון.

  • minWidth

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

    הוצא משימוש

    צריך להשתמש ב-innerBounds או ב-outerBounds.

    הרוחב המינימלי של החלון.

  • outerBounds

    BoundsSpecification אופציונלי

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

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

    המאפיין הזה חדש ב-Chrome 36.

  • ניתן לשנות את הגודל

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

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

  • showInShelf

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

    ‫Chrome מגרסה 54 ואילך

    אם המדיניות מוגדרת כ-True, לחלון יהיה סמל משלו במדף. אחרת, החלון יקובץ במדף עם חלונות אחרים שמשויכים לאפליקציה. ערך ברירת המחדל הוא False. אם הערך של showInShelf הוא True, צריך לציין מזהה לחלון.

  • singleton

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

    הוצא משימוש

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

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

  • מדינה (State)

    ‫State (מדינה) אופציונלי

    המצב הראשוני של החלון, שמאפשר ליצור אותו כבר במצב מסך מלא, מוגדל או ממוזער. ברירת המחדל היא "normal".

  • סוג

    ‫WindowType אופציונלי

    ‫Chrome מגרסה 45 ואילך הוצא משימוש בגרסה 69 של Chrome

    כל חלונות האפליקציות משתמשים בסוג החלון shell

    סוג החלון שרוצים ליצור.

  • visibleOnAllWorkspaces

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

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

FrameOptions

מאפיינים

  • activeColor

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

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

    אפשר לצבוע את המסגרת רק אם סוג המסגרת הוא chrome.

    צביעת המסגרת היא תכונה חדשה ב-Chrome 36.

  • צבע

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

    מאפשר להגדיר את צבע המסגרת. אפשר לצבוע את המסגרת רק אם סוג המסגרת הוא chrome.

    צביעת המסגרת היא תכונה חדשה ב-Chrome 36.

  • inactiveColor

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

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

    צריך להשתמש ב-inactiveColor בשילוב עם color.

    צביעת המסגרת היא תכונה חדשה ב-Chrome 36.

  • סוג

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

    סוג הפריים: none או chrome (ברירת המחדל היא chrome).

    ב-none, אפשר להשתמש במאפיין ה-CSS‏ -webkit-app-region כדי להחיל יכולת גרירה על חלון האפליקציה.

    אפשר להשתמש ב--webkit-app-region: drag כדי לסמן אזורים שניתן לגרור. אפשר להשתמש ב-no-drag כדי להשבית את הסגנון הזה ברכיבים בתצוגת עץ.

State

מצב החלון: רגיל, מסך מלא, מוגדל, ממוזער.

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

"normal"

"fullscreen"

"maximized"

"minimized"

WindowType

‫Chrome 45 ואילך

מציין את סוג החלון שרוצים ליצור.

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

"shell"
סוג החלון שמוגדר כברירת מחדל.

"panel"
חלון שמנוהל על ידי מערכת ההפעלה (הוצא משימוש).

Methods

canSetVisibleOnAllWorkspaces()

chrome.app.window.canSetVisibleOnAllWorkspaces(): boolean

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

החזרות

  • בוליאני

create()

Promise 
chrome.app.window.create(
  url: string,
  options?: CreateWindowOptions,
  callback?: function,
): Promise<AppWindow>

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

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

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

פרמטרים

  • url

    מחרוזת

  • אפשרויות

    ‫CreateWindowOptions אופציונלי

  • callback

    function optional

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

    (createdWindow: AppWindow) => void

החזרות

  • Promise<AppWindow>

    ‫Chrome מגרסה 117 ואילך

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

current()

chrome.app.window.current(): AppWindow | undefined

מחזירה אובייקט AppWindow להקשר הנוכחי של הסקריפט (כלומר אובייקט window של JavaScript). אפשר גם להפעיל את הפונקציה הזו על נקודת אחיזה להקשר של סקריפט בדף אחר, לדוגמה: otherWindow.chrome.app.window.current().‎

החזרות

get()

chrome.app.window.get(
  id: string,
): AppWindow | undefined

מקבלת AppWindow עם המזהה שצוין. אם לא קיים חלון עם המזהה שצוין, יוחזר ערך null. השיטה הזו חדשה ב-Chrome 33.

פרמטרים

  • id [מזהה]

    מחרוזת

החזרות

getAll()

chrome.app.window.getAll(): AppWindow[]

מקבל מערך של כל חלונות האפליקציות שנוצרו כרגע. השיטה הזו חדשה ב-Chrome 33.

החזרות

אירועים

onBoundsChanged

chrome.app.window.onBoundsChanged.addListener(
  callback: function,
)

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

פרמטרים

  • callback

    פונקציה

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

    () => void

onClosed

chrome.app.window.onClosed.addListener(
  callback: function,
)

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

פרמטרים

  • callback

    פונקציה

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

    () => void

onFullscreened

chrome.app.window.onFullscreened.addListener(
  callback: function,
)

מופעל כשהחלון מוצג במסך מלא (באמצעות AppWindow או ממשקי API של HTML5).

פרמטרים

  • callback

    פונקציה

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

    () => void

onMaximized

chrome.app.window.onMaximized.addListener(
  callback: function,
)

מופעל כשהחלון מוגדל.

פרמטרים

  • callback

    פונקציה

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

    () => void

onMinimized

chrome.app.window.onMinimized.addListener(
  callback: function,
)

מופעל כשהחלון ממוזער.

פרמטרים

  • callback

    פונקציה

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

    () => void

onRestored

chrome.app.window.onRestored.addListener(
  callback: function,
)

מופעל כשהחלון משוחזר ממצב ממוזער או מוגדל.

פרמטרים

  • callback

    פונקציה

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

    () => void