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

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

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

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

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

דוגמאות

כדי לראות עוד הדגמות של תוספים ל-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+‎

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

Enum

"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,
)

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

פרמטרים