chrome.userScripts (original) (raw)

الوصف

استخدِم واجهة برمجة التطبيقات 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 أو الإصدارات الأحدثالإصدار 3 أو الإصدارات الأحدث من Manifest

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

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

تفعيل استخدام واجهة برمجة التطبيقات userScripts

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

استخدِم عملية التحقّق التالية لتحديد زر التبديل الذي يجب أن يفعّله المستخدم، على سبيل المثال، أثناء تعريف المستخدم الجديد بالمنتج:

let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version >= 138) {
  // Allow User Scripts toggle will be used.
} else {
  // Developer mode toggle will be used.
}

توضّح الأقسام التالية مفاتيح التبديل المختلفة وكيفية تفعيلها.

إصدارات Chrome الأقدم من 138 (زر التبديل إلى وضع "مطوّر البرامج")

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

يمكنك نسخ التعليمات التالية ولصقها في مستندات الإضافة لتوفيرها للمستخدمين

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

الإصدار 138 من Chrome والإصدارات الأحدث (زر التبديل "السماح ببرامج المستخدم النصية")

يكون مفتاح التبديل السماح ببرامج المستخدمين مفعَّلاً في صفحة تفاصيل كل إضافة (على سبيل المثال، chrome://extensions/?id=YOUR_EXTENSION_ID).

يمكنك نسخ التعليمات التالية ولصقها في مستندات الإضافة لتوفيرها للمستخدمين:

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

زر التبديل "السماح بالنصوص البرمجية الخاصة بالمستخدم" (chrome://extensions/?id=abc...)

التحقّق من توفّر واجهة برمجة التطبيقات

ننصحك بإجراء عملية التحقّق التالية لتحديد ما إذا كانت واجهة برمجة التطبيقات userScripts مفعّلة، لأنّها تعمل في جميع إصدارات Chrome. يحاول هذا التحقّق طلب طريقة chrome.userScripts() التي من المفترض أن تنجح دائمًا عندما تكون واجهة برمجة التطبيقات متاحة. إذا أدى هذا الطلب إلى ظهور خطأ، يعني ذلك أنّ واجهة برمجة التطبيقات غير متاحة:

function isUserScriptsAvailable() {
  try {
    // Method call which throws if API permission or toggle is not enabled.
    chrome.userScripts.getScripts();
    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"
تحدّد بيئة التنفيذ الخاصة ببرامج المستخدم النصية والتي تكون معفاة من سياسة أمان المحتوى للصفحة.

InjectionResult

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

الخصائص

• المستند المرتبط بعملية الإدخال
• الخطأ، إن وُجد يستبعد كلّ من الحقلَين error وresult الآخر.
• الإطار المرتبط بعملية الإدخال
• نتيجة تنفيذ النص البرمجي

InjectionTarget

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

الخصائص

• allFrames
  boolean اختياري
  تحديد ما إذا كان يجب إدراج النص البرمجي في جميع الإطارات ضمن علامة التبويب القيمة التلقائية هي "خطأ". يجب ألا تكون هذه السمة صحيحة إذا تم تحديد frameIds.
• documentIds
  string[] اختياري
  معرّفات documentId المحدّدة التي سيتم إدراجها فيها. يجب عدم ضبط هذه السياسة في حال ضبط سياسة frameIds.
• frameIds
  number[] اختيارية
  معرّفات إطارات معيّنة سيتم إدراج الإعلانات فيها
• رقم تعريف علامة التبويب التي سيتم إدراج المحتوى فيها

RegisteredUserScript

الخصائص

• allFrames
  boolean اختياري
  إذا كانت القيمة صحيحة، سيتم إدخالها في جميع الإطارات، حتى إذا لم يكن الإطار هو الإطار الأعلى في علامة التبويب. يتم التحقّق من كل إطار بشكل مستقل للتأكّد من استيفاء متطلبات عنوان URL، ولن يتم إدراجه في الإطارات الفرعية إذا لم يتم استيفاء متطلبات عنوان URL. القيمة التلقائية هي "خطأ"، ما يعني أنّه يتم مطابقة الإطار العلوي فقط.
• excludeGlobs
  string[] اختياري
  تحدّد هذه السمة أنماط أحرف البدل للصفحات التي لن يتم إدراج نص برمجي للمستخدم فيها.
• excludeMatches
  string[] اختياري
  تستبعد الصفحات التي كان سيتم إدراج نص المستخدم البرمجي فيها. اطّلِع على أنماط المطابقة لمزيد من التفاصيل حول بنية هذه السلاسل.
• رقم تعريف البرنامج النصي للمستخدم المحدّد في طلب البيانات من واجهة برمجة التطبيقات يجب ألا تبدأ هذه السمة بشرطة سفلية "_" لأنّها محجوزة كبادئة لمعرّفات النصوص البرمجية التي يتم إنشاؤها.
• includeGlobs
  string[] اختياري
  تحدّد هذه السمة أنماط أحرف البدل للصفحات التي سيتم إدراج نص برمجي للمستخدم فيها.
• js
  ScriptSource[] اختياري
  قائمة بعناصر ScriptSource تحدّد مصادر النصوص البرمجية التي سيتم إدخالها في الصفحات المطابقة يجب تحديد هذه السمة لـ ${ref:register}، وعند تحديدها، يجب أن تكون مصفوفة غير فارغة.
• فلتر مطابق لـ
  string[] اختياري
  تحدّد هذه السمة الصفحات التي سيتم إدراج نص برمجي للمستخدم فيها. اطّلِع على أنماط المطابقة لمزيد من التفاصيل حول بنية هذه السلاسل. يجب تحديد هذه السمة لـ ${ref:register}.
• تحدّد هذه السمة وقت إدخال ملفات JavaScript في صفحة الويب. القيمة المفضّلة والتلقائية هي document_idle.
• العالم
  ExecutionWorld اختياري
  بيئة تنفيذ JavaScript التي سيتم تشغيل النص البرمجي فيها القيمة التلقائية هي `USER_SCRIPT`.
• الإصدار 133 من Chrome والإصدارات الأحدث
  تحدّد هذه السمة رقم تعريف مساحة تنفيذ البرنامج النصي للمستخدم. في حال عدم تضمينها، سيتم تنفيذ النص البرمجي في بيئة النص البرمجي التلقائية للمستخدم. لا تكون هذه السمة صالحة إلا إذا تم حذف world أو كانت قيمتها USER_SCRIPT. القيم التي تبدأ بشرطة سفلية (_) محجوزة.

ScriptSource

الخصائص

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

UserScriptFilter

الخصائص

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

UserScriptInjection

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

الخصائص

• injectImmediately
  boolean اختياري
  تحديد ما إذا كان يجب بدء عملية الإدخال في الهدف في أقرب وقت ممكن يُرجى العِلم أنّ هذا لا يضمن حدوث عملية الإدخال قبل تحميل الصفحة، إذ قد تكون الصفحة قد تم تحميلها بالفعل عندما يصل النص البرمجي إلى الهدف.
• قائمة بعناصر ScriptSource تحدّد مصادر النصوص البرمجية التي سيتم إدخالها في الهدف.
• تفاصيل تحدّد الهدف الذي سيتم إدخال النص البرمجي فيه.
• العالم
  ExecutionWorld اختياري
  "عالم" JavaScript الذي سيتم تشغيل النص البرمجي فيه القيمة التلقائية هي USER_SCRIPT.
• تحدّد هذه السمة رقم تعريف مساحة تنفيذ البرنامج النصي للمستخدم. في حال عدم تضمينها، سيتم تنفيذ النص البرمجي في بيئة النص البرمجي التلقائية للمستخدم. لا تكون هذه السمة صالحة إلا إذا تم حذف world أو كانت قيمتها USER_SCRIPT. القيم التي تبدأ بشرطة سفلية (_) محجوزة.

WorldProperties

الخصائص

• تحدّد هذه السمة موفّر خدمة السحابة الإلكترونية العالمي. القيمة التلقائية هي `ISOLATED` world csp.
• تحدِّد هذه السمة ما إذا كانت واجهات برمجة التطبيقات الخاصة بالمراسلة متاحة. القيمة التلقائية هي false.
• الإصدار 133 من Chrome والإصدارات الأحدث
  تحدّد هذه السمة معرّف عالم نصوص برمجية محدّد للمستخدم سيتم تعديله. في حال عدم توفيرها، يتم تعديل خصائص عالم نصوص المستخدم التلقائي. القيم التي تبدأ بشرطة سفلية (_) محجوزة.

الطُرق

configureWorld()

chrome.userScripts.configureWorld(
  properties: WorldProperties,
): Promise

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

المعلمات

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

المرتجعات

execute()

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

chrome.userScripts.execute(
  injection: UserScriptInjection,
): Promise<InjectionResult[]>

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

المعلمات

المرتجعات

• Promise<InjectionResult[]>

getScripts()

chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
): Promise<RegisteredUserScript[]>

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

المعلمات

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

المرتجعات

• Promise<RegisteredUserScript[]>

getWorldConfigurations()

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

chrome.userScripts.getWorldConfigurations(): Promise<WorldProperties[]>

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

المرتجعات

• Promise<WorldProperties[]>

register()

chrome.userScripts.register(
  scripts: RegisteredUserScript[],
): Promise

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

المعلمات

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

المرتجعات

resetWorldConfiguration()

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

chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
): Promise

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

المعلمات

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

المرتجعات

unregister()

chrome.userScripts.unregister(
  filter?: UserScriptFilter,
): Promise

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

المعلمات

• تصفية
  ‫UserScriptFilter اختياري
  في حال تحديدها، ستؤدي هذه الطريقة إلى إلغاء تسجيل النصوص البرمجية للمستخدمين التي تتطابق معها فقط.

المرتجعات

update()

chrome.userScripts.update(
  scripts: RegisteredUserScript[],
): Promise

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

المعلمات

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

المرتجعات