الوصف
استخدِم 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. بالنسبة إلى إضافات النصوص البرمجية للمستخدم، على المستخدمين أيضًا تفعيل وضع مطوّر البرامج. في ما يلي التعليمات التي يمكنك نسخها ولصقها في مستنداتك الخاصة.
- انتقِل إلى صفحة "الإضافات" من خلال إدخال
chrome://extensions
في علامة تبويب جديدة. (حسب التصميم، لا يمكن ربط عناوين URL التي تخصّchrome://
). فعّل وضع مطوّر البرامج من خلال النقر على مفتاح التبديل بجانب وضع مطوّر البرامج.
يمكنك تحديد ما إذا كان وضع مطوّر البرامج مفعَّلاً من خلال التحقّق مما إذا كان 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
سلسلة[] اختيارية
لتحديد أنماط أحرف البدل للصفحات التي سيتم إدخال هذا النص البرمجي للمستخدم فيها.
-
js
قائمة كائنات 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`
.
المَعلمات
-
المواقع
يحتوي على إعدادات عالم النص البرمجي للمستخدم.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
getScripts()
chrome.userScripts.getScripts(
filter?: UserScriptFilter,
callback?: function,
)
تعرض جميع نصوص المستخدمين البرمجية المسجّلة ديناميكيًا لهذه الإضافة.
المَعلمات
-
filter
UserScriptFilter اختياري
وفي حال تحديد هذه الطريقة، تعرض هذه الطريقة النصوص البرمجية للمستخدم المطابقة لها فقط.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(scripts: RegisteredUserScript[]) => void
-
نصوص برمجية
-
المرتجعات
-
Promise<RegisteredUserScript[]>
تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
register()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
callback?: function,
)
تسجِّل نصًا برمجيًا واحدًا أو أكثر للمستخدم لهذه الإضافة.
المَعلمات
-
نصوص برمجية
يحتوي على قائمة بالنصوص البرمجية للمستخدمين المطلوب تسجيلها.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
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,
)
تُعدِّل نصًا برمجيًا واحدًا أو أكثر للمستخدم لهذه الإضافة.
المَعلمات
-
نصوص برمجية
يحتوي على قائمة بالنصوص البرمجية للمستخدمين التي سيتم تعديلها. لا يتم تعديل الخاصية للنص البرمجي الحالي إلّا إذا تم تحديدها في هذا العنصر. إذا كانت هناك أخطاء أثناء تحليل النصوص البرمجية/التحقق من الملف، أو إذا كانت المعرفات المحددة لا تتوافق مع نص برمجي مسجل بالكامل، فلن يتم تحديث أي نصوص برمجية.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.