דף זה תורגם על ידי Cloud Translation API.

chrome.sidePanel

תיאור

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

הרשאות

sidePanel

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

manifest.json:

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

זמינות

Chrome 114 ומעלה 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() כדי להפעיל חלונית צדדית בכרטיסייה ספציפית. בדוגמה הזו נעשה שימוש ב-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.tabs.onActivated.addListener(async ({ tabId }) => {
  const { path } = await chrome.sidePanel.getOptions({ tabId });
  if (path === welcomePage) {
    chrome.sidePanel.setOptions({ path: mainPage });
  }
});

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

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

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

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

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

פתיחה באמצעות תנועת משתמש

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

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

דוגמאות

להדגמות נוספות של תוספי 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
```
- אפשרויות
  
  PanelOptions

החזרות

Promise<PanelOptions>

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

getPanelBehavior()

הבטחה

chrome.sidePanel.getPanelBehavior(
  callback?: function,
)

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

פרמטרים

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

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

הפרמטר callback נראה כך:
```
(behavior: PanelBehavior)=>void
```
- צרכנים
  
  PanelBehavior

החזרות

Promise<PanelBehavior>

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

open()

Promise Chrome 116 ואילך

chrome.sidePanel.open(
  options: OpenOptions,
  callback?: function,
)

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

פרמטרים

אפשרויות

OpenOptions

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

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

הפרמטר callback נראה כך:
```
()=>void
```

החזרות

Promise<void>

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

setOptions()

הבטחה

chrome.sidePanel.setOptions(
  options: PanelOptions,
  callback?: function,
)

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

פרמטרים

אפשרויות

PanelOptions

אפשרויות ההגדרה שצריך להחיל על הלוח.
קריאה חוזרת (callback)

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

הפרמטר callback נראה כך:
```
()=>void
```

החזרות

Promise<void>

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

setPanelBehavior()

הבטחה

chrome.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
  callback?: function,
)

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

פרמטרים

צרכנים

PanelBehavior

ההתנהגות החדשה שתיקבע.
קריאה חוזרת (callback)

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

הפרמטר callback נראה כך:
```
()=>void
```

החזרות

Promise<void>

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