chrome.userScripts

الوصف

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

الأذونات

userScripts

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

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

مدى التوفّر

الإصدار 120 من Chrome والإصدارات الأحدث الإصدار 3 من MV والإصدارات الأحدث

المفاهيم وطريقة الاستخدام

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

وضع المطوِّر لمستخدمي الإضافات

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

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

  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 في عامل خدمة إضافة Chrome. لا تستجِب إلا "update" للسبب الذي تم تمريره إلى دالة الاستدعاء للحدث.

مثال

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

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

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

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

الأنواع

ExecutionWorld

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

تعداد

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

‫"USER_SCRIPT"
تُحدِّد بيئة التنفيذ الخاصة بنصوص المستخدم البرمجية وتُستثنى من "سياسة حماية المحتوى في الصفحة".

RegisteredUserScript

الخصائص

  • allFrames

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

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

  • excludeGlobs

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

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

  • excludeMatches

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

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

  • id

    سلسلة

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

  • includeGlobs

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

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

  • js

    ScriptSource[] اختياري

    قائمة عناصر ScriptSource التي تحدّد مصادر النصوص البرمجية التي سيتم إدراجها في الصفحات المطابقة يجب تحديد هذه السمة لدالة ${ref:register}، ويجب أن تكون صفيفًا غير فارغ عند تحديدها.

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

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

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

  • runAt

    ‫RunAt اختيارية

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

  • العالم

    ExecutionWorld اختياري

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

  • worldId

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

    في انتظار المراجعة

    إذا تم تحديده، يحدّد معرّفًا عالميًا محدّدًا لنص برمجي خاص بالمستخدم لتنفيذه. لا يكون هذا الحقل صالحًا إلا إذا تم حذف world أو إذا كانت قيمته USER_SCRIPT. في حال حذفها، سيتم تنفيذ النص البرمجي في بيئة النص البرمجي التلقائية للمستخدم. إنّ القيم التي تحتوي على شرط سفلية (_) في البداية محجوزة.

ScriptSource

الخصائص

  • رمز

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

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

  • ملف

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

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

UserScriptFilter

الخصائص

  • ids

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

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

WorldProperties

الخصائص

  • csp

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

    تُحدِّد خدمة إدارة المحتوى الآمن (CSP) على مستوى العالم. الإعداد التلقائي هو خدمة إدارة الخدمات في `ISOLATED`.

  • المراسلة

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

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

  • worldId

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

    في انتظار المراجعة

    تُحدِّد معرّف عالم نص برمجي محدّد للمستخدم المطلوب تعديله. في حال عدم توفيرها، يتم تعديل سمات عالم نص برمجي المستخدم التلقائي. إنّ القيم التي تحتوي على شرط سفلية (_) في البداية محجوزة.

الطُرق

configureWorld()

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

لضبط بيئة تنفيذ `USER_SCRIPT`

المعلمات

  • المواقع

    WorldProperties

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

  • ردّ الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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

getScripts()

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

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

المعلمات

  • تصفية

    ‫UserScriptFilter اختيارية

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

  • ردّ الاتصال

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

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

    (scripts: RegisteredUserScript[]) => void

المرتجعات

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

getWorldConfigurations()

الوعد في انتظار المراجعة
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

يستردّ جميع إعدادات العالم المسجّلة.

المعلمات

  • ردّ الاتصال

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

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

    (worlds: WorldProperties[]) => void

المرتجعات

  • Promise<WorldProperties[]>

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

register()

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

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

المعلمات

  • نصوص برمجية

    RegisteredUserScript[]

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

  • ردّ الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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

resetWorldConfiguration()

الوعد في انتظار المراجعة
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

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

المعلمات

  • worldId

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

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

  • ردّ الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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

unregister()

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

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

المعلمات

  • تصفية

    ‫UserScriptFilter اختيارية

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

  • ردّ الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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

update()

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

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

المعلمات

  • نصوص برمجية

    RegisteredUserScript[]

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

  • ردّ الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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