الوصف
استخدِم واجهة برمجة التطبيقات userScripts لتنفيذ نصوص المستخدم البرمجية في سياق "نصوص المستخدم البرمجية".
الأذونات
userScriptsلاستخدام واجهة برمجة التطبيقات User Scripts API، browser.userScripts، أضِف الإذن "userScripts" إلى ملف manifest.json و"host_permissions" للمواقع الإلكترونية التي تريد تشغيل النصوص البرمجية عليها.
{
"name": "User script test extension",
"manifest_version": 3,
"minimum_chrome_version": "120",
"permissions": [
"userScripts"
],
"host_permissions": [
"*://example.com/*"
]
}
مدى التوفّر
المفاهيم والاستخدام
النص البرمجي للمستخدم هو مقتطف من الرمز يتم إدخاله في صفحة ويب لتعديل مظهرها أو سلوكها. على عكس ميزات الإضافات الأخرى، مثل نصوص المحتوى البرمجية وواجهة برمجة التطبيقات browser.scripting، تتيح لك واجهة برمجة التطبيقات User Scripts API تشغيل رمز عشوائي. هذه الواجهة مطلوبة للإضافات التي تشغّل نصوصًا برمجية يوفّرها المستخدم ولا يمكن شحنها كجزء من حزمة الإضافة.
تفعيل استخدام واجهة برمجة التطبيقات userScripts API
بعد أن تحصل الإضافة على إذن باستخدام واجهة userScripts API، يجب على المستخدمين تفعيل زر تبديل معيّن للسماح للإضافة باستخدام واجهة برمجة التطبيقات. ويختلف مفتاح التبديل المطلوب وسلوك واجهة برمجة التطبيقات عند إيقافها حسب إصدار 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 المثبَّت لديك. ويجب على المستخدمين أيضًا تفعيل "وضع مطوّر البرامج".
يمكنك نسخ التعليمات التالية ولصقها في مستندات الإضافة للمستخدمين
- انتقِل إلى صفحة "الإضافات" من خلال إدخال
chrome://extensionsفي علامة تبويب جديدة. (تم تصميم عناوين URL فيchrome://بحيث لا يمكن ربطها.) فعِّل "وضع مطوّر البرامج" من خلال النقر على مفتاح التبديل بجانب وضع مطوّر البرامج.
صفحة "الإضافات" (chrome://extensions)
الإصدار 138 من Chrome والإصدارات الأحدث (مفتاح التبديل "السماح بنصوص المستخدمين البرمجية")
يتوفّر خيار السماح بنصوص المستخدمين البرمجية في صفحة تفاصيل كل إضافة (على سبيل المثال، chrome://extensions/?id=YOUR_EXTENSION_ID).
يمكنك نسخ التعليمات التالية ولصقها في مستندات الإضافة للمستخدمين:
- انتقِل إلى صفحة "الإضافات" من خلال إدخال
chrome://extensionsفي علامة تبويب جديدة. (تم تصميم عناوين URL فيchrome://بحيث لا يمكن ربطها.) - انقر على الزر "التفاصيل" في بطاقة الإضافة لعرض معلومات مفصّلة عنها.
- انقر على مفتاح التبديل بجانب السماح بنصوص المستخدمين البرمجية.
التحقّق من توفّر واجهة برمجة التطبيقات
ننصحك بإجراء عملية التحقّق التالية لتحديد ما إذا كانت واجهة برمجة التطبيقات userScripts API مفعَّلة، لأنّها تعمل في جميع إصدارات Chrome. يحاول هذا الفحص استدعاء طريقة browser.userScripts() التي من المفترض أن تنجح دائمًا عندما تكون واجهة برمجة التطبيقات متاحة. إذا عرض هذا الطلب خطأ، يعني ذلك أنّ واجهة برمجة التطبيقات غير متاحة:
function isUserScriptsAvailable() {
try {
// Method call which throws if API permission or toggle is not enabled.
browser.userScripts.getScripts();
return true;
} catch {
// Not available.
return false;
}
}
العمل في عوالم معزولة
يمكن تشغيل كل من نصوص المستخدم البرمجية ونصوص المحتوى البرمجية في بيئة معزولة أو في البيئة الرئيسية. العالم المعزول هو بيئة تنفيذ لا يمكن لصفحة مضيفة أو إضافات أخرى الوصول إليها. يتيح ذلك للنص البرمجي الخاص بالمستخدم تغيير بيئة JavaScript بدون التأثير في الصفحة المضيفة أو النصوص البرمجية الخاصة بالمستخدم والمحتوى في الإضافات الأخرى. في المقابل، لا تظهر نصوص المستخدم البرمجية (ونصوص المحتوى البرمجية) للصفحة المضيفة أو لنصوص المستخدم والمحتوى البرمجية الخاصة بالإضافات الأخرى. يمكن لصفحات المضيف والإضافات الأخرى الوصول إلى النصوص البرمجية التي يتم تشغيلها في العالم الرئيسي، كما يمكن لصفحات المضيف والإضافات الأخرى رؤيتها. لاختيار العالم، مرِّر "USER_SCRIPT" أو "MAIN" عند استدعاء userScripts.register().
لضبط سياسة أمان المحتوى لعالم USER_SCRIPT، يمكنك استدعاء userScripts.configureWorld():
browser.userScripts.configureWorld({
csp: "script-src 'self'"
});
المراسلة
مثل نصوص المحتوى البرمجية والمستندات خارج الشاشة، تتواصل نصوص المستخدم البرمجية مع أجزاء أخرى من الإضافة باستخدام المراسلة (ما يعني أنّه يمكنها استدعاء runtime.sendMessage() وruntime.connect() كما يفعل أي جزء آخر من الإضافة). ومع ذلك، يتم تلقّيها باستخدام معالِجات أحداث مخصّصة (أي أنّها لا تستخدم onMessage أو onConnect). تُسمّى هذه المعالِجات runtime.onUserScriptMessage وruntime.onUserScriptConnect. تسهّل المعالِجات المخصّصة تحديد الرسائل الواردة من نصوص المستخدمين البرمجية، وهي سياق أقل موثوقية.
قبل إرسال رسالة، يجب استدعاء configureWorld() مع ضبط الوسيطة messaging على true. يُرجى العِلم أنّه يمكن تمرير الوسيطتَين csp وmessaging في الوقت نفسه.
browser.userScripts.configureWorld({
messaging: true
});
تحديثات الإضافات
يتم محو نصوص المستخدم البرمجية عند تحديث الإضافة. ويمكنك إضافتها مرة أخرى من خلال تشغيل الرمز في معالج الأحداث runtime.onInstalled في مشغّل خدمات الإضافة. يجب الردّ فقط على السبب "update" الذي تم تمريره إلى دالة الاستدعاء الخاصة بالحدث.
مثال
هذا المثال مأخوذ من نموذج userScript في مستودع النماذج.
تسجيل نص برمجي
يوضّح المثال التالي طلبًا أساسيًا إلى register(). الوسيطة الأولى هي مصفوفة من العناصر التي تحدّد النصوص البرمجية المطلوب تسجيلها. هناك خيارات أكثر من تلك المعروضة هنا.
browser.userScripts.register([{
id: 'test',
matches: ['*://*/*'],
js: [{code: 'alert("Hi!")'}]
}]);
الأنواع
ExecutionWorld
يشير ذلك إلى بيئة JavaScript التي يتم تنفيذ نص برمجي للمستخدم فيها.
Enum
"MAIN"
تحدّد بيئة تنفيذ نموذج العناصر في المستند (DOM)، وهي بيئة التنفيذ التي تتم مشاركتها مع JavaScript الخاص بالصفحة المضيفة.
"USER_SCRIPT"
تحدّد بيئة التنفيذ الخاصة بنصوص المستخدم البرمجية والتي يتم إعفاؤها من سياسة أمان المحتوى (CSP) الخاصة بالصفحة.
InjectionResult
الخصائص
-
documentId
سلسلة
المستند المرتبط بالحقن
-
خطأ
string اختياري
الخطأ، إن وُجد يستبعد كلّ من
errorوresultالآخر. -
frameId
الرقم
الإطار المرتبط بالحقن.
-
نتيجة
أيّ اختياري
نتيجة تنفيذ النص البرمجي
InjectionTarget
الخصائص
-
allFrames
قيمة منطقية اختيارية
ما إذا كان يجب حقن النص البرمجي في جميع الإطارات ضمن علامة التبويب. الخيار التلقائي هو "خطأ". يجب ألا تكون هذه القيمة صحيحة في حال تحديد
frameIds. -
documentIds
string[] اختياري
أرقام تعريف documentIds المحدّدة المطلوب إدخالها يجب عدم ضبط هذه السمة في حال ضبط السمة
frameIds. -
frameIds
number[] اختيارية
أرقام تعريف الإطارات المحدّدة المطلوب حقنها
-
tabId
الرقم
رقم تعريف علامة التبويب المطلوب إدخالها
RegisteredUserScript
الخصائص
-
allFrames
قيمة منطقية اختيارية
إذا كانت القيمة "صحيح"، سيتم إدخال النص البرمجي في جميع الإطارات، حتى إذا لم يكن الإطار هو الإطار الأعلى في علامة التبويب. يتم التحقّق من كل إطار بشكل مستقل للتأكّد من استيفائه متطلبات عناوين URL، ولن يتم حقن النصوص البرمجية في الإطارات الفرعية إذا لم يتم استيفاء متطلبات عناوين URL. تكون القيمة التلقائية false، ما يعني أنّه تتم مطابقة الإطار العلوي فقط.
-
excludeGlobs
string[] اختياري
تحدِّد هذه السياسة أنماط أحرف البدل للصفحات التي لن يتم إدخال نص المستخدم هذا فيها.
-
excludeMatches
string[] اختياري
يستبعد الصفحات التي سيتم حقن نص المستخدم هذا فيها. يُرجى الاطّلاع على أنماط المطابقة لمزيد من التفاصيل حول بنية هذه السلاسل.
-
id
سلسلة
رقم تعريف نص المستخدم البرمجي المحدّد في طلب البيانات من واجهة برمجة التطبيقات يجب ألا تبدأ هذه السمة بشرطة سفلية "_" لأنّها محجوزة كبادئة لمعرّفات النصوص البرمجية التي يتم إنشاؤها.
-
includeGlobs
string[] اختياري
تحدِّد هذه السياسة أنماط أحرف البدل للصفحات التي سيتم إدخال نص المستخدم هذا فيها.
-
js
ScriptSource[] اختيارية
قائمة بعناصر ScriptSource التي تحدّد مصادر النصوص البرمجية التي سيتم إدخالها في الصفحات المطابقة. يجب تحديد هذه السمة لـ ${ref:register}، وعند تحديدها يجب أن تكون مصفوفة غير فارغة.
-
فلتر مطابق لـ
string[] اختياري
تحدّد هذه السمة الصفحات التي سيتم إدخال نص المستخدم البرمجي هذا فيها. يُرجى الاطّلاع على أنماط المطابقة لمزيد من التفاصيل حول بنية هذه السلاسل. يجب تحديد هذه السمة لـ ${ref:register}.
-
runAt
RunAt اختيارية
يحدّد هذا الإعداد وقت إدخال ملفات JavaScript في صفحة الويب. القيمة المفضّلة والتلقائية هي
document_idle. -
العالم
ExecutionWorld اختياري
بيئة تنفيذ JavaScript لتشغيل النص البرمجي فيها القيمة التلقائية هي
`USER_SCRIPT`. -
worldId
string اختياري
الإصدار 133 من Chrome والإصدارات الأحدث browser.* منذ الإصدار 148 من Chromeتحدّد هذه السياسة رقم تعريف بيئة نص المستخدم البرمجي المطلوب تنفيذه. في حال حذف هذه السمة، سيتم تنفيذ النص البرمجي في بيئة النص البرمجي التلقائية للمستخدم. تكون هذه السمة صالحة فقط في حال حذف
worldأو ضبطها علىUSER_SCRIPT. يتم حجز القيم التي تبدأ بشرطة سفلية (_).
ScriptSource
الخصائص
-
رمز
string اختياري
سلسلة تحتوي على رمز JavaScript المطلوب إدخاله يجب تحديد سمة واحدة فقط من
fileأوcode. -
ملف واحد
string اختياري
مسار ملف JavaScript الذي سيتم إدخاله بالنسبة إلى الدليل الجذري للإضافة يجب تحديد سمة واحدة فقط من
fileأوcode.
UserScriptFilter
الخصائص
-
ids
string[] اختياري
لا تعرض السمة
getScriptsسوى النصوص البرمجية التي تتضمّن أرقام التعريف المحدّدة في هذه القائمة.
UserScriptInjection
الخصائص
-
injectImmediately
قيمة منطقية اختيارية
ما إذا كان يجب تشغيل الحقن في الهدف في أقرب وقت ممكن. يُرجى العِلم أنّ هذا لا يضمن حدوث الإدخال قبل تحميل الصفحة، لأنّ الصفحة قد تكون قد تم تحميلها بالفعل بحلول الوقت الذي يصل فيه النص البرمجي إلى الهدف.
-
js
قائمة بعناصر ScriptSource التي تحدّد مصادر النصوص البرمجية التي سيتم إدخالها في الهدف
-
target
تفاصيل تحدّد الهدف الذي سيتم إدخال النص البرمجي فيه
-
العالم
ExecutionWorld اختياري
تمثّل هذه السمة "بيئة" JavaScript التي سيتم تشغيل النص البرمجي فيها. القيمة التلقائية هي
USER_SCRIPT. -
worldId
string اختياري
تحدّد هذه السياسة رقم تعريف بيئة نص المستخدم البرمجي المطلوب تنفيذه. في حال حذف هذه السمة، سيتم تنفيذ النص البرمجي في بيئة النص البرمجي التلقائية للمستخدم. تكون هذه السمة صالحة فقط في حال حذف
worldأو ضبطها علىUSER_SCRIPT. يتم حجز القيم التي تبدأ بشرطة سفلية (_).
WorldProperties
الخصائص
-
csp
string اختياري
تحدّد هذه السمة موفّر خدمة المحتوى (CSP) على مستوى العالم. الإعداد التلقائي هو
`ISOLATED`world csp. -
المراسلة
قيمة منطقية اختيارية
يحدّد ما إذا كان سيتم عرض واجهات برمجة التطبيقات للمراسلة. القيمة التلقائية هي
false. -
worldId
string اختياري
الإصدار 133 من Chrome والإصدارات الأحدث browser.* منذ الإصدار 148 من Chromeيحدّد هذا الإعداد رقم تعريف بيئة نص المستخدم البرمجي المحدّدة المطلوب تعديلها. في حال عدم توفيره، يتم تعديل خصائص بيئة النص البرمجي التلقائية للمستخدم. يتم حجز القيم التي تبدأ بشرطة سفلية (
_).
الطُرق
configureWorld()
browser.userScripts.configureWorld(
properties: WorldProperties,
): Promise<void>
تضبط هذه السياسة بيئة تنفيذ `USER_SCRIPT`.
المعلمات
-
أماكن الإقامة
تحتوي على إعدادات بيئة النص البرمجي للمستخدم.
المرتجعات
-
وعد<فراغ>
وعد يتم حلّه بعد ضبط العالم
execute()
browser.userScripts.execute(
injection: UserScriptInjection,
): Promise<InjectionResult[]>
يتيح هذا الإذن إدخال نص برمجي في سياق مستهدَف. سيتم تشغيل النص البرمجي تلقائيًا عند document_idle، أو فورًا إذا تم تحميل الصفحة. في حال ضبط السمة injectImmediately، سيتم إدخال النص البرمجي بدون انتظار، حتى إذا لم ينتهِ تحميل الصفحة. إذا تم تقييم النص البرمجي على أنّه وعد، سينتظر المتصفّح تسوية الوعد وعرض القيمة الناتجة.
المعلمات
-
حُقْنَة
المرتجعات
-
Promise<InjectionResult[]>
getScripts()
browser.userScripts.getScripts(
filter?: UserScriptFilter,
): Promise<RegisteredUserScript[]>
تعرض هذه الطريقة جميع نصوص المستخدم البرمجية المسجّلة ديناميكيًا لهذه الإضافة.
المعلمات
-
تصفية
UserScriptFilter اختياري
في حال تحديد هذا الحقل، ستعرض هذه الطريقة نصوص المستخدم البرمجية التي تتطابق معه فقط.
المرتجعات
-
Promise<RegisteredUserScript[]>
وعد يتم حلّه باستخدام النصوص البرمجية المسجّلة سيتم رفض الوعد في حال حدوث خطأ.
getWorldConfigurations()
browser.userScripts.getWorldConfigurations(): Promise<WorldProperties[]>
تسترد هذه الطريقة جميع إعدادات العالم المسجّلة.
المرتجعات
-
Promise<WorldProperties[]>
Promise الذي يتم حله باستخدام إعدادات العالم المسجَّلة
register()
browser.userScripts.register(
scripts: RegisteredUserScript[],
): Promise<void>
لتسجيل نص برمجي واحد أو أكثر من نصوص المستخدم البرمجية لهذه الإضافة
المعلمات
-
نصوص برمجية
تحتوي على قائمة بنصوص المستخدم البرمجية التي سيتم تسجيلها.
المرتجعات
-
وعد<فراغ>
وعد يتم حله بعد تسجيل النصوص البرمجية بالكامل. سيتم رفض الوعد في حال حدوث خطأ.
resetWorldConfiguration()
browser.userScripts.resetWorldConfiguration(
worldId?: string,
): Promise<void>
تتم إعادة ضبط إعدادات بيئة النص البرمجي للمستخدم. وستستخدم أي نصوص برمجية يتم إدخالها في البيئة التي تحمل المعرّف المحدّد الإعدادات التلقائية للبيئة.
المعلمات
-
worldId
string اختياري
رقم تعريف بيئة نص المستخدم البرمجي المطلوب إعادة ضبطها في حال حذف هذه السمة، تتم إعادة ضبط إعدادات العالم التلقائي.
المرتجعات
-
وعد<فراغ>
وعد يتم حلّه عند إعادة ضبط الإعدادات.
unregister()
browser.userScripts.unregister(
filter?: UserScriptFilter,
): Promise<void>
يؤدي هذا الإجراء إلى إلغاء تسجيل جميع نصوص المستخدم البرمجية المسجَّلة ديناميكيًا لهذه الإضافة.
المعلمات
-
تصفية
UserScriptFilter اختياري
في حال تحديد هذه الطريقة، يتم إلغاء تسجيل نصوص المستخدم البرمجية التي تتطابق معها فقط.
المرتجعات
-
وعد<فراغ>
وعد يتم حلّه بعد إلغاء تسجيل النصوص البرمجية بالكامل. سيتم رفض الوعد في حال حدوث خطأ.
update()
browser.userScripts.update(
scripts: RegisteredUserScript[],
): Promise<void>
تعديل نص برمجي واحد أو أكثر للمستخدم في هذه الإضافة
المعلمات
-
نصوص برمجية
تحتوي على قائمة بنصوص المستخدم البرمجية التي سيتم تعديلها. لا يتم تعديل سمة للنص البرمجي الحالي إلا إذا تم تحديدها في هذا العنصر. إذا حدثت أخطاء أثناء تحليل النص البرمجي أو التحقّق من صحة الملف، أو إذا كانت أرقام التعريف المحدّدة لا تتوافق مع نص برمجي مسجَّل بالكامل، لن يتم تعديل أي نصوص برمجية.
المرتجعات
-
وعد<فراغ>
وعد يتم حله بعد تحديث النصوص البرمجية بالكامل. سيتم رفض الوعد في حال حدوث خطأ.