chrome.omnibox

توضیحات

omnibox API به شما امکان می دهد کلمه کلیدی را در نوار آدرس گوگل کروم که به omnibox نیز معروف است، ثبت کنید.

تصویری که پیشنهادات مربوط به کلمه کلیدی «جستجوی Chromium» را نشان می‌دهد

هنگامی که کاربر کلمه کلیدی افزونه شما را وارد می کند، کاربر صرفاً با برنامه افزودنی شما تعامل برقرار می کند. هر ضربه کلید به برنامه افزودنی شما ارسال می شود و شما می توانید در پاسخ به آن پیشنهاداتی ارائه دهید.

پیشنهادها را می‌توان به روش‌های مختلف به شکلی غنی تنظیم کرد. وقتی کاربر پیشنهادی را می‌پذیرد، برنامه افزودنی شما مطلع می‌شود و می‌تواند اقدامی انجام دهد.

آشکار

برای استفاده از این API باید کلیدهای زیر در مانیفست اعلان شوند.

"omnibox"

برای استفاده از omnibox API باید یک فیلد "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"]
  }
}

نمونه ها

برای امتحان این API، نمونه API omnibox را از مخزن chrome-extension-samples نصب کنید.

انواع

DefaultSuggestResult

یک نتیجه پیشنهادی

خواص

  • توضیحات

    رشته

    متنی که در منوی کشویی URL نمایش داده می شود. می تواند شامل نشانه گذاری به سبک XML برای یک ظاهر طراحی شود. برچسب‌های پشتیبانی شده عبارتند از 'url' (برای یک URL تحت اللفظی)، 'Match' (برای برجسته کردن متنی که با درخواست کاربر مطابقت دارد)، و 'dim' (برای متن کمکی کم رنگ). سبک ها را می توان تو در تو قرار داد، به عنوان مثال. کبریت کم رنگ

DescriptionStyleType

Chrome 44+

نوع سبک

Enum

"url"

"مطابقت"

"کم نور"

OnInputEnteredDisposition

Chrome 44+

موقعیت پنجره برای عبارت omnibox. این زمینه پیشنهادی برای نمایش نتایج است. به عنوان مثال، اگر دستور omnibox به یک URL خاص پیمایش کند، قرار گرفتن "newForegroundTab" به این معنی است که پیمایش باید در یک برگه انتخابی جدید انجام شود.

Enum

"currentTab"

"NewForegroundTab"

"NewBackgroundTab"

SuggestResult

یک نتیجه پیشنهادی

خواص

  • محتوا

    رشته

    متنی که در نوار URL قرار می گیرد و زمانی که کاربر این ورودی را انتخاب می کند به برنامه افزودنی ارسال می شود.

  • قابل حذف

    بولی اختیاری

    Chrome 63+

    آیا نتیجه پیشنهادی می تواند توسط کاربر حذف شود یا خیر.

  • توضیحات

    رشته

    متنی که در منوی کشویی URL نمایش داده می شود. می تواند شامل نشانه گذاری به سبک XML برای یک ظاهر طراحی شود. برچسب‌های پشتیبانی شده عبارتند از 'url' (برای یک URL تحت اللفظی)، 'Match' (برای برجسته کردن متنی که با درخواست کاربر مطابقت دارد)، و 'dim' (برای متن کمکی کم رنگ). سبک ها را می توان تو در تو قرار داد، به عنوان مثال. کبریت کم رنگ شما باید از پنج موجودیت از پیش تعریف شده فرار کنید تا آنها را به صورت متن نمایش دهید: stackoverflow.com/a/1091953/89484

روش ها

setDefaultSuggestion()

قول بده
chrome.omnibox.setDefaultSuggestion(
  suggestion: DefaultSuggestResult,
  callback?: function,
)

توضیحات و استایل را برای پیشنهاد پیش‌فرض تنظیم می‌کند. پیشنهاد پیش فرض متنی است که در ردیف پیشنهادی اول در زیر نوار URL نمایش داده می شود.

پارامترها

  • پیشنهاد

    DefaultSuggest Result

    یک شیء جزئی SuggestResult، بدون پارامتر "content".

  • پاسخ به تماس

    عملکرد اختیاری

    Chrome 100+

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول<باطل>

    Chrome 100+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

رویدادها

onDeleteSuggestion

Chrome 63+
chrome.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

کاربر یک نتیجه پیشنهادی را حذف کرده است.

پارامترها

  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد: 

    (text: string) => void

    • متن

      رشته

onInputCancelled

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

کاربر جلسه ورودی کلمه کلیدی را بدون پذیرش ورودی به پایان رسانده است.

پارامترها

  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد: 

    () => void

onInputChanged

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

کاربر آنچه را که در omnibox تایپ شده است تغییر داده است.

پارامترها

  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد: 

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

    • متن

      رشته

    • پیشنهاد می کند

      تابع

      پارامتر suggest به صورت زیر است: 

      (suggestResults: SuggestResult[]) => void

onInputEntered

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

کاربر آنچه را که در omnibox تایپ شده است پذیرفته است.

پارامترها

onInputStarted

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

کاربر با تایپ کلمه کلیدی برنامه افزودنی جلسه ورودی کلمه کلیدی را شروع کرده است. این تضمین شده است که دقیقاً یک بار در هر جلسه ورودی و قبل از هر رویداد onInputChanged ارسال شود.

پارامترها

  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد: 

    () => void