chrome.app.window

תיאור

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

סוגים

AppWindow

מאפיינים

  • contentWindow

    חלון

    'חלון' של JavaScript בשביל הצאצא שנוצר.

  • id [מזהה]

    מחרוזת

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

  • innerBounds

    גבולות

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

  • outerBounds

    גבולות

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

  • clearAttention

    ריק

    מפנים את תשומת הלב לחלון.

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

    () => {...}

  • סגירה

    ריק

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

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

    () => {...}

  • drawAttention

    ריק

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

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

    () => {...}

  • מיקוד

    ריק

    מתמקדים בחלון.

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

    () => {...}

  • מסך מלא

    ריק

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

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

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

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

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

    () => {...}

  • getBounds

    ריק

    הוצא משימוש

    השתמשו בגבולות פנימיים או גבולות חיצוניים.

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

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

    () => {...}

  • הסתר

    ריק

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

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

    () => {...}

  • isAlwaysOnTop

    ריק

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

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

    () => {...}

    • החזרות

      בוליאני

  • isFullscreen

    ריק

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

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

    () => {...}

    • החזרות

      בוליאני

  • isMaximized

    ריק

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

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

    () => {...}

    • החזרות

      בוליאני

  • isMinimized

    ריק

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

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

    () => {...}

    • החזרות

      בוליאני

  • הגדלה

    ריק

    הגדלת החלון.

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

    () => {...}

  • מזעור

    ריק

    מזעור החלון.

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

    () => {...}

  • moveTo

    ריק

    הוצא משימוש מאז Chrome 43

    שימוש בגבולות חיצוניים.

    מזיזים את החלון למיקום (left, top).

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

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

    • שמאלי

      number

    • עליון

      number

  • resizeTo

    ריק

    הוצא משימוש מאז Chrome 43

    שימוש בגבולות חיצוניים.

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

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

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

    • רוחב

      number

    • גובה

      number

  • שחזור

    ריק

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

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

    () => {...}

  • setAlwaysOnTop

    ריק

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

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

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

    • alwaysOnTop

      בוליאני

  • setBounds

    ריק

    הוצא משימוש

    השתמשו בגבולות פנימיים או גבולות חיצוניים.

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

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

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

  • setVisibleOnAllWorkspaces

    ריק

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

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

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

    • alwaysVisible

      בוליאני

  • הצג

    ריק

    הצגת החלון. לא יקרה כלום אם החלון כבר גלוי. מיקוד החלון אם focused מוגדר כ-True או הושמט.

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

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

    • ממוקד

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

Bounds

מאפיינים

  • גובה

    number

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

  • שמאלי

    number

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

  • maxHeight

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

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

  • maxWidth

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

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

  • minHeight

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

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

  • minWidth

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

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

  • עליון

    number

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

  • רוחב

    number

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

  • setMaximumSize

    ריק

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

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

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

    • maxWidth

      number

    • maxHeight

      number

  • setMinimumSize

    ריק

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

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

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

    • minWidth

      number

    • minHeight

      number

  • setPosition

    ריק

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

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

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

    • שמאלי

      number

    • עליון

      number

  • setSize

    ריק

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

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

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

    • רוחב

      number

    • גובה

      number

BoundsSpecification

מאפיינים

  • גובה

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

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

  • שמאלי

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

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

  • maxHeight

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

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

  • maxWidth

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

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

  • minHeight

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

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

  • minWidth

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

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

  • עליון

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

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

  • רוחב

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

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

ContentBounds

מאפיינים

  • גובה

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

  • שמאלי

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

  • עליון

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

  • רוחב

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

CreateWindowOptions

מאפיינים

  • alwaysOnTop

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

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

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

  • גבולות

    ContentBounds אופציונלי

    הוצא משימוש

    השתמשו בגבולות פנימיים או גבולות חיצוניים.

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

  • ממוקד

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

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

  • מסגרת

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

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

    השימוש ב-FrameOptions חדש בגרסה M36.

  • מוסתר

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

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

  • סמל

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

    Chrome 54+

    כתובת ה-URL של סמל החלון. כשמגדירים חלון כ-True, לצד החלון יכול להיות סמל משלו. כתובת ה-URL צריכה להיות כתובת URL גלובלית או של תוסף מקומי.

  • id [מזהה]

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

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

  • innerBounds

    BoundsSpecification אופציונלי

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

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

    הנכס הזה חדש ב-Chrome 36.

  • maxHeight

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

    הוצא משימוש

    השתמשו בגבולות פנימיים או גבולות חיצוניים.

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

  • maxWidth

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

    הוצא משימוש

    השתמשו בגבולות פנימיים או גבולות חיצוניים.

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

  • minHeight

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

    הוצא משימוש

    השתמשו בגבולות פנימיים או גבולות חיצוניים.

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

  • minWidth

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

    הוצא משימוש

    השתמשו בגבולות פנימיים או גבולות חיצוניים.

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

  • outerBounds

    BoundsSpecification אופציונלי

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

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

    הנכס הזה חדש ב-Chrome 36.

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

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

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

  • showInShelf

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

    Chrome 54+

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

  • singleton

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

    הוצא משימוש

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

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

  • הסמוי הסופי

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

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

  • סוג

    WindowType אופציונלי

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

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

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

  • visibleOnAllWorkspaces

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

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

FrameOptions

מאפיינים

  • activeColor

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

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

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

    צבעי פריימים חדשים ב-Chrome 36.

  • color [צבע]

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

    מאפשרת להגדיר את צבע המסגרת. אפשר לצבוע מסגרת רק אם סוג המסגרת הוא 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

"רגיל"

"מסך מלא"

"מקסימלית"

"מזעור"

WindowType

Chrome 45+

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

Enum

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

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

שיטות

canSetVisibleOnAllWorkspaces()

chrome.app.window.canSetVisibleOnAllWorkspaces()

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

החזרות

  • בוליאני

create()

הבטחה 
chrome.app.window.create(
  url: string,
  options?: CreateWindowOptions,
  callback?: function,
)

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

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

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

פרמטרים

  • כתובת אתר

    מחרוזת

  • אפשרויות

    CreateWindowOptions אופציונלית

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

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

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

    (createdWindow: AppWindow) => void

החזרות

  • Promise<AppWindow>

    Chrome 117 ואילך

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

current()

chrome.app.window.current()

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

החזרות

get()

chrome.app.window.get(
  id: string,
)

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

פרמטרים

  • id [מזהה]

    מחרוזת

החזרות

getAll()

chrome.app.window.getAll()

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