browser.sidePanel

תיאור

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

הרשאות

sidePanel

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

manifest.json:

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

זמינות

‫Chrome 114 ואילך ‫MV3 ואילך

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

ה-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(). היא מאפשרת לתוספים לפתוח את חלונית הצדדית באמצעות תנועה של המשתמש בתוסף, כמו לחיצה על סמל הפעולה. או אינטראקציה של משתמש בדף של תוסף או בסקריפט תוכן, כמו לחיצה על לחצן. לצפייה בהדגמה מלאה, אפשר לעיין בתוסף לדוגמה Open Side Panel.

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

הקוד המלא מופיע בדוגמה Multiple side panels.

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

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

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

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

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

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

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

דוגמאות

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

סוגים

CloseOptions

‫Chrome 141+‎

מאפיינים

  • tabId

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

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

  • windowId

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

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

GetPanelOptions

מאפיינים

  • tabId

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

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

OpenOptions

‫Chrome 116 ואילך

מאפיינים

  • tabId

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

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

  • windowId

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

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

PanelBehavior

מאפיינים

  • openPanelOnActionClick

    ‫boolean אופציונלי

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

PanelClosedInfo

‫Chrome 142 ואילך

מאפיינים

  • נתיב

    מחרוזת

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

  • tabId

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

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

  • windowId

    number

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

PanelLayout

‫Chrome 140+‎

מאפיינים

PanelOpenedInfo

‫Chrome 141+‎

מאפיינים

  • נתיב

    מחרוזת

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

  • tabId

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

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

  • windowId

    number

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

PanelOptions

מאפיינים

  • פעיל

    ‫boolean אופציונלי

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

  • נתיב

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

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

  • tabId

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

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

Side

‫Chrome 140+‎

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

ספירה

"left"

"right"

SidePanel

מאפיינים

  • default_path

    מחרוזת

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

Methods

close()

‫Chrome 141+‎ 
chrome.sidePanel.close(
  options: CloseOptions,
): Promise<void>

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

פרמטרים

  • options

    CloseOptions

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

החזרות

  • Promise<void>

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

getLayout()

‫Chrome 140+‎ 
chrome.sidePanel.getLayout(): Promise<PanelLayout>

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

החזרות

getOptions()

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

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

פרמטרים

  • options

    GetPanelOptions

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

החזרות

  • Promise<PanelOptions>

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

getPanelBehavior()

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

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

החזרות

  • Promise<PanelBehavior>

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

open()

‫Chrome 116 ואילך 
chrome.sidePanel.open(
  options: OpenOptions,
): Promise<void>

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

פרמטרים

  • options

    OpenOptions

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

החזרות

  • Promise<void>

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

setOptions()

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

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

פרמטרים

  • options

    PanelOptions

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

החזרות

  • Promise<void>

    מחזירה Promise שמושלם כשהאפשרויות מוגדרות.

setPanelBehavior()

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

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

פרמטרים

  • צרכנים

    PanelBehavior

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

החזרות

  • Promise<void>

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

אירועים

onClosed

‫Chrome 142 ואילך 
chrome.sidePanel.onClosed.addListener(
  callback: function,
)

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

פרמטרים

onOpened

‫Chrome 141+‎ 
chrome.sidePanel.onOpened.addListener(
  callback: function,
)

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

פרמטרים