chrome.omnibox

คำอธิบาย

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

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

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

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

ไฟล์ Manifest

คุณต้องประกาศคีย์ต่อไปนี้ในไฟล์ Manifest เพื่อใช้ API นี้

"omnibox"

คุณต้องรวมฟิลด์ "omnibox.keyword" ในไฟล์ Manifest เพื่อใช้ API ของแถบอเนกประสงค์ คุณ ควรระบุไอคอนขนาด 16 x 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 ของแถบอเนกประสงค์จาก chrome-extension-samples ที่เก็บได้

ประเภท

DefaultSuggestResult

ผลการค้นหาที่แนะนำ

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

  • คำอธิบาย

    สตริง

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

DescriptionStyleType

Chrome 44 ขึ้นไป

ประเภทสไตล์

ค่าแจกแจง

"url"

"match"

"หรี่"

OnInputEnteredDisposition

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

ผลการค้นหาที่แนะนำ

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

  • เนื้อหา

    สตริง

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

  • ลบได้

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

    Chrome 63 ขึ้นไป

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

  • คำอธิบาย

    สตริง

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

เมธอด

setDefaultSuggestion()

สัญญา 
chrome.omnibox.setDefaultSuggestion(
  suggestion: DefaultSuggestResult,
  callback?: function,
)

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

พารามิเตอร์

  • คำแนะนำ

    DefaultSuggestResult

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

  • Callback

    ไม่บังคับ

    Chrome 100 ขึ้นไป

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

    () => void

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

  • คำมั่นสัญญา<โมฆะ>

    Chrome 100 ขึ้นไป

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง 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