chrome.omnibox

الوصف

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

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

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

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

البيان

يجب الإفصاح عن المفاتيح التالية في ملف البيان لاستخدام واجهة برمجة التطبيقات هذه.

"omnibox"

يجب تضمين حقل "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 والإصدارات الأحدث

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

Enum

"url"

"match"

"dim"

OnInputEnteredDisposition

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

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

Enum

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

نتيجة اقتراح

الخصائص

  • المحتوى

    سلسلة

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

  • قابلة للحذف

    boolean اختياري

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

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

  • الوصف

    سلسلة

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

الطُرق

setDefaultSuggestion()

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

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

المعلمات

  • اقتراح

    DefaultSuggestResult

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

المرتجعات

  • Promise<void>

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

الفعاليات

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