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-sample

ประเภท

DefaultSuggestResult

ผลลัพธ์ที่แนะนำ

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

  • คำอธิบาย

    string

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

DescriptionStyleType

Chrome 44 ขึ้นไป

ประเภทสไตล์

ค่าแจกแจง

"url"

OnInputEnteredDisposition

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

ผลลัพธ์ที่แนะนำ

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

  • คอนเทนต์

    string

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

  • ลบได้

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

    Chrome 63 ขึ้นไป

    ผู้ใช้สามารถลบผลลัพธ์ของคำแนะนำได้หรือไม่

  • คำอธิบาย

    string

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

วิธีการ

setDefaultSuggestion()

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

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

พารามิเตอร์

  • คำแนะนำ

    DefaultSuggestResult

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

  • Callback

    ฟังก์ชัน ไม่บังคับ

    Chrome 100 ขึ้นไป

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

    ()=>void

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

  • Promise<void>

    Chrome 100 ขึ้นไป

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

กิจกรรม

onDeleteSuggestion

Chrome 63 ขึ้นไป 
chrome.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

ผู้ใช้ได้ลบผลลัพธ์ที่แนะนำแล้ว

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    (text: string)=>void

    • ข้อความ

      string

onInputCancelled

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

ผู้ใช้สิ้นสุดเซสชันการป้อนคีย์เวิร์ดโดยไม่ยอมรับอินพุต

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    ()=>void

onInputChanged

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

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

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

    • ข้อความ

      string

    • แนะนำ

      ฟังก์ชัน

      พารามิเตอร์ 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