chrome.userScripts

الوصف

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

الأذونات

userScripts

لاستخدام User Scripts API، 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/*"
  ]
}

مدى التوفّر

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

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

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

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

بصفتك مطوّر إضافات، يكون وضع المطوّر مفعّلاً في تثبيت 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 التي سيتم تنفيذ نص برمجي للمستخدم فيها

Enum

‫"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

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

  الإصدار 133 من Chrome والإصدارات الأحدث

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

ScriptSource

الخصائص

• رمز

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

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

• ملف

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

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

UserScriptFilter

الخصائص

• ids

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

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

WorldProperties

الخصائص

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

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

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

• المراسلة

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

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

• worldId

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

  الإصدار 133 من Chrome والإصدارات الأحدث

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

الطُرق

configureWorld()

الوعد

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

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

المعلمات

• المواقع

  WorldProperties

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

• callback

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

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

  () => void

المرتجعات

• Promise<void>

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

getScripts()

الوعد

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

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

المعلمات

• تصفية

  ‫UserScriptFilter اختيارية

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

• callback

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

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

  (scripts: RegisteredUserScript[]) => void

  • نصوص برمجية

    RegisteredUserScript[]

المرتجعات

• Promise<RegisteredUserScript[]>

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

getWorldConfigurations()

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

chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

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

المعلمات

• callback

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

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

  (worlds: WorldProperties[]) => void

  • العوالم

    WorldProperties[]

المرتجعات

• Promise<WorldProperties[]>

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

register()

الوعد

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

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

المعلمات

• نصوص برمجية

  RegisteredUserScript[]

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

• callback

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

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

  () => void

المرتجعات

• Promise<void>

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

resetWorldConfiguration()

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

chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

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

المعلمات

• worldId

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

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

• callback

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

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

  () => void

المرتجعات

• Promise<void>

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

unregister()

الوعد

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

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

المعلمات

• تصفية

  ‫UserScriptFilter اختيارية

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

• callback

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

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

  () => void

المرتجعات

• Promise<void>

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

update()

الوعد

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

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

المعلمات

• نصوص برمجية

  RegisteredUserScript[]

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

• callback

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

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

  () => void

المرتجعات

• Promise<void>

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