chrome.userScripts

الوصف

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

الأذونات

userScripts

لاستخدام واجهة برمجة التطبيقات chrome.userScripts، عليك إضافة الإذن "userScripts" إلى ملف البيان.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. بالنسبة إلى إضافات النصوص البرمجية للمستخدم، على المستخدمين أيضًا تفعيل وضع مطوّر البرامج. في ما يلي التعليمات التي يمكنك نسخها ولصقها في مستنداتك الخاصة.

  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 في مشغّل خدمات الإضافات. الردّ فقط على السبب "update" الذي تم تمريره إلى معاودة الاتصال بالحدث

مثال

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

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

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

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

الأنواع

ExecutionWorld

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

التعداد

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

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

RegisteredUserScript

أماكن إقامة

  • allFrames

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

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

  • excludeGlobs

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

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

  • excludeMatches

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

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

  • id

    سلسلة

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

  • includeGlobs

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

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

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

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

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

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

  • runAt

    RunAt اختيارية

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

  • العالم

    ExecutionWorld اختياري

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

ScriptSource

أماكن إقامة

  • رمز

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

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

  • ملف

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

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

UserScriptFilter

أماكن إقامة

  • ids

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

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

WorldProperties

أماكن إقامة

  • خدمات مقارنة الأسعار

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

    تحدِّد هذه السياسة سياسة csp العالمية. يكون الإعداد التلقائي هو سياسة csp العالمية `ISOLATED`.

  • المراسلة

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

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

الطُرق

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

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

المَعلمات

  • filter

    UserScriptFilter اختياري

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

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

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

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

    (scripts: RegisteredUserScript[])=>void

المرتجعات

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

register()

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

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

المَعلمات

  • نصوص برمجية

    RegisteredUserScript[]

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

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

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

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

    ()=>void

المرتجعات

  • Promise<void>

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

unregister()

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

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

المَعلمات

  • filter

    UserScriptFilter اختياري

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

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

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

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

    ()=>void

المرتجعات

  • Promise<void>

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

update()

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

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

المَعلمات

  • نصوص برمجية

    RegisteredUserScript[]

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

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

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

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

    ()=>void

المرتجعات

  • Promise<void>

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