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

اسمح للمستخدمين بتخصيص سلوك الإضافة من خلال توفير صفحة خيارات. يمكن للمستخدم عرض خيارات الإضافات من خلال النقر بزر الماوس الأيمن على رمز الإضافة في شريط الأدوات ثم تحديد الخيارات أو من خلال الانتقال إلى صفحة إدارة الإضافات على 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.

// 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);

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

يتوفر نوعان من صفحات خيارات الإضافات، هما صفحة كاملة ومضمّنة. يتم تحديد نوع الخيارات من خلال كيفية تعريفها في البيان.

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

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

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

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

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

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

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

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

  • page (سلسلة)

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

  • open_in_tab (boolean)

    حدِّد القيمة 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.query أبدًا على علامة تبويب ضمن عنوان URL لصفحة خيارات الإضافة.
  • لن يتم تنشيط tabs.onCreated عند فتح صفحة الخيارات.
  • لن يتم تنشيط tabs.onUpdated عند تغيير حالة تحميل صفحة الخيارات.
  • لا يمكن استخدام tabs.connect أو tabs.sendMessage للاتصال بصفحة الخيارات.

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

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

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

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

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

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