chrome.userScripts

الوصف

استخدِم واجهة برمجة التطبيقات userScripts لتنفيذ النصوص البرمجية للمستخدم في سياق النصوص البرمجية للمستخدم.

الأذونات

userScripts

لاستخدام واجهة برمجة التطبيقات chrome.userScripts، أضِف الإذن "userScripts" إلى ملف sitemap.json و"host_permissions" للمواقع الإلكترونية التي تريد تنفيذ نصوص برمجية عليها.

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

مدى التوفّر

الإصدار 120 من Chrome أو الإصدارات الأحدث MV3+

المفاهيم والاستخدام

النص البرمجي للمستخدم هو جزء من رمز يتم إدخاله في صفحة ويب لتعديل مظهره أو سلوكه. يتم إنشاء النصوص البرمجية من قِبل المستخدمين، أو يتم تنزيلها من مستودع النصوص البرمجية أو إضافة النصوص البرمجية للمستخدم.

وضع مطور البرامج لمستخدمي الإضافات

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

  1. انتقِل إلى صفحة "الإضافات" من خلال إدخال chrome://extensions في علامة تبويب جديدة. (حسب تصميم chrome://، عناوين URL غير قابلة للربط.)

  2. فعّل وضع مطور البرامج من خلال النقر على مفتاح التبديل بجوار وضع مطور البرامج.

    صفحة "الإضافات"

    صفحة الإضافات (chrome://extensions)

يمكنك معرفة ما إذا كان "وضع مطوّر البرامج" مفعَّلاً من خلال التحقّق مما إذا كان chrome.userScripts يعرض رسالة خطأ. على سبيل المثال:

function isUserScriptsAvailable() {
  try {
    // Property access which throws if developer mode is not enabled.
    chrome.userScripts;
    return true;
  } catch {
    // Not available.
    return false;
  }
}

العمل في عوالم منعزلة

يمكن تشغيل النصوص البرمجية للمستخدم والمحتوى في عالم منعزل أو في العالم الرئيسي. العالم المعزول هو بيئة تنفيذ لا يمكن الوصول إليها من خلال صفحة مضيف أو إضافات أخرى. يتيح هذا للنص البرمجي للمستخدم تغيير بيئة JavaScript بدون التأثير في صفحة المضيف أو الإضافات الأخرى. النصوص البرمجية للمستخدم والمحتوى. وعلى العكس، لا تكون النصوص البرمجية للمستخدم (ونصوص المحتوى البرمجية) مرئية لصفحة المضيف أو نصوص المستخدم والمحتوى للإضافات الأخرى. يمكن الوصول إلى النصوص البرمجية التي يتم تشغيلها في العالم الرئيسي لاستضافة الصفحات والإضافات الأخرى، كما تكون مرئية لصفحات المضيف والإضافات الأخرى. لاختيار العالم، عليك استخدام "USER_SCRIPT" أو "MAIN" عند الاتصال userScripts.register().

لضبط سياسة أمان المحتوى للعالم USER_SCRIPT، اتصل بالرقم userScripts.configureWorld():

chrome.userScripts.configureWorld({
  csp: "script-src 'self'"
});

المراسلة

على غرار النصوص البرمجية للمحتوى والمستندات خارج الشاشة، تتواصل النصوص البرمجية للمستخدم مع أجزاء أخرى من الإضافة باستخدام ميزة المراسلة (أي يمكنهم استدعاء runtime.sendMessage() وruntime.connect() كما يفعل أي جزء آخر من الإضافة). وفي المقابل، يتم تلقّيها باستخدام معالِجات أحداث مخصّصة (أي أنّها لا تستخدم onMessage أو onConnect). يُطلق على هذه المعالجات اسمَي runtime.onUserScriptMessage وruntime.onUserScriptConnect. تسهّل المعالجات المخصصة تحديد الرسائل من النصوص البرمجية للمستخدم، والتي تعد سياقًا أقل موثوقية.

قبل إرسال رسالة، يجب الاتصال بـ configureWorld() مع ضبط الوسيطة messaging على true. تجدر الإشارة إلى أنّه يمكن تمرير كلٍّ من الوسيطات csp وmessaging في الوقت نفسه.

chrome.userScripts.configureWorld({
  messaging: true
});

تحديثات الإضافات

يتم محو النصوص البرمجية للمستخدم عند تحديث الإضافة. ويمكنك إضافتها مرة أخرى من خلال تنفيذ الرمز في معالِج أحداث runtime.onInstalled ضمن مشغّل خدمات الإضافات. عليك الردّ فقط على السبب "update" الذي تم تمريره إلى معاودة الاتصال بالحدث.

مثال

هذا المثال مأخوذ من نموذج userScript في مستودع النماذج لدينا.

تسجيل نص برمجي

يعرض المثال التالي طلبًا أساسيًا إلى register(). الوسيطة الأولى هي صفيف من كائنات تحدد النصوص البرمجية المراد تسجيلها. هناك خيارات أكثر مما هو معروض هنا.

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

الأنواع

ExecutionWorld

عالم JavaScript الذي يجب تنفيذ النص البرمجي للمستخدم بداخله.

Enum

"MAIN"
يحدد هذا الحقل بيئة تنفيذ نموذج العناصر في المستند (DOM)، وهي بيئة التنفيذ التي تتم مشاركتها مع JavaScript لصفحة المضيف.

"USER_script"
يحدد هذا الخيار بيئة التنفيذ الخاصة بالنصوص البرمجية للمستخدم والمُستثناة من سياسة أمان المحتوى (CSP) للصفحة.

RegisteredUserScript

أماكن إقامة

  • allFrames

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

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

  • excludeGlobs

    string[] اختيارية

    تحدِّد هذه السياسة أنماط أحرف البدل للصفحات التي لن يتم إدخال النص البرمجي للمستخدم فيها.

  • excludeMatches

    string[] اختيارية

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

  • id

    سلسلة

    رقم تعريف النص البرمجي للمستخدم المحدّد في طلب بيانات من واجهة برمجة التطبيقات. يجب ألا تبدأ هذه السمة بـ "_". لأنّه محجوز كبادئة لمعرّفات النصوص البرمجية التي تمّ إنشاؤها.

  • includeGlobs

    string[] اختيارية

    تُحدِّد أنماط أحرف البدل للصفحات التي سيتم إدخال النص البرمجي للمستخدم فيها.

  • JavaScript

    ScriptSource[]

    قائمة عناصر ScriptSource التي تحدّد مصادر النصوص البرمجية التي سيتم إدخالها في الصفحات المطابقة.

  • فلتر مطابق لـ

    string[] اختيارية

    تحدِّد هذه السياسة الصفحات التي سيتم إدخال النص البرمجي للمستخدم فيها. ويمكنك الاطّلاع على أنماط المطابقة للحصول على مزيد من التفاصيل حول بنية هذه السلاسل. يجب تحديد هذه السمة لـ ${ref:register}.

  • runAt

    RunAt اختياري

    تُحدِّد هذه السياسة وقت إدخال ملفات JavaScript في صفحة الويب. القيمة المفضّلة والتلقائية هي document_idle.

  • العالم

    ExecutionWorld اختياري.

    بيئة تنفيذ JavaScript المطلوب تشغيل النص البرمجي فيها والقيمة التلقائية هي `USER_SCRIPT`.

ScriptSource

أماكن إقامة

  • رمز

    سلسلة اختيارية

    سلسلة تحتوي على رمز JavaScript المطلوب إدخاله يجب تحديد سمة واحدة فقط من file أو code.

  • ملف

    سلسلة اختيارية

    مسار ملف JavaScript المطلوب إدخاله بالنسبة إلى الدليل الجذري للإضافة. يجب تحديد سمة واحدة فقط من file أو code.

UserScriptFilter

أماكن إقامة

  • أرقام التعريف

    string[] اختيارية

    لا تعرض getScripts إلا النصوص البرمجية التي تتضمن المعرّفات المحددة في هذه القائمة.

WorldProperties

أماكن إقامة

  • سياسة أمان المحتوى (CSP)

    سلسلة اختيارية

    تحدِّد هذه السياسة نظام سياسة توفير الطاقة (CPP) العالمي. والخيار التلقائي هو توفير بروتوكول أمان طبقة النقل لمخطّطات البيانات (csp) للعالم (`ISOLATED`).

  • المراسلة

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

    يحدِّد هذا الإعداد ما إذا كان سيتم الكشف عن واجهات برمجة تطبيقات المراسلة. والقيمة التلقائية هي false.

الطُرق

configureWorld()

وعود 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

تضبط هذه السياسة بيئة تنفيذ `USER_SCRIPT`.

المعلمات

  • المواقع

    WorldProperties

    يحتوي على إعدادات عالم النص البرمجي للمستخدم.

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

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

getScripts()

وعود 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

تعرض جميع النصوص البرمجية المسجّلة ديناميكيًا الخاصة بالمستخدم لهذه الإضافة.

المعلمات

  • تصفية

    UserScriptFilter اختياري

    في حال تحديد هذه الطريقة، يتم عرض النصوص البرمجية التي تطابقها فقط للمستخدم.

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (scripts: RegisteredUserScript[]) => void

المرتجعات

  • Promise&lt;RegisteredUserScript[]&gt;

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

register()

وعود 
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

المعلمات

  • نصوص برمجية

    RegisteredUserScript[]

    يحتوي على قائمة بالنصوص البرمجية للمستخدم المطلوب تسجيلها.

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

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

unregister()

وعود 
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

يؤدي إلى إلغاء تسجيل جميع النصوص البرمجية المسجّلة ديناميكيًا الخاصة بالمستخدم لهذه الإضافة.

المعلمات

  • تصفية

    UserScriptFilter اختياري

    في حالة تحديد هذه الطريقة، تلغي هذه الطريقة تسجيل النصوص البرمجية للمستخدم المطابقة لها فقط.

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

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

update()

وعود 
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

المعلمات

  • نصوص برمجية

    RegisteredUserScript[]

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

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

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