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 נראית כך:

  () => {...}

  • החזרות

    ContentBounds

• הסתר

  ריק

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

  הפונקציה 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) => {...}

  • גבולות

    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

  • createdWindow

    AppWindow

החזרות

• Promise<AppWindow>

  Chrome 117 ואילך

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

current()

chrome.app.window.current()

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

החזרות

• AppWindow | לא מוגדר

get()

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

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

פרמטרים

• id [מזהה]

  מחרוזת

החזרות

• AppWindow | לא מוגדר

getAll()

chrome.app.window.getAll()

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

החזרות

• AppWindow[]

אירועים

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