נותנים למשתמשים אפשרויות

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

איפה נמצא דף האפשרויות

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

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

כתיבת דף האפשרויות

דוגמה לדף אפשרויות:

options.html:

<!DOCTYPE html>
<html>
  <head>
    <title>My Test Extension Options</title>
  </head>
  <body>
    <select id="color">
      <option value="red">red</option>
      <option value="green">green</option>
      <option value="blue">blue</option>
      <option value="yellow">yellow</option>
    </select>

    <label>
      <input type="checkbox" id="like" />
      I like colors.
    </label>

    <div id="status"></div>
    <button id="save">Save</button>

    <script src="options.js"></script>
  </body>
</html>

בהמשך מופיע סקריפט לדוגמה של אפשרויות. שומרים אותו באותה תיקייה שבה נמצא options.html. הפעולה הזו שומרת את האפשרויות המועדפות של המשתמשים במכשירים שונים באמצעות storage.sync API.

options.js:

// Saves options to browser.storage
const saveOptions = () => {
  const color = document.getElementById('color').value;
  const likesColor = document.getElementById('like').checked;

  browser.storage.sync.set(
    { favoriteColor: color, likesColor: likesColor },
    () => {
      // Update status to let user know options were saved.
      const status = document.getElementById('status');
      status.textContent = 'Options saved.';
      setTimeout(() => {
        status.textContent = '';
      }, 750);
    }
  );
};

// Restores select box and checkbox state using the preferences
// stored in browser.storage.
const restoreOptions = () => {
  browser.storage.sync.get(
    { favoriteColor: 'red', likesColor: true },
    (items) => {
      document.getElementById('color').value = items.favoriteColor;
      document.getElementById('like').checked = items.likesColor;
    }
  );
};

document.addEventListener('DOMContentLoaded', restoreOptions);
document.getElementById('save').addEventListener('click', saveOptions);

בסוף, מוסיפים את ההרשאה "storage" לקובץ manifest של התוסף:

manifest.json:

{
  "name": "My extension",
  ...
  "permissions": [
    "storage"
  ]
  ...
}

הצהרה על התנהגות דף האפשרויות

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

אפשרויות של דף מלא

דף האפשרויות full page מוצג בכרטיסייה חדשה. רושמים את קובץ ה-HTML של האפשרויות במניפסט בשדה "options_page".

manifest.json:

{
  "name": "My extension",
  ...
  "options_page": "options.html",
  ...
}
אפשרויות של דף מלא
אפשרויות של דף מלא בכרטיסייה חדשה.

אפשרויות להטמעה

דף אפשרויות מוטמעות מאפשר למשתמשים לשנות את האפשרויות של התוסף בלי לצאת מדף ניהול התוספים בתוך תיבה מוטמעת. כדי להצהיר על אפשרויות מוטמעות, צריך לרשום את קובץ ה-HTML בשדה "options_ui" במניפסט של התוסף, ולהגדיר את המפתח "open_in_tab" לערך false.

manifest.json:

{
  "name": "My extension",
  ...
  "options_ui": {
    "page": "options.html",
    "open_in_tab": false
  },
  ...
}
אפשרויות להטמעה
אפשרויות מוטמעות.
‫page (מחרוזת)
מציין את הנתיב לדף האפשרויות, ביחס לשורש של התוסף.
open_in_tab (boolean)
ההגדרה קובעת אם דף האפשרויות של התוסף ייפתח בכרטיסייה חדשה. אם המדיניות מוגדרת כ-false, דף האפשרויות של התוסף מוטמע ב-chrome://extensions במקום להיפתח בכרטיסייה חדשה.

התחשבות בהבדלים

יש הבדלים קלים בהתנהגות של דפי אפשרויות שמוטמעים בתוך chrome://extensions לעומת דפי אפשרויות בכרטיסיות.

קישור לדף האפשרויות

תוסף יכול לקשר ישירות לדף האפשרויות על ידי קריאה ל-browser.runtime.openOptionsPage(). לדוגמה, אפשר להוסיף אותו לחלון קופץ:

popup.html:

<button id="go-to-options">Go to options</button>
<script src="popup.js"></script>

popup.js:

document.querySelector('#go-to-options').addEventListener('click', function() {
  if (browser.runtime.openOptionsPage) {
    browser.runtime.openOptionsPage();
  } else {
    window.open(browser.runtime.getURL('options.html'));
  }
});

Tabs API

מכיוון שקוד האפשרויות המוטמע לא מתארח בכרטיסייה, אי אפשר להשתמש ב-Tabs API. במקום זאת, משתמשים ב-runtime.connect() וב-runtime.sendMessage(), אם דף האפשרויות צריך לשנות את הכרטיסייה שמכילה אותו.

Messaging APIs

אם דף האפשרויות של תוסף שולח הודעה באמצעות runtime.connect() או runtime.sendMessage(), הכרטיסייה של השולח לא תוגדר, וכתובת ה-URL של השולח תהיה כתובת ה-URL של דף האפשרויות.

התאמת גודל

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

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