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"
تُحدِّد بيئة التنفيذ الخاصة بنصوص المستخدم البرمجية وتُستثنى من "سياسة حماية المحتوى في الصفحة".

InjectionResult

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

الخصائص

  • documentId

    سلسلة

    المستند المرتبط بالحقنة

  • خطأ

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

    الخطأ، إن وُجد لا يمكن استخدام error وresult معًا.

  • frameId

    الرقم

    الإطار المرتبط بالحقنة

  • نتيجة

    أيّ اختيارية

    نتيجة تنفيذ النص البرمجي

InjectionTarget

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

الخصائص

  • allFrames

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

    ما إذا كان يجب إدراج النص البرمجي في جميع الإطارات ضمن علامة التبويب القيمة التلقائية هي false. يجب ألا يكون هذا صحيحًا إذا تم تحديد frameIds.

  • documentIds

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

    أرقام تعريف مستندات معيّنة لإدراجها يجب عدم ضبط هذه القيمة إذا تم ضبط frameIds.

  • frameIds

    عدد اختياري

    معرّفات اللقطات المحدّدة التي تريد إدراجها

  • tabId

    الرقم

    رقم تعريف علامة التبويب التي سيتمّ إدراجها فيها.

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 سوى النصوص البرمجية التي تحتوي على المعرّفات المحدّدة في هذه القائمة.

UserScriptInjection

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

الخصائص

  • injectImmediately

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

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

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

  • الاستهداف

    تفاصيل تحدّد الهدف الذي سيتمّ إدخال النصّ البرمجي فيه

  • العالم

    ExecutionWorld اختياري

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

  • worldId

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

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

WorldProperties

الخصائص

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

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

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

  • المراسلة

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

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

  • worldId

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

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

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

الطُرق

configureWorld()

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

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

المعلمات

  • المواقع

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

execute()

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

يتيح هذا الإذن إدخال نص برمجي في سياق مستهدَف. سيتم تشغيل النص البرمجي تلقائيًا في document_idle، أو على الفور إذا سبق أن تم تحميل الصفحة. في حال ضبط السمة injectImmediately، سيتمّ إدراج النص البرمجي بدون انتظار، حتى إذا لم ينتهِ تحميل الصفحة. إذا تم تقييم النص البرمجي على أنّه وعد، سينتظر المتصفّح استقرار الوعد وعرض القيمة الناتجة.

المعلمات

المرتجعات

  • Promise<InjectionResult[]>

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

getScripts()

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

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

المعلمات

  • تصفية

    UserScriptFilter اختيارية

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

  • callback

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

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

    (scripts: RegisteredUserScript[]) => void

المرتجعات

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

getWorldConfigurations()

الوعد الإصدار 133 من Chrome والإصدارات الأحدث
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

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

المعلمات

  • callback

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

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

    (worlds: WorldProperties[]) => void

المرتجعات

  • Promise<WorldProperties[]>

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

register()

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

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

المعلمات

  • نصوص برمجية

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

  • 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,
)

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

المعلمات

  • نصوص برمجية

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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