chrome.omnibox

refresh date: 2026-09-25 robots: noindex

الوصف

تتيح لك واجهة برمجة التطبيقات الخاصة بالمربّع المتعدد الاستخدامات تسجيل كلمة رئيسية في شريط العناوين في Google Chrome، المعروف أيضًا باسم المربّع المتعدد الاستخدامات.

لقطة شاشة تعرض اقتراحات ذات صلة بالكلمة الرئيسية "بحث Chromium"

عندما يُدخل المستخدم الكلمة الرئيسية الخاصة بإضافتك، يبدأ التفاعل مع إضافتك فقط. يتم إرسال كل ضغطة مفتاح إلى الإضافة، ويمكنك تقديم اقتراحات ردًا على ذلك.

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

البيان

يجب تضمين الحقل omnibox keyword في ملف البيان لاستخدام واجهة برمجة التطبيقات الخاصة بالمربّع المتعدد الاستخدامات. عليك أيضًا تحديد رمز بحجم 16×16 بكسل سيتم عرضه في شريط العناوين عند اقتراح أن يدخل المستخدمون وضع الكلمات الرئيسية.

على سبيل المثال:

{
  "name": "Aaron's omnibox extension",
  "version": "1.0",
  "omnibox": { "keyword" : "aaron" },
  "icons": {
    "16": "16-full-color.png"
  },
  "background": {
    "persistent": false,
    "scripts": ["background.js"]
  }
}

أمثلة

لتجربة واجهة برمجة التطبيقات هذه، ثبِّت مثال واجهة برمجة التطبيقات الخاصة بمربّع متعدد الاستخدامات من مستودع chrome-extension-samples.

الأنواع

DefaultSuggestResult

نتيجة اقتراح

الخصائص

  • الوصف

    سلسلة

    النص الذي يتم عرضه في القائمة المنسدلة لعنوان URL يمكن أن يحتوي على ترميز بتنسيق XML للتصميم. العلامات المتوافقة هي "url" (لعنوان URL حرفي) و"match" (لتمييز النص الذي يتطابق مع طلب بحث المستخدم) و"dim" (لنص المساعدة الباهت). يمكن دمج الأنماط، مثل المطابقة المخفّضة.

DescriptionStyleType

Chrome 44 والإصدارات الأحدث

تمثّل هذه السمة نوع النمط.

تعداد

"url"

"match"

"dim"

OnInputEnteredDisposition

Chrome 44 والإصدارات الأحدث

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

تعداد

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

نتيجة اقتراح

الخصائص

  • المحتوى

    سلسلة

    النص الذي يتم إدخاله في شريط عناوين URL والذي يتم إرساله إلى الإضافة عندما يختار المستخدم هذا الإدخال

  • قابلة للحذف

    boolean اختياري

    Chrome 63 والإصدارات الأحدث

    تحدّد هذه السمة ما إذا كان بإمكان المستخدم حذف نتيجة الاقتراح.

  • الوصف

    سلسلة

    النص الذي يتم عرضه في القائمة المنسدلة لعنوان URL يمكن أن يحتوي على ترميز بتنسيق XML للتصميم. العلامات المتوافقة هي "url" (لعنوان URL حرفي) و"match" (لتمييز النص الذي يتطابق مع طلب بحث المستخدم) و"dim" (لنص المساعدة الباهت). يمكن دمج الأنماط، مثل المطابقة المخفّضة. يجب إيقاف عمل الكيانات الخمس المحدّدة مسبقًا لعرضها كنص: stackoverflow.com/a/1091953/89484

الطُرق

setDefaultSuggestion()

وعد 
chrome.omnibox.setDefaultSuggestion(
  suggestion: DefaultSuggestResult,
  callback?: function,
): Promise<void>

تضبط هذه السمة الوصف والنمط الخاصين بالاقتراح التلقائي. الاقتراح التلقائي هو النص الذي يظهر في صف الاقتراحات الأول أسفل شريط عنوان URL.

المعلمات

  • اقتراح

    DefaultSuggestResult

    كائن SuggestResult جزئي، بدون المَعلمة "content"

  • callback

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

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • Promise<void>

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

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

الفعاليات

onDeleteSuggestion

Chrome 63 والإصدارات الأحدث 
chrome.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

حذف المستخدم نتيجة مقترَحة.

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (text: string) => void

    • نصي

      سلسلة

onInputCancelled

chrome.omnibox.onInputCancelled.addListener(
  callback: function,
)

أنهى المستخدم جلسة إدخال الكلمات الرئيسية بدون قبول الإدخال.

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    () => void

onInputChanged

chrome.omnibox.onInputChanged.addListener(
  callback: function,
)

غيَّر المستخدم ما تم إدخاله في مربّع متعدد الاستخدامات.

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (text: string, suggest: function) => void

    • نصي

      سلسلة

    • اقتراح

      دالة

      تظهر المَعلمة suggest على النحو التالي: 

      (suggestResults: SuggestResult[]) => void

      • suggestResults

        SuggestResult[]

        مجموعة من نتائج الاقتراحات

onInputEntered

chrome.omnibox.onInputEntered.addListener(
  callback: function,
)

قبِل المستخدم ما تمّت كتابته في مربّع متعدد الاستخدامات.

المعلمات

onInputStarted

chrome.omnibox.onInputStarted.addListener(
  callback: function,
)

بدأ المستخدم جلسة إدخال كلمة رئيسية من خلال كتابة الكلمة الرئيسية للإضافة. ويُضمن إرسال هذا الحدث مرة واحدة بالضبط لكل جلسة إدخال، وقبل أي أحداث onInputChanged.

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    () => void