chrome.app.window

תיאור

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

סוגים

AppWindow

מאפיינים

  • contentWindow

    חלון

    אובייקט ה-JavaScript ‏ 'window' עבור החלון המשני שנוצר.

  • id [מזהה]

    מחרוזת

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

  • innerBounds

    Bounds

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

  • outerBounds

    Bounds

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

  • clearAttention

    void

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

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

    () => {...}

  • סגירה

    void

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

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

    () => {...}

  • drawAttention

    void

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

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

    () => {...}

  • מיקוד

    void

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

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

    () => {...}

  • מסך מלא

    void

    החלון יוצג במסך מלא.

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

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

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

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

    () => {...}

  • getBounds

    void

    הוצא משימוש

    משתמשים ב-innerBounds או ב-outerBounds.

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

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

    () => {...}

  • הסתר

    void

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

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

    () => {...}

  • isAlwaysOnTop

    void

    החלון תמיד מוצג בחזית?

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

    () => {...}

    • החזרות

      בוליאני

  • isFullscreen

    void

    החלון במסך מלא? הערך יהיה True אם החלון נוצר במסך מלא או אם הוא הוגדר למסך מלא באמצעות AppWindow או ממשקי API של 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) => {...}

    • ממוקד

      ‫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

    ‫boolean אופציונלי

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

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

  • גבולות

    ‫ContentBounds אופציונלי

    הוצא משימוש

    משתמשים ב-innerBounds או ב-outerBounds.

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

  • ממוקד

    ‫boolean אופציונלי

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

  • פריים

    string | FrameOptions אופציונלי

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

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

  • מוסתר

    ‫boolean אופציונלי

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

  • סימן השאלה

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

    ‫Chrome 54 ואילך

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

  • id [מזהה]

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

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

  • innerBounds

    ‫BoundsSpecification אופציונלי

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

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

    המאפיין הזה חדש בגרסה 36 של Chrome.

  • maxHeight

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

    הוצא משימוש

    משתמשים ב-innerBounds או ב-outerBounds.

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

  • maxWidth

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

    הוצא משימוש

    משתמשים ב-innerBounds או ב-outerBounds.

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

  • minHeight

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

    הוצא משימוש

    משתמשים ב-innerBounds או ב-outerBounds.

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

  • minWidth

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

    הוצא משימוש

    משתמשים ב-innerBounds או ב-outerBounds.

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

  • outerBounds

    ‫BoundsSpecification אופציונלי

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

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

    המאפיין הזה חדש בגרסה 36 של Chrome.

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

    ‫boolean אופציונלי

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

  • showInShelf

    ‫boolean אופציונלי

    ‫Chrome 54 ואילך

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

  • singleton

    ‫boolean אופציונלי

    הוצא משימוש

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

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

  • הסמוי הסופי

    מדינה אופציונלי

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

  • סוג

    ‫WindowType אופציונלי

    ‫Chrome 45+‎ הוצא משימוש מאז Chrome 69

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

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

  • visibleOnAllWorkspaces

    ‫boolean אופציונלי

    אם הערך הוא 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"
סוג ברירת המחדל של החלון.

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

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

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

פרמטרים

  • כתובת אתר

    מחרוזת

  • options

    ‫CreateWindowOptions אופציונלי

  • callback

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

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

    (createdWindow: AppWindow) => void

החזרות

  • Promise<AppWindow>

    ‫Chrome 117 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

current()

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

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

החזרות

get()

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

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

פרמטרים

  • id [מזהה]

    מחרוזת

החזרות

getAll()

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

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

החזרות

אירועים

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