الوصف
استخدِم واجهة برمجة التطبيقات 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.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 الذي تستخدمه. على المستخدمين أيضًا تفعيل "وضع مطوّر البرامج".
يمكنك نسخ التعليمات التالية ولصقها في مستندات الإضافة لتوفيرها للمستخدمين
- انتقِل إلى صفحة "الإضافات" من خلال إدخال
chrome://extensionsفي علامة تبويب جديدة. (لا يمكن ربط عناوين URL التي تبدأ بـchrome://). فعِّل "وضع مطوّر البرامج" من خلال النقر على مفتاح التبديل بجانب وضع مطوّر البرامج.
صفحة "الإضافات" (chrome://extensions)
الإصدار 138 من Chrome والإصدارات الأحدث (زر التبديل "السماح ببرامج المستخدم النصية")
يكون مفتاح التبديل السماح ببرامج المستخدمين مفعَّلاً في صفحة تفاصيل كل إضافة (على سبيل المثال، chrome://extensions/?id=YOUR_EXTENSION_ID).
يمكنك نسخ التعليمات التالية ولصقها في مستندات الإضافة لتوفيرها للمستخدمين:
- انتقِل إلى صفحة "الإضافات" من خلال إدخال
chrome://extensionsفي علامة تبويب جديدة. (لا يمكن ربط عناوين URL التي تبدأ بـchrome://). - انقر على الزر "التفاصيل" في بطاقة الإضافة لعرض معلومات مفصّلة عنها.
- انقر على مفتاح التبديل بجانب السماح ببرامج المستخدمين.
التحقّق من توفّر واجهة برمجة التطبيقات
ننصحك بإجراء عملية التحقّق التالية لتحديد ما إذا كانت واجهة برمجة التطبيقات 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
الخصائص
-
documentId
سلسلة
المستند المرتبط بعملية الإدخال
-
خطأ
سلسلة اختيارية
الخطأ، إن وُجد يستبعد كلّ من الحقلَين
errorوresultالآخر. -
frameId
الرقم
الإطار المرتبط بعملية الإدخال
-
نتيجة
أي اختياري
نتيجة تنفيذ النص البرمجي
InjectionTarget
الخصائص
-
allFrames
boolean اختياري
تحديد ما إذا كان يجب إدراج النص البرمجي في جميع الإطارات ضمن علامة التبويب القيمة التلقائية هي "خطأ". يجب ألا تكون هذه السمة صحيحة إذا تم تحديد
frameIds. -
documentIds
string[] اختياري
معرّفات documentId المحدّدة التي سيتم إدراجها فيها. يجب عدم ضبط هذه السياسة في حال ضبط سياسة
frameIds. -
frameIds
number[] اختيارية
معرّفات إطارات معيّنة سيتم إدراج الإعلانات فيها
-
tabId
الرقم
رقم تعريف علامة التبويب التي سيتم إدراج المحتوى فيها
RegisteredUserScript
الخصائص
-
allFrames
boolean اختياري
إذا كانت القيمة صحيحة، سيتم إدخالها في جميع الإطارات، حتى إذا لم يكن الإطار هو الإطار الأعلى في علامة التبويب. يتم التحقّق من كل إطار بشكل مستقل للتأكّد من استيفاء متطلبات عنوان URL، ولن يتم إدراجه في الإطارات الفرعية إذا لم يتم استيفاء متطلبات عنوان URL. القيمة التلقائية هي "خطأ"، ما يعني أنّه يتم مطابقة الإطار العلوي فقط.
-
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
سلسلة اختيارية
الإصدار 133 من Chrome والإصدارات الأحدثتحدّد هذه السمة رقم تعريف مساحة تنفيذ البرنامج النصي للمستخدم. في حال عدم تضمينها، سيتم تنفيذ النص البرمجي في بيئة النص البرمجي التلقائية للمستخدم. لا تكون هذه السمة صالحة إلا إذا تم حذف
worldأو كانت قيمتهاUSER_SCRIPT. القيم التي تبدأ بشرطة سفلية (_) محجوزة.
ScriptSource
الخصائص
-
رمز
سلسلة اختيارية
سلسلة تحتوي على رمز JavaScript المراد إدخاله يجب تحديد سمة واحدة فقط من
fileأوcode. -
ملف
سلسلة اختيارية
مسار ملف JavaScript الذي سيتم إدخاله بالنسبة إلى الدليل الجذر للإضافة يجب تحديد سمة واحدة فقط من
fileأوcode.
UserScriptFilter
الخصائص
-
ids
string[] اختياري
لا تعرض الدالة
getScriptsسوى النصوص البرمجية التي تحمل المعرّفات المحدّدة في هذه القائمة.
UserScriptInjection
الخصائص
-
injectImmediately
boolean اختياري
تحديد ما إذا كان يجب بدء عملية الإدخال في الهدف في أقرب وقت ممكن يُرجى العِلم أنّ هذا لا يضمن حدوث عملية الإدخال قبل تحميل الصفحة، إذ قد تكون الصفحة قد تم تحميلها بالفعل عندما يصل النص البرمجي إلى الهدف.
-
js
قائمة بعناصر ScriptSource تحدّد مصادر النصوص البرمجية التي سيتم إدخالها في الهدف.
-
الاستهداف
تفاصيل تحدّد الهدف الذي سيتم إدخال النص البرمجي فيه.
-
العالم
ExecutionWorld اختياري
"عالم" JavaScript الذي سيتم تشغيل النص البرمجي فيه القيمة التلقائية هي
USER_SCRIPT. -
worldId
سلسلة اختيارية
تحدّد هذه السمة رقم تعريف مساحة تنفيذ البرنامج النصي للمستخدم. في حال عدم تضمينها، سيتم تنفيذ النص البرمجي في بيئة النص البرمجي التلقائية للمستخدم. لا تكون هذه السمة صالحة إلا إذا تم حذف
worldأو كانت قيمتهاUSER_SCRIPT. القيم التي تبدأ بشرطة سفلية (_) محجوزة.
WorldProperties
الخصائص
-
csp
سلسلة اختيارية
تحدّد هذه السمة موفّر خدمة السحابة الإلكترونية العالمي. القيمة التلقائية هي
`ISOLATED`world csp. -
المراسلة
boolean اختياري
تحدِّد هذه السمة ما إذا كانت واجهات برمجة التطبيقات الخاصة بالمراسلة متاحة. القيمة التلقائية هي
false. -
worldId
سلسلة اختيارية
الإصدار 133 من Chrome والإصدارات الأحدثتحدّد هذه السمة معرّف عالم نصوص برمجية محدّد للمستخدم سيتم تعديله. في حال عدم توفيرها، يتم تعديل خصائص عالم نصوص المستخدم التلقائي. القيم التي تبدأ بشرطة سفلية (
_) محجوزة.
الطُرق
configureWorld()
chrome.userScripts.configureWorld(
properties: WorldProperties,
): Promise<void>
تضبط هذه السمة بيئة تنفيذ `USER_SCRIPT`.
المعلمات
-
المواقع
يحتوي على إعدادات بيئة النص البرمجي للمستخدم.
المرتجعات
-
Promise<void>
execute()
chrome.userScripts.execute(
injection: UserScriptInjection,
): Promise<InjectionResult[]>
يتيح هذا الإذن إدخال نص برمجي في سياق مستهدف. سيتم تشغيل النص البرمجي تلقائيًا في document_idle، أو فورًا إذا تم تحميل الصفحة من قبل. في حال ضبط السمة injectImmediately، سيتم إدراج النص البرمجي بدون انتظار، حتى إذا لم ينتهِ تحميل الصفحة. إذا تم تقييم النص البرمجي على أنّه وعد، سينتظر المتصفّح إلى أن يتم تنفيذ الوعد ويعرض القيمة الناتجة.
المعلمات
-
الحقن
المرتجعات
-
Promise<InjectionResult[]>
getScripts()
chrome.userScripts.getScripts(
filter?: UserScriptFilter,
): Promise<RegisteredUserScript[]>
تعرض هذه الطريقة جميع نصوص برامج المستخدمين المسجّلة ديناميكيًا لهذه الإضافة.
المعلمات
-
تصفية
UserScriptFilter اختياري
في حال تحديدها، لا تعرض هذه الطريقة سوى نصوص المستخدمين البرمجية التي تتطابق معها.
المرتجعات
-
Promise<RegisteredUserScript[]>
getWorldConfigurations()
chrome.userScripts.getWorldConfigurations(): Promise<WorldProperties[]>
يستردّ هذا الإجراء جميع إعدادات العالم المسجّلة.
المرتجعات
-
Promise<WorldProperties[]>
register()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
): Promise<void>
تسجِّل هذه السمة نصًا برمجيًا واحدًا أو أكثر للمستخدم لهذه الإضافة.
المعلمات
-
نصوص برمجية
يحتوي على قائمة ببرامج المستخدم النصية التي سيتم تسجيلها.
المرتجعات
-
Promise<void>
resetWorldConfiguration()
chrome.userScripts.resetWorldConfiguration(
worldId?: string,
): Promise<void>
تعيد هذه الطريقة ضبط إعدادات مساحة عمل نص برمجي للمستخدم. ستستخدم أي نصوص برمجية يتم إدخالها في العالم باستخدام المعرّف المحدّد إعدادات العالم التلقائية.
المعلمات
-
worldId
سلسلة اختيارية
معرّف عالم نصوص المستخدم المطلوب إعادة ضبطه. في حال عدم إدخال قيمة، تتم إعادة ضبط الإعدادات التلقائية للعالم.
المرتجعات
-
Promise<void>
unregister()
chrome.userScripts.unregister(
filter?: UserScriptFilter,
): Promise<void>
لإلغاء تسجيل جميع نصوص المستخدمين البرمجية المسجّلة ديناميكيًا لهذه الإضافة
المعلمات
-
تصفية
UserScriptFilter اختياري
في حال تحديدها، ستؤدي هذه الطريقة إلى إلغاء تسجيل النصوص البرمجية للمستخدمين التي تتطابق معها فقط.
المرتجعات
-
Promise<void>
update()
chrome.userScripts.update(
scripts: RegisteredUserScript[],
): Promise<void>
تعدّل هذه الطريقة نصًا برمجيًا واحدًا أو أكثر للمستخدم لهذه الإضافة.
المعلمات
-
نصوص برمجية
يحتوي على قائمة بنصوص برامج المستخدمين التي سيتم تعديلها. لا يتم تعديل السمة للبرنامج النصي الحالي إلا إذا تم تحديدها في هذا العنصر. في حال حدوث أخطاء أثناء تحليل النص البرمجي أو التحقّق من صحة الملف، أو إذا كانت المعرّفات المحدّدة لا تتوافق مع نص برمجي مسجّل بالكامل، لن يتم تعديل أي نصوص برمجية.
المرتجعات
-
Promise<void>