browser.sidePanel

תיאור

משתמשים ב-API של chrome.sidePanel כדי לארח תוכן בחלונית הצדדית של הדפדפן לצד התוכן הראשי של דף אינטרנט.

הרשאות

sidePanel

כדי להשתמש ב-Side Panel API, צריך להוסיף את ההרשאה "sidePanel" בקובץ המניפסט של התוסף:

manifest.json:

{
  "name": "My side panel extension",
  ...
  "permissions": [
    "sidePanel"
  ]
}

זמינות

‫Chrome 114 ואילך ‫browser.* ‎ מגרסה Chrome 148 ‫MV3 ואילך

מושגים ושימוש

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

ממשק המשתמש של החלונית הצדדית בדפדפן Chrome.

התכונות כוללות:

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

תרחישים לדוגמה

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

הצגת אותה חלונית צדדית בכל אתר

אפשר להגדיר את חלונית הצד בהתחלה מהמאפיין "default_path" במפתח "side_panel" של המניפסט כדי להציג את אותה חלונית צד בכל אתר. הוא צריך להפנות לנתיב יחסי בתוך ספריית התוסף.

manifest.json:

{
  "name": "My side panel extension",
  ...
  "side_panel": {
    "default_path": "sidepanel.html"
  }
  ...
}

sidepanel.html:

<!DOCTYPE html>
<html>
  <head>
    <title>My Sidepanel</title>
  </head>
  <body>
    <h1>All sites sidepanel extension</h1>
    <p>This side panel is enabled on all sites</p>
  </body>
</html>

הפעלת חלונית צדדית באתר ספציפי

תוסף יכול להשתמש ב-sidepanel.setOptions() כדי להפעיל חלונית צדדית בכרטיסייה ספציפית. בדוגמה הזו נעשה שימוש ב-browser.tabs.onUpdated() כדי להאזין לעדכונים שבוצעו בכרטיסייה. הוא בודק אם כתובת ה-URL היא www.google.com ומפעיל את החלונית הצדדית. אחרת, היא משביתה אותו.

service-worker.js:

const GOOGLE_ORIGIN = 'https://www.google.com';

browser.tabs.onUpdated.addListener(async (tabId, info, tab) => {
  if (!tab.url) return;
  const url = new URL(tab.url);
  // Enables the side panel on google.com
  if (url.origin === GOOGLE_ORIGIN) {
    await browser.sidePanel.setOptions({
      tabId,
      path: 'sidepanel.html',
      enabled: true
    });
  } else {
    // Disables the side panel on all other sites
    await browser.sidePanel.setOptions({
      tabId,
      enabled: false
    });
  }
});

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

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

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

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

מפתחים יכולים לאפשר למשתמשים לפתוח את החלונית הצדדית כשהם לוחצים על סמל סרגל הכלים של הפעולה באמצעות sidePanel.setPanelBehavior(). קודם כל, צריך להצהיר על המפתח "action" במניפסט:

manifest.json:

{
  "name": "My side panel extension",
  ...
  "action": {
    "default_title": "Click to open panel"
  },
  ...
}

עכשיו, מוסיפים את הקוד הזה לדוגמה הקודמת:

service-worker.js:

const GOOGLE_ORIGIN = 'https://www.google.com';

// Allows users to open the side panel by clicking on the action toolbar icon
browser.sidePanel
  .setPanelBehavior({ openPanelOnActionClick: true })
  .catch((error) => console.error(error));
...

פתיחה פרוגרמטית של החלונית הצדדית באינטראקציה של המשתמש

ב-Chrome 116 יש sidePanel.open(). היא מאפשרת לתוספים לפתוח את החלונית הצדדית באמצעות תנועה של המשתמש בתוסף, כמו לחיצה על סמל הפעולה. או אינטראקציה של משתמש בדף של תוסף או בסקריפט תוכן, כמו לחיצה על כפתור. להדגמה מלאה, אפשר לעיין בתוסף לדוגמה פתיחת חלונית צדדית.

הקוד הבא מראה איך לפתוח חלונית צדדית גלובלית בחלון הנוכחי כשהמשתמש לוחץ על תפריט הקשר. כשמשתמשים ב-sidePanel.open(), צריך לבחור את ההקשר שבו הוא ייפתח. מקישים על windowId כדי לפתוח חלונית צדדית גלובלית. אפשר גם להגדיר את tabId כך שהחלונית הצדדית תיפתח רק בכרטיסייה ספציפית.

service-worker.js:

browser.runtime.onInstalled.addListener(() => {
  browser.contextMenus.create({
    id: 'openSidePanel',
    title: 'Open side panel',
    contexts: ['all']
  });
});

browser.contextMenus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === 'openSidePanel') {
    // This will open the panel in all the pages on the current window.
    browser.sidePanel.open({ windowId: tab.windowId });
  }
});

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

מעבר לחלונית אחרת

תוספים יכולים להשתמש ב-sidepanel.getOptions() כדי לאחזר את חלונית הצד הנוכחית. בדוגמה הבאה מוגדרת חלונית צדדית של הודעת פתיחה ב-runtime.onInstalled(). כשהמשתמש עובר לכרטיסייה אחרת, החלונית מוחלפת בחלונית הצדדית הראשית.

service-worker.js:

const welcomePage = 'sidepanels/welcome-sp.html';
const mainPage = 'sidepanels/main-sp.html';

browser.runtime.onInstalled.addListener(() => {
  browser.sidePanel.setOptions({ path: welcomePage });
  browser.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
});

browser.tabs.onActivated.addListener(async ({ tabId }) => {
  const { path } = await browser.sidePanel.getOptions({ tabId });
  if (path === welcomePage) {
    browser.sidePanel.setOptions({ path: mainPage });
  }
});

הקוד המלא מופיע בדוגמה חלוניות צדדיות מרובות.

חוויית המשתמש בחלונית הצדדית

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

פתיחת החלונית הצדדית

כדי לאפשר למשתמשים לפתוח את החלונית הצדדית, משתמשים בסמל פעולה בשילוב עם sidePanel.setPanelBehavior(). לחלופין, אפשר לבצע קריאה ל-sidePanel.open() אחרי אינטראקציה של המשתמש, למשל:

• קליק מסוג פעולה
• מקש קיצור
• תפריט הקשר
• תנועה של המשתמש בדף של התוסף או בסקריפט תוכן.

הצמדת החלונית הצדדית

סמל ההצמדה בממשק המשתמש של החלונית הצדדית.

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

דוגמאות

כדי לראות עוד הדגמות של תוספים ל-Side Panel API, אפשר לעיין בתוספים הבאים:

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

סוגים

CloseOptions

‫Chrome 141 ואילך ‫‎browser.* ‎ מגרסה Chrome 148

מאפיינים

• tabId

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

  הכרטיסייה שבה רוצים לסגור את החלונית הצדדית. אם חלונית צדדית ספציפית לכרטיסייה פתוחה בכרטיסייה שצוינה, היא תיסגר בכרטיסייה הזו. אם רק חלונית הצד הגלובלית פתוחה, ההבטחה שמוחזרת על ידי הקריאה ל-close() תידחה עם שגיאה. ההתנהגות הזו השתנתה ב-Chrome 145, ובגרסאות קודמות החלונית הגלובלית נסגרת. צריך לציין לפחות את השדה הזה או את השדה windowId.

• windowId

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

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

GetPanelOptions

מאפיינים

• tabId

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

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

OpenOptions

‫Chrome 116 ואילך ‫browser.* ‎ מ-Chrome 148

מאפיינים

• tabId

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

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

• windowId

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

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

PanelBehavior

מאפיינים

• openPanelOnActionClick

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

  אם לחיצה על סמל התוסף תגרום להצגת הרשומה של התוסף בחלונית הצדדית. ברירת המחדל היא False.

PanelClosedInfo

‫Chrome 142 ואילך ‫browser.* ‎ מגרסה Chrome 148

מאפיינים

• נתיב

  מחרוזת

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

• tabId

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

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

• windowId

  number

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

PanelLayout

‫Chrome מגרסה 140 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

מאפיינים

• קבוצה

  צד

PanelOpenedInfo

‫Chrome 141 ואילך ‫‎browser.* ‎ מגרסה Chrome 148

מאפיינים

• נתיב

  מחרוזת

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

• tabId

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

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

• windowId

  number

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

PanelOptions

מאפיינים

• פעיל

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

  אם החלונית הצדדית צריכה להיות מופעלת. הפעולה הזאת אופציונלית. ערך ברירת המחדל הוא True.

• נתיב

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

  הנתיב לקובץ ה-HTML של חלונית הצד שבו רוצים להשתמש. המשאב הזה חייב להיות משאב מקומי בחבילת התוסף.

• tabId

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

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

Side

‫Chrome מגרסה 140 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

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

"left"

"right"

SidePanel

מאפיינים

• default_path

  מחרוזת

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

Methods

close()

‫Chrome 141 ואילך ‫‎browser.* ‎ מגרסה Chrome 148

browser.sidePanel.close(
  options: CloseOptions,
): Promise<void>

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

פרמטרים

• אפשרויות

  CloseOptions

  מציין את ההקשר שבו החלונית הצדדית תיסגר.

החזרות

• Promise<void>

  מחזירה Promise שמתבצעת כשהחלונית הצדדית נסגרת.

getLayout()

‫Chrome מגרסה 140 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

browser.sidePanel.getLayout(): Promise<PanelLayout>

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

החזרות

• Promise<PanelLayout>

  מחזירה Promise שמתקבל עם PanelLayout.

getOptions()

browser.sidePanel.getOptions(
  options: GetPanelOptions,
): Promise<PanelOptions>

מחזירה את הגדרת החלונית הפעילה.

פרמטרים

• אפשרויות

  GetPanelOptions

  מציין את ההקשר שבו צריך להחזיר את ההגדרות האישיות.

החזרות

• Promise<PanelOptions>

  מחזירה Promise שמתקבלת עם הגדרת החלונית הפעילה.

getPanelBehavior()

browser.sidePanel.getPanelBehavior(): Promise<PanelBehavior>

הפונקציה מחזירה את ההתנהגות הנוכחית של חלונית הצד של התוסף.

החזרות

• Promise<PanelBehavior>

  מחזירה Promise שמתקבלת עם ההתנהגות של חלונית הצד של התוסף.

open()

‫Chrome 116 ואילך ‫browser.* ‎ מ-Chrome 148

browser.sidePanel.open(
  options: OpenOptions,
): Promise<void>

פותחת את החלונית הצדדית של התוסף. אפשר להפעיל את הפונקציה הזו רק בתגובה לפעולה של משתמש.

פרמטרים

• אפשרויות

  OpenOptions

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

החזרות

• Promise<void>

  הפונקציה מחזירה Promise שמתבצע כשהחלונית הצדדית נפתחת.

setOptions()

browser.sidePanel.setOptions(
  options: PanelOptions,
): Promise<void>

מגדירה את החלונית הצדדית.

פרמטרים

• אפשרויות

  PanelOptions

  אפשרויות ההגדרה שרוצים להחיל על החלונית.

החזרות

• Promise<void>

  הפונקציה מחזירה Promise שמתבצעת כשהאפשרויות מוגדרות.

setPanelBehavior()

browser.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
): Promise<void>

ההגדרה קובעת את אופן הפעולה של חלונית הצד של התוסף. זו פעולת עדכון או הוספה (upsert).

פרמטרים

• צרכנים

  PanelBehavior

  ההתנהגות החדשה שרוצים להגדיר.

החזרות

• Promise<void>

  הפונקציה מחזירה Promise שמתבצע כשההתנהגות החדשה מוגדרת.

אירועים

onClosed

‫Chrome 142 ואילך ‫browser.* ‎ מגרסה Chrome 148

browser.sidePanel.onClosed.addListener(
  callback: function,
)

מופעל כשחלונית הצד של התוסף נסגרת.

פרמטרים

• callback

  פונקציה

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

  (info: PanelClosedInfo) => void

  • מידע

    PanelClosedInfo

onOpened

‫Chrome 141 ואילך ‫‎browser.* ‎ מגרסה Chrome 148

browser.sidePanel.onOpened.addListener(
  callback: function,
)

מופעל כשפותחים את החלונית הצדדית של התוסף.

פרמטרים

• callback

  פונקציה

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

  (info: PanelOpenedInfo) => void

  • מידע

    PanelOpenedInfo