chrome.sidePanel

תיאור

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

הרשאות

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() כדי להפעיל חלונית צדדית בכרטיסייה ספציפית. בדוגמה הזו נעשה שימוש ב-chrome.tabs.onUpdated() כדי להאזין לעדכונים בכרטיסייה. הוא בודק אם כתובת ה-URL היא www.google.com ומפעילים את החלונית הצדדית. אחרת, הוא יושבת.

service-worker.js:

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

chrome.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 chrome.sidePanel.setOptions({
      tabId,
      path: 'sidepanel.html',
      enabled: true
    });
  } else {
    // Disables the side panel on all other sites
    await chrome.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
chrome.sidePanel
  .setPanelBehavior({ openPanelOnActionClick: true })
  .catch((error) => console.error(error));
...

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

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

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

service-worker.js:

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

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

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

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

service-worker.js:

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

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

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

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

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

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

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

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

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

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

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

דוגמאות

להדגמות נוספות של תוספי Side Panel API, כדאי לנסות כל אחד מהתוספים הבאים:

סוגים

GetPanelOptions

מאפיינים

  • tabId

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

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

OpenOptions

Chrome 116 ואילך

מאפיינים

  • tabId

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

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

  • windowId

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

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

PanelBehavior

מאפיינים

  • openPanelOnActionClick

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

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

PanelOptions

מאפיינים

  • פעיל

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

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

  • נתיב

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

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

  • tabId

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

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

SidePanel

מאפיינים

  • default_path

    מחרוזת

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

שיטות

getOptions()

הבטחה 
chrome.sidePanel.getOptions(
  options: GetPanelOptions,
  callback?: function,
)

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

פרמטרים

  • אפשרויות

    GetPanelOptions

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

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

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

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

    (options: PanelOptions) => void

החזרות

  • Promise&lt;PanelOptions&gt;

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

getPanelBehavior()

הבטחה 
chrome.sidePanel.getPanelBehavior(
  callback?: function,
)

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

פרמטרים

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

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

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

    (behavior: PanelBehavior) => void

החזרות

  • Promise&lt;PanelBehavior&gt;

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

open()

הבטחה Chrome 116 ואילך 
chrome.sidePanel.open(
  options: OpenOptions,
  callback?: function,
)

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

פרמטרים

  • אפשרויות

    OpenOptions

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

setOptions()

הבטחה 
chrome.sidePanel.setOptions(
  options: PanelOptions,
  callback?: function,
)

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

פרמטרים

  • אפשרויות

    PanelOptions

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

setPanelBehavior()

הבטחה 
chrome.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
  callback?: function,
)

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

פרמטרים

  • צרכנים

    PanelBehavior

    ההתנהגות החדשה שתיקבע.

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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