chrome.types

الوصف

تحتوي واجهة برمجة التطبيقات chrome.types API على أنواع تعريف الأنواع لمتصفِّح Chrome.

إعدادات Chrome

يوفّر النوع ChromeSetting مجموعة مشتركة من الدوال (get() وset() وclear()) بالإضافة إلى ناشر أحداث (onChange) لإعدادات متصفّح Chrome. توضح أمثلة إعدادات الخادم الوكيل كيفية الغرض من استخدام هذه الدوال.

النطاق ودورة الحياة

يميّز Chrome بين ثلاثة نطاقات مختلفة لإعدادات المتصفّح:

regular
تسري الإعدادات التي يتم ضبطها في نطاق regular على نوافذ المتصفِّح العادية، وتكتسبها نوافذ التصفُّح المتخفي إذا لم يتم استبدالها. يتم تخزين هذه الإعدادات على القرص وتبقى في مكانها إلى أن يتم محوها من خلال الإضافة الحاكمة أو يتم إيقاف الإضافة الحاكمة أو إلغاء تثبيتها.
incognito_persistent
لا تنطبق الإعدادات التي يتم ضبطها في نطاق incognito_persistent إلا على نوافذ التصفُّح المتخفي. بالنسبة إلى هذه النطاقات، يتم تجاوز إعدادات regular. يتم تخزين هذه الإعدادات على القرص وتظل في مكانها حتى يتم محوها من خلال الإضافة الحاكمة أو يتم إيقاف الإضافة الحاكمة أو إلغاء تثبيتها.
incognito_session_only
لا تنطبق الإعدادات التي يتم ضبطها في نطاق incognito_session_only إلا على نوافذ التصفُّح المتخفي. بالنسبة إلى هذه النطاقات، يتم إلغاء إعدادات regular وincognito_persistent. ولا يتم تخزين هذه الإعدادات على القرص ويتم محوها عند إغلاق آخر نافذة للتصفح المتخفي. لا يمكن ضبطها إلا عند فتح نافذة تصفّح متخفٍ واحدة على الأقل.

الأولوية

يدير Chrome الإعدادات في طبقات مختلفة. تصف القائمة التالية الطبقات التي قد تؤثر في الإعدادات الفعالة، بترتيب متزايد من الأسبقية.

  1. إعدادات النظام التي يوفرها نظام التشغيل
  2. مَعلمات سطر الأوامر
  3. الإعدادات التي توفّرها الإضافات
  4. السياسات

كما تشير القائمة، قد تلغي السياسات أي تغييرات تحدِّدها باستخدام الإضافة. يمكنك استخدام الدالة get() لتحديد ما إذا كانت الإضافة قادرة على توفير إعداد أو ما إذا كان سيتم تجاوز هذا الإعداد.

كما ذكرنا سابقًا، يسمح Chrome باستخدام إعدادات مختلفة للنوافذ العادية ونوافذ التصفح المتخفي. يوضِّح المثال التالي السلوك. افترِض أنّه لا تتوفّر أي سياسة تلغي الإعدادات، وأنّ الإضافة يمكنها ضبط الإعدادات للنوافذ العادية (R) وإعدادات نوافذ التصفّح المتخفي (I).

  • وفي حال ضبط (R) فقط، تكون هذه الإعدادات سارية لكل من النوافذ العادية ونافذة التصفُّح المتخفي.
  • وفي حال ضبط علامة (I) فقط، تكون هذه الإعدادات سارية في نوافذ التصفُّح المتخفي فقط. تستخدم النوافذ العادية الإعدادات التي تحددها الطبقات السفلية (خيارات سطر الأوامر وإعدادات النظام).
  • في حال ضبط كل من (R) و(I)، يتم استخدام الإعدادات الخاصة بكل من النوافذ العادية ونوافذ التصفّح المتخفي.

إذا أرادت إضافتان أو أكثر ضبط الإعداد نفسه على قيم مختلفة، ستكون للإضافة المثبّتة مؤخرًا الأولوية على الإضافات الأخرى. إذا كانت آخر إضافة مثبَّتة ضبطت (I) فقط، يمكن تحديد إعدادات النوافذ العادية من خلال الإضافات التي سبق تثبيتها.

وتكون القيمة الفعالة لأحد الإعدادات هي القيمة التي تنتج عن مراعاة قواعد الأولوية. ويتم استخدامه من قبل Chrome.

الأنواع

ChromeSetting

واجهة تسمح بالوصول إلى أحد إعدادات متصفّح Chrome. راجِع accessibilityFeatures للاطّلاع على مثال.

أماكن إقامة

  • onChange

    الحدث<functionvitvit>

    يتم تنشيطها بعد تغيير الإعداد.

    تبدو الدالة onChange.addListener على النحو التالي: 

    (callback: function)=> {...}

    • معاودة الاتصال

      الوظيفة

      تبدو معلَمة callback على النحو التالي: 

      (details: object)=>void

      • التفاصيل

        كائن

        • incognitoSpecific

          منطقية اختيارية

          ما إذا كانت القيمة التي تم تغييرها خاصة بجلسة التصفُّح المتخفي. لن يظهر هذا الموقع إلا إذا فعَّل المستخدم الإضافة في وضع التصفُّح المتخفي.

        • levelOfControl

          LevelOfControl

          مستوى التحكّم في الإعداد

        • القيمة

          T

          قيمة الإعداد بعد التغيير.

  • محو

    void

    وعد

    يؤدي إلى محو الإعداد واستعادة أي قيمة تلقائية.

    تبدو الدالة clear على النحو التالي: 

    (details: object,callback?: function)=> {...}

    • التفاصيل

      كائن

      الإعداد الذي تريد محوه.

      • نطاق

        ChromeSettingScope اختياري

        الموضع المطلوب لمحوه (الإعداد التلقائي: عادي)

    • معاودة الاتصال

      الدالة اختيارية

      تبدو معلَمة callback على النحو التالي: 

      ()=>void

    • returns

      Promise<void>

      Chrome 96 والإصدارات الأحدث

      تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

  • الحصول على

    void

    وعد

    للحصول على قيمة الإعداد.

    تبدو الدالة get على النحو التالي: 

    (details: object,callback?: function)=> {...}

    • التفاصيل

      كائن

      الإعداد الذي يجب مراعاته.

      • وضع التصفّح المتخفي

        منطقية اختيارية

        ما إذا كان سيتم عرض القيمة التي تنطبق على جلسة التصفُّح المتخفي (خطأ تلقائي، القيمة التي تنطبق على جلسة التصفُّح المتخفي).

    • معاودة الاتصال

      الدالة اختيارية

      تبدو معلَمة callback على النحو التالي: 

      (details: object)=>void

      • التفاصيل

        كائن

        تفاصيل القيمة السارية حاليًا.

        • incognitoSpecific

          منطقية اختيارية

          ما إذا كانت القيمة الفعالة خاصة بجلسة التصفُّح المتخفي. لن يتوفّر هذا الموقع إلا إذا كانت السمة incognito في المَعلمة details للسمة get() صحيحة.

        • levelOfControl

          LevelOfControl

          مستوى التحكّم في الإعداد

        • القيمة

          T

          قيمة الإعداد.

    • returns

      Promise<object>

      Chrome 96 والإصدارات الأحدث

      تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

  • ضبط

    void

    وعد

    لتحديد قيمة أحد الإعدادات

    تبدو الدالة set على النحو التالي: 

    (details: object,callback?: function)=> {...}

    • التفاصيل

      كائن

      الإعداد الذي تريد تغييره.

      • نطاق

        ChromeSettingScope اختياري

        مكان ضبط الإعداد (التلقائي: عادي)

      • القيمة

        T

        قيمة الإعداد. يُرجى ملاحظة أنّ كل إعداد له نوع قيمة معيّن، ويتم وصفه مع الإعداد. ويجب ألا تضبط الإضافة قيمة من نوع مختلف.

    • معاودة الاتصال

      الدالة اختيارية

      تبدو معلَمة callback على النحو التالي: 

      ()=>void

    • returns

      Promise<void>

      Chrome 96 والإصدارات الأحدث

      تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

ChromeSettingScope

Chrome 44 والإصدارات الأحدث

نطاق Chromeإعداد واحد من

  • regular: إعداد للملف الشخصي العادي (الذي يكتسبه الملف الشخصي في وضع التصفّح المتخفي إذا لم يتم إلغاؤه في مكان آخر)
  • regular\_only: إعداد للملف الشخصي العادي فقط (غير موروث من الملف الشخصي في وضع التصفح المتخفي)
  • incognito\_persistent: إعداد للملف الشخصي في وضع التصفّح المتخفي الذي يستمر في إعادة تشغيل المتصفّح (يلغي الإعدادات المفضّلة العادية)،
  • incognito\_session\_only: إعداد للملف الشخصي في وضع التصفّح المتخفي الذي لا يمكن ضبطه إلا أثناء جلسة في وضع التصفّح المتخفي، ويتم حذفه عند انتهاء جلسة التصفّح المتخفي (يتم تجاوز الإعدادات المفضّلة العادية والتفضيلات المستمرة)

التعداد

"regular_only"

LevelOfControl

Chrome 44 والإصدارات الأحدث

واحد من

  • not\_controllable: لا يمكن التحكّم فيه من خلال أي إضافة
  • controlled\_by\_other\_extensions: يتم التحكّم فيه من خلال إضافات ذات أولوية أعلى.
  • controllable\_by\_this\_extension: يمكن التحكم فيه من خلال هذه الإضافة
  • controlled\_by\_this\_extension: يتم التحكم فيه من خلال هذه الإضافة

التعداد

"not_controllable"

"controlled_by_other_extensions"

"controllable_by_this_extension"

"controlled_by_this_extension"