chrome.omnibox

refresh date: 2026-09-25 robots: noindex

คำอธิบาย

Omnibox API ช่วยให้คุณลงทะเบียนคีย์เวิร์ดกับแถบที่อยู่ของ Google Chrome หรือที่เรียกว่าแถบอเนกประสงค์ได้

ภาพหน้าจอที่แสดงคำแนะนำที่เกี่ยวข้องกับคีย์เวิร์ด "การค้นหาใน Chromium"

เมื่อผู้ใช้ป้อนคีย์เวิร์ดของส่วนขยาย ผู้ใช้จะเริ่มโต้ตอบกับส่วนขยายของคุณเท่านั้น ระบบจะส่งการกดแป้นพิมพ์แต่ละครั้งไปยังส่วนขยายของคุณ และคุณสามารถให้คำแนะนำเพื่อตอบกลับได้

คำแนะนำสามารถจัดรูปแบบได้หลากหลายวิธี เมื่อผู้ใช้ยอมรับคำแนะนำ ส่วนขยายจะได้รับการแจ้งเตือนและดำเนินการได้

ไฟล์ Manifest

คุณต้องใส่ช่อง omnibox keyword ในไฟล์ Manifest เพื่อใช้ Omnibox API นอกจากนี้ คุณควรระบุไอคอนขนาด 16x16 พิกเซล ซึ่งจะแสดงในแถบที่อยู่เมื่อแนะนำให้ผู้ใช้เข้าสู่โหมดคีย์เวิร์ด

เช่น

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

ตัวอย่าง

หากต้องการลองใช้ API นี้ ให้ติดตั้งตัวอย่าง Omnibox API จากที่เก็บ chrome-extension-samples

ประเภท

DefaultSuggestResult

ผลการแนะนำ

พร็อพเพอร์ตี้

  • คำอธิบาย

    สตริง

    ข้อความที่แสดงในเมนูแบบเลื่อนลงของ URL มีมาร์กอัปสไตล์ XML สำหรับการจัดรูปแบบได้ แท็กที่รองรับคือ "url" (สำหรับ URL ตามตัวอักษร), "match" (สำหรับไฮไลต์ข้อความที่ตรงกับคำค้นหาของผู้ใช้) และ "dim" (สำหรับข้อความช่วยเหลือแบบจาง) คุณสามารถฝังรูปแบบได้ เช่น การจับคู่ที่หรี่แสง

DescriptionStyleType

Chrome 44 ขึ้นไป

ประเภทสไตล์

ค่าแจกแจง

"url"

"match"

"หรี่"

OnInputEnteredDisposition

Chrome 44 ขึ้นไป

การจัดการหน้าต่างสำหรับการค้นหาแถบอเนกประสงค์ นี่คือบริบทที่แนะนำในการแสดงผลลัพธ์ ตัวอย่างเช่น หากคำสั่งแถบอเนกประสงค์คือการไปยัง URL ที่เฉพาะเจาะจง การจัดการ "newForegroundTab" หมายความว่าการไปยังส่วนต่างๆ ควรเกิดขึ้นในแท็บใหม่ที่เลือก

ค่าแจกแจง

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

ผลการแนะนำ

พร็อพเพอร์ตี้

  • เนื้อหา

    สตริง

    ข้อความที่ใส่ในแถบ URL และส่งไปยังส่วนขยายเมื่อผู้ใช้เลือกรายการนี้

  • ลบได้

    บูลีน ไม่บังคับ

    Chrome 63 ขึ้นไป

    ผู้ใช้ลบผลการค้นหาที่แนะนำได้หรือไม่

  • คำอธิบาย

    สตริง

    ข้อความที่แสดงในเมนูแบบเลื่อนลงของ URL มีมาร์กอัปสไตล์ XML สำหรับการจัดรูปแบบได้ แท็กที่รองรับคือ "url" (สำหรับ URL ตามตัวอักษร), "match" (สำหรับไฮไลต์ข้อความที่ตรงกับคำค้นหาของผู้ใช้) และ "dim" (สำหรับข้อความช่วยเหลือแบบจาง) คุณสามารถฝังรูปแบบได้ เช่น การจับคู่ที่หรี่แสง คุณต้องหลีกเลี่ยงเอนทิตีที่กำหนดไว้ล่วงหน้า 5 รายการเพื่อแสดงเป็นข้อความ: stackoverflow.com/a/1091953/89484

เมธอด

setDefaultSuggestion()

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

ตั้งค่าคำอธิบายและการจัดรูปแบบสำหรับคำแนะนำเริ่มต้น คำแนะนำเริ่มต้นคือข้อความที่แสดงในแถวคำแนะนำแรกใต้แถบ URL

พารามิเตอร์

  • คำแนะนำ

    DefaultSuggestResult

    ออบเจ็กต์ SuggestResult บางส่วนที่ไม่มีพารามิเตอร์ "content"

  • callback

    function ไม่บังคับ

    Chrome 100 ขึ้นไป

    พารามิเตอร์ callback จะมีลักษณะดังนี้ 

    () => void

การคืนสินค้า

  • Promise<void>

    Chrome 100 ขึ้นไป

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

กิจกรรม

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,
)

ผู้ใช้ยอมรับสิ่งที่พิมพ์ลงในแถบอเนกประสงค์

พารามิเตอร์

  • callback

    ฟังก์ชัน

    พารามิเตอร์ callback จะมีลักษณะดังนี้ 

    (text: string, disposition: OnInputEnteredDisposition) => void

onInputStarted

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

ผู้ใช้เริ่มเซสชันการป้อนคีย์เวิร์ดโดยพิมพ์คีย์เวิร์ดของส่วนขยาย ระบบรับประกันว่าจะส่งเหตุการณ์นี้เพียงครั้งเดียวต่อเซสชันการป้อนข้อมูล และก่อนเหตุการณ์ onInputChanged ใดๆ

พารามิเตอร์

  • callback

    ฟังก์ชัน

    พารามิเตอร์ callback จะมีลักษณะดังนี้ 

    () => void