منح المستخدمين خيارات

يمكنك السماح للمستخدمين بتخصيص سلوك إضافة من خلال توفير صفحة خيارات. يمكن للمستخدم الاطّلاع على خيارات إضافة من خلال النقر بزر الماوس الأيمن على رمز الإضافة في شريط الأدوات ثم اختيار "خيارات" أو من خلال الانتقال إلى صفحة إدارة الإضافات على chrome://extensions، وتحديد الإضافة المطلوبة، والنقر على التفاصيل، ثم النقر على رابط الخيارات.

كتابة صفحة الخيارات

في ما يلي مثال على صفحة خيارات.

<!DOCTYPE html>
<html>
<head><title>My Test Extension Options</title></head>
<body>

Favorite color:
<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>

يمكنك حفظ الخيارات المفضّلة للمستخدم على جميع الأجهزة باستخدام storage.sync API.

// Saves options to chrome.storage
function save_options() {
  var color = document.getElementById('color').value;
  var likesColor = document.getElementById('like').checked;
  chrome.storage.sync.set({
    favoriteColor: color,
    likesColor: likesColor
  }, function() {
    // Update status to let user know options were saved.
    var status = document.getElementById('status');
    status.textContent = 'Options saved.';
    setTimeout(function() {
      status.textContent = '';
    }, 750);
  });
}

// Restores select box and checkbox state using the preferences
// stored in chrome.storage.
function restore_options() {
  // Use default value color = 'red' and likesColor = true.
  chrome.storage.sync.get({
    favoriteColor: 'red',
    likesColor: true
  }, function(items) {
    document.getElementById('color').value = items.favoriteColor;
    document.getElementById('like').checked = items.likesColor;
  });
}
document.addEventListener('DOMContentLoaded', restore_options);
document.getElementById('save').addEventListener('click',
    save_options);

تحديد سلوك صفحة الخيارات

يتوفّر نوعان من صفحات خيارات الإضافات، وهما صفحة كاملة وصفحة مضمّنة. يتم تحديد نوع الخيارات استنادًا إلى طريقة تعريفها في ملف manifest.

خيارات الصفحة الكاملة

سيتم عرض صفحة خيارات الإضافة في علامة تبويب جديدة. يتم إدراج ملف HTML للخيارات المسجَّل ضِمن حقل options_page.

{
  "name": "My extension",
  ...
  "options_page": "options.html",
  ...
}

خيارات الصفحة الكاملة

الخيارات المضمّنة

تسمح الخيارات المضمّنة للمستخدمين بتعديل خيارات الإضافة بدون الانتقال إلى صفحة إدارة الإضافات داخل مربّع مضمّن. لتعريف خيارات مضمّنة، عليك تسجيل ملف HTML ضِمن حقل options_ui في ملف manifest للإضافة، مع ضبط المفتاح open_in_tab على "false".

{
  "name": "My extension",
  ...
  "options_ui": {
    "page": "options.html",
    "open_in_tab": false
  },
  ...
}

الخيارات المضمّنة

  • page (سلسلة)

    مسار صفحة الخيارات، بالنسبة إلى جذر الإضافة.

  • open_in_tab (منطقي)

    يجب تحديد القيمة false لتعريف صفحة خيارات مضمّنة. إذا كانت القيمة true، سيتم فتح صفحة خيارات الإضافة في علامة تبويب جديدة بدلاً من تضمينها في chrome://extensions.

الاطّلاع على الاختلافات

تتضمّن صفحات الخيارات المضمّنة داخل chrome://extensions بعض الاختلافات الطفيفة في السلوك المرتبط بعدم استضافتها داخل علامات تبويب خاصة بها.

إدراج رابط إلى صفحة الخيارات

يمكن للإضافة إدراج رابط مباشر إلى صفحة الخيارات من خلال استدعاء chrome.runtime.openOptionsPage() .

<button id="go-to-options">Go to options</button>

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

‫Tabs API

لا تتم استضافة رمز صفحة الخيارات المضمّنة للإضافة داخل علامة تبويب، ما يؤثّر في طريقة استخدام Tabs API يمكن استخدامه:

  • tabs.query لن يعثر مطلقًا على علامة تبويب ضمن عنوان URL لصفحة خيارات الإضافة.
  • tabs.onCreated لن يتم تفعيله عند فتح صفحة الخيارات.
  • tabs.onUpdated لن يتم تفعيله عند تغيير حالة تحميل صفحة الخيارات.
  • tabs.connect أو tabs.sendMessage لا يمكن استخدامهما للتواصل مع صفحة الخيارات.

يُعدّ استخدام runtime.connect وruntime.sendMessage حلاً بديلاً لهذه القيود، إذا كانت صفحة الخيارات بحاجة إلى تعديل علامة التبويب التي تحتوي عليها.

واجهات برمجة تطبيقات المراسلة

إذا أرسلت صفحة خيارات الإضافة رسالة باستخدام runtime.connect أو runtime.sendMessage، لن يتم ضبط علامة تبويب المُرسِل، وسيكون عنوان URL للمُرسِل هو عنوان URL لصفحة الخيارات.

مقاسات الشعار

يجب أن تحدّد الخيارات المضمّنة حجمها تلقائيًا استنادًا إلى محتوى الصفحة. ومع ذلك، قد لا يعثر المربّع المضمّن على حجم مناسب لبعض أنواع المحتوى. تحدث هذه المشكلة غالبًا في صفحات الخيارات التي تعدّل شكل محتواها استنادًا إلى حجم النافذة.

إذا كانت هذه المشكلة تؤثر فيك، يمكنك توفير الحد الأدنى الثابت لأبعاد صفحة الخيارات لضمان العثور على حجم مناسب للصفحة المضمّنة.