chrome.omnibox

refresh date: 2026-09-25 robots: noindex

الوصف

تتيح لك واجهة برمجة التطبيقات Omnibox API تسجيل كلمة رئيسية في شريط عناوين 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"]
  }
}

أمثلة

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

الأنواع

DefaultSuggestResult

نتيجة مقترَحة

الخصائص

  • الوصف

    سلسلة

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

DescriptionStyleType

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

نوع النمط

Enum

"url"

"match"

"dim"

OnInputEnteredDisposition

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

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

Enum

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

نتيجة مقترَحة

الخصائص

  • المحتوى

    سلسلة

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

  • deletable

    قيمة منطقية اختيارية

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

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

  • الوصف

    سلسلة

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

الطُرق

setDefaultSuggestion()

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

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

المعلمات

  • اقتراح

    DefaultSuggestResult

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

  • callback

    function اختياري

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

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

    () => void

المرتجعات

  • وعد<فراغ>

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

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

الفعاليات

onDeleteSuggestion

الإصدار 63 من Chrome والإصدارات الأحدث 
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