chrome.browserAction

คำอธิบาย

ใช้การทำงานของเบราว์เซอร์เพื่อใส่ไอคอนในแถบเครื่องมือหลักของ Google Chrome ทางด้านขวาของแถบที่อยู่ นอกเหนือจากไอคอน การดำเนินการของเบราว์เซอร์อาจมีเคล็ดลับเครื่องมือ ป้าย และป๊อปอัป

ความพร้อมใช้งาน

≤ MV2

ในภาพต่อไปนี้ สี่เหลี่ยมจัตุรัสหลากสีทางด้านขวาของแถบที่อยู่คือไอคอนสำหรับการทำงานของเบราว์เซอร์ มีป๊อปอัปอยู่ใต้ไอคอน

หากต้องการสร้างไอคอนที่ไม่ได้ใช้งานเสมอไป ให้ใช้การทำงานของหน้าเว็บแทนการทำงานของเบราว์เซอร์

ไฟล์ Manifest

ลงทะเบียนการดำเนินการของเบราว์เซอร์ในไฟล์ Manifest ของส่วนขยายดังนี้

{
  "name": "My extension",
  ...
  "browser_action": {
    "default_icon": {                // optional
      "16": "images/icon16.png",     // optional
      "24": "images/icon24.png",     // optional
      "32": "images/icon32.png"      // optional
    },
    "default_title": "Google Mail",  // optional, shown in tooltip
    "default_popup": "popup.html"    // optional
  },
  ...
}

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

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

ระบบยังคงรองรับไวยากรณ์เดิมสำหรับการลงทะเบียนไอคอนเริ่มต้นดังนี้

{
  "name": "My extension",
  ...
  "browser_action": {
    ...
    "default_icon": "images/icon32.png"  // optional
    // equivalent to "default_icon": { "32": "images/icon32.png" }
  },
  ...
}

ส่วนต่างๆ ของ UI

การดำเนินการของเบราว์เซอร์อาจมีไอคอน เคล็ดลับเครื่องมือ ป้าย และป๊อปอัป

Icon

ไอคอนการดำเนินการของเบราว์เซอร์ใน Chrome มีความกว้างและสูง 16 ระดับ (พิกเซลที่ขึ้นอยู่กับอุปกรณ์) ไอคอนขนาดใหญ่จะปรับขนาดให้พอดี แต่เพื่อผลลัพธ์ที่ดีที่สุด ให้ใช้ไอคอนสี่เหลี่ยมจัตุรัสแบบ 16 องศา

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

ภาพนิ่งจะอยู่ในรูปแบบใดก็ได้ที่ WebKit แสดงได้ ซึ่งรวมถึง BMP, GIF, ICO, JPEG หรือ PNG สำหรับส่วนขยายที่คลายการแพคแล้ว รูปภาพจะต้องอยู่ในรูปแบบ PNG

หากต้องการตั้งค่าไอคอน ให้ใช้ช่อง default_icon ของ default_icon ในไฟล์ Manifest หรือเรียกใช้เมธอด browserAction.setIcon

หากต้องการแสดงไอคอนอย่างเหมาะสมเมื่อความหนาแน่นของพิกเซลหน้าจอ (อัตราส่วน size_in_pixel / size_in_dip) มากกว่า 1 คุณจะกำหนดไอคอนเป็นชุดรูปภาพที่มีขนาดต่างกันได้ ภาพจริงที่จะแสดงจะเลือกจากชุดให้พอดีกับขนาดพิกเซล 16 d0 ชุดไอคอนอาจมีข้อกำหนดเกี่ยวกับไอคอนขนาดใดก็ได้ และ Chrome จะเลือกไอคอนที่เหมาะสมที่สุด

เคล็ดลับเครื่องมือ

หากต้องการตั้งค่าเคล็ดลับเครื่องมือ ให้ใช้ช่อง default_title ของ default_title ในไฟล์ Manifest หรือเรียกใช้เมธอด browserAction.setTitle คุณระบุสตริงที่เจาะจงภาษาสำหรับช่อง default_title ได้ โปรดดูรายละเอียดในการทำให้เป็นสากล

ป้าย

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

ป้ายต้องมีพื้นที่จำกัด ป้ายจึงควรมีอักขระไม่เกิน 4 ตัว

กำหนดข้อความและสีของป้ายโดยใช้ browserAction.setBadgeText และ browserAction.setBadgeBackgroundColor ตามลำดับ

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

หากต้องการเพิ่มป๊อปอัปลงในการทำงานของเบราว์เซอร์ ให้สร้างไฟล์ HTML ที่มีเนื้อหาของป๊อปอัปนั้น ระบุไฟล์ HTML ในช่อง default_popup ของ default_popup ในไฟล์ Manifest หรือเรียกใช้เมธอด browserAction.setPopup

เคล็ดลับ

ทำตามหลักเกณฑ์ต่อไปนี้เพื่อให้ภาพโดดเด่นที่สุด

  • ควรใช้การดำเนินการของเบราว์เซอร์สำหรับฟีเจอร์ที่เหมาะสมกับหน้าเว็บส่วนใหญ่
  • อย่าใช้การดำเนินการของเบราว์เซอร์สำหรับฟีเจอร์ที่เหมาะสมกับหน้าเว็บเพียงไม่กี่หน้า ให้ใช้การดำเนินการของหน้าเว็บแทน
  • ควรใช้ไอคอนขนาดใหญ่สีสันสดใสที่ใช้พื้นที่ขนาด 16x16 ให้เกิดประโยชน์สูงสุด ไอคอนการทำงานของเบราว์เซอร์ควรใหญ่และหนักกว่าไอคอนการทำงานบนหน้าเว็บเล็กน้อย
  • อย่าพยายามเลียนแบบไอคอนเมนูขาวดำของ Google Chrome วิธีนี้ไม่ค่อยเหมาะกับธีม ดังนั้น ส่วนขยายจึงควรโดดเด่นขึ้น
  • ควรใช้ความโปร่งใสแบบอัลฟ่าเพื่อเพิ่มขอบที่นุ่มนวลให้กับไอคอน เนื่องจากผู้คนจำนวนมากใช้ธีม ไอคอนของคุณจึงควรดูดีบนสีพื้นหลังที่หลากหลาย
  • อย่าทำให้ไอคอนเคลื่อนไหวอยู่ตลอดเวลา มันน่ารำคาญ

ตัวอย่าง

ดูตัวอย่างง่ายๆ ของการใช้การดำเนินการของเบราว์เซอร์ได้ในไดเรกทอรี examples/api/browserAction สำหรับตัวอย่างอื่นๆ และความช่วยเหลือในการดูซอร์สโค้ด โปรดดูตัวอย่าง

ประเภท

ColorArray

ประเภท

[ตัวเลข, ตัวเลข, ตัวเลข]

ImageDataType

ข้อมูลพิกเซลสำหรับรูปภาพ ต้องเป็นออบเจ็กต์ ImageData เช่น จากองค์ประกอบ canvas

ประเภท

ImageData

TabDetails

Chrome เวอร์ชัน 88 ขึ้นไป

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

  • tabId

    ตัวเลข ไม่บังคับ

    รหัสของแท็บสถานะการค้นหา หากไม่มีการระบุแท็บ ระบบจะแสดงผลสถานะที่ไม่ใช่แท็บเฉพาะ

วิธีการ

disable()

สัญญา 
chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
)

ปิดใช้การทำงานของเบราว์เซอร์สำหรับแท็บ

พารามิเตอร์

  • tabId

    ตัวเลข ไม่บังคับ

    รหัสของแท็บที่จะแก้ไขการทำงานของเบราว์เซอร์

  • Callback

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

    Chrome เวอร์ชัน 67 ขึ้นไป

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

    ()=>void

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

  • Promise<void>

    Chrome เวอร์ชัน 88 ขึ้นไป

    Promiss รองรับเฉพาะไฟล์ Manifest V3 ขึ้นไป ส่วนแพลตฟอร์มอื่นๆ จะต้องใช้โค้ดเรียกกลับ

enable()

สัญญา 
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
)

เปิดใช้การทำงานของเบราว์เซอร์สำหรับแท็บ ค่าเริ่มต้นคือเปิดใช้

พารามิเตอร์

  • tabId

    ตัวเลข ไม่บังคับ

    รหัสของแท็บที่จะแก้ไขการทำงานของเบราว์เซอร์

  • Callback

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

    Chrome เวอร์ชัน 67 ขึ้นไป

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

    ()=>void

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

  • Promise<void>

    Chrome เวอร์ชัน 88 ขึ้นไป

    Promiss รองรับเฉพาะไฟล์ Manifest V3 ขึ้นไป ส่วนแพลตฟอร์มอื่นๆ จะต้องใช้โค้ดเรียกกลับ

getBadgeBackgroundColor()

สัญญา 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

เรียกดูสีพื้นหลังของการดำเนินการของเบราว์เซอร์

พารามิเตอร์

  • รายละเอียด

    TabDetails

  • Callback

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

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

    (result: ColorArray)=>void

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

  • Promise<ColorArray>

    Chrome เวอร์ชัน 88 ขึ้นไป

    Promiss รองรับเฉพาะไฟล์ Manifest V3 ขึ้นไป ส่วนแพลตฟอร์มอื่นๆ จะต้องใช้โค้ดเรียกกลับ

getBadgeText()

สัญญา 
chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
)

รับข้อความป้ายของการดำเนินการของเบราว์เซอร์ หากไม่มีการระบุแท็บ ระบบจะแสดงข้อความป้ายที่ไม่ใช่แท็บเฉพาะ

พารามิเตอร์

  • รายละเอียด

    TabDetails

  • Callback

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

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

    (result: string)=>void

    • ผลลัพธ์

      string

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

  • คำสัญญา<string>

    Chrome เวอร์ชัน 88 ขึ้นไป

    Promiss รองรับเฉพาะไฟล์ Manifest V3 ขึ้นไป ส่วนแพลตฟอร์มอื่นๆ จะต้องใช้โค้ดเรียกกลับ

getPopup()

สัญญา 
chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
)

รับเอกสาร HTML ที่ตั้งค่าเป็นป๊อปอัปสำหรับการดำเนินการของเบราว์เซอร์นี้

พารามิเตอร์

  • รายละเอียด

    TabDetails

  • Callback

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

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

    (result: string)=>void

    • ผลลัพธ์

      string

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

  • คำสัญญา<string>

    Chrome เวอร์ชัน 88 ขึ้นไป

    Promiss รองรับเฉพาะไฟล์ Manifest V3 ขึ้นไป ส่วนแพลตฟอร์มอื่นๆ จะต้องใช้โค้ดเรียกกลับ

getTitle()

สัญญา 
chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
)

รับชื่อของการดำเนินการของเบราว์เซอร์

พารามิเตอร์

  • รายละเอียด

    TabDetails

  • Callback

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

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

    (result: string)=>void

    • ผลลัพธ์

      string

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

  • คำสัญญา<string>

    Chrome เวอร์ชัน 88 ขึ้นไป

    Promiss รองรับเฉพาะไฟล์ Manifest V3 ขึ้นไป ส่วนแพลตฟอร์มอื่นๆ จะต้องใช้โค้ดเรียกกลับ

setBadgeBackgroundColor()

สัญญา 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

ตั้งค่าสีพื้นหลังของป้าย

พารามิเตอร์

  • รายละเอียด

    ออบเจ็กต์

    • สี

      สตริง|ColorArray

      อาร์เรย์ของจำนวนเต็ม 4 ตัวในช่วง 0-255 ที่ทำให้เกิดสี RGBA ของป้าย และอาจเป็นสตริงที่มีค่าสีฐานสิบหก CSS เช่น #FF0000 หรือ #F00 (สีแดง) แสดงสีที่ความทึบแสงสูงสุด

    • tabId

      ตัวเลข ไม่บังคับ

      จำกัดการเปลี่ยนแปลงไว้เฉพาะเมื่อมีการเลือกแท็บใดแท็บหนึ่ง รีเซ็ตโดยอัตโนมัติเมื่อแท็บปิดอยู่

  • Callback

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

    Chrome เวอร์ชัน 67 ขึ้นไป

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

    ()=>void

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

  • Promise<void>

    Chrome เวอร์ชัน 88 ขึ้นไป

    Promiss รองรับเฉพาะไฟล์ Manifest V3 ขึ้นไป ส่วนแพลตฟอร์มอื่นๆ จะต้องใช้โค้ดเรียกกลับ

setBadgeText()

สัญญา 
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
)

ตั้งค่าข้อความป้ายสำหรับการดำเนินการกับเบราว์เซอร์ โดยป้ายจะแสดงอยู่ที่ด้านบนของไอคอน

พารามิเตอร์

  • รายละเอียด

    ออบเจ็กต์

    • tabId

      ตัวเลข ไม่บังคับ

      จำกัดการเปลี่ยนแปลงไว้เฉพาะเมื่อมีการเลือกแท็บใดแท็บหนึ่ง รีเซ็ตโดยอัตโนมัติเมื่อแท็บปิดอยู่

    • ข้อความ

      string ไม่บังคับ

      สามารถส่งผ่านอักขระกี่ตัวก็ได้ แต่จะใช้พื้นที่ได้ประมาณ 4 ตัวเท่านั้น หากส่งสตริงว่าง ('') ข้อความป้ายจะถูกล้างออก หากระบุ tabId และ text เป็นค่าว่าง ระบบจะล้างข้อความของแท็บที่ระบุและใช้ข้อความป้ายส่วนกลางเป็นค่าเริ่มต้น

  • Callback

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

    Chrome เวอร์ชัน 67 ขึ้นไป

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

    ()=>void

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

  • Promise<void>

    Chrome เวอร์ชัน 88 ขึ้นไป

    Promiss รองรับเฉพาะไฟล์ Manifest V3 ขึ้นไป ส่วนแพลตฟอร์มอื่นๆ จะต้องใช้โค้ดเรียกกลับ

setIcon()

สัญญา 
chrome.browserAction.setIcon(
  details: object,
  callback?: function,
)

ตั้งค่าไอคอนสำหรับการทำงานของเบราว์เซอร์ ไอคอนสามารถระบุเป็นเส้นทางไปยังไฟล์ภาพ เป็นข้อมูลพิกเซลจากองค์ประกอบ Canvas หรือเป็นพจนานุกรมของหนึ่งในนั้น ต้องระบุพร็อพเพอร์ตี้ path หรือ imageData

พารามิเตอร์

  • รายละเอียด

    ออบเจ็กต์

    • imageData

      ImageData|object ไม่บังคับ

      เป็นวัตถุ ImageData หรือพจนานุกรม {size -> ImageData} แสดงไอคอนที่จะตั้งค่า หากระบุไอคอนเป็นพจนานุกรม ระบบจะเลือกรูปภาพที่ใช้ตามความหนาแน่นพิกเซลของหน้าจอ หากจำนวนพิกเซลรูปภาพที่พอดีกับหน่วยพื้นที่หน้าจอ 1 หน่วยเท่ากับ scale ระบบจะเลือกรูปภาพที่มีขนาด scale * n โดย n คือขนาดของไอคอนใน UI ต้องระบุรูปภาพอย่างน้อย 1 รูป โปรดทราบว่า 'details.imageData = foo' จะเหมือนกับ 'details.imageData = {'16': foo}'

    • เส้นทาง

      string|object ไม่บังคับ

      เส้นทางอิมเมจแบบสัมพัทธ์หรือพจนานุกรม {size -> related image path} ที่ชี้ไปยังไอคอน เพื่อตั้งค่า หากระบุไอคอนเป็นพจนานุกรม ระบบจะเลือกรูปภาพที่ใช้ตามความหนาแน่นพิกเซลของหน้าจอ หากจำนวนพิกเซลรูปภาพที่พอดีกับหน่วยพื้นที่หน้าจอ 1 หน่วยเท่ากับ scale ระบบจะเลือกรูปภาพที่มีขนาด scale * n โดย n คือขนาดของไอคอนใน UI ต้องระบุรูปภาพอย่างน้อย 1 รูป โปรดทราบว่า 'details.path = foo' จะเหมือนกับ 'details.path = {'16': foo}'

    • tabId

      ตัวเลข ไม่บังคับ

      จำกัดการเปลี่ยนแปลงไว้เฉพาะเมื่อมีการเลือกแท็บใดแท็บหนึ่ง รีเซ็ตโดยอัตโนมัติเมื่อแท็บปิดอยู่

  • Callback

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

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

    ()=>void

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

  • Promise<void>

    Chrome 116 ขึ้นไป

    Promiss รองรับเฉพาะไฟล์ Manifest V3 ขึ้นไป ส่วนแพลตฟอร์มอื่นๆ จะต้องใช้โค้ดเรียกกลับ

setPopup()

สัญญา 
chrome.browserAction.setPopup(
  details: object,
  callback?: function,
)

ตั้งค่าให้เปิดเอกสาร HTML เป็นป๊อปอัปเมื่อผู้ใช้คลิกไอคอนการทำงานของเบราว์เซอร์

พารามิเตอร์

  • รายละเอียด

    ออบเจ็กต์

    • ป๊อปอัป

      string

      เส้นทางที่เกี่ยวข้องไปยังไฟล์ HTML เพื่อแสดงในป๊อปอัป หากตั้งค่าเป็นสตริงว่างเปล่า ('') ระบบจะไม่แสดงป๊อปอัป

    • tabId

      ตัวเลข ไม่บังคับ

      จำกัดการเปลี่ยนแปลงไว้เฉพาะเมื่อมีการเลือกแท็บใดแท็บหนึ่ง รีเซ็ตโดยอัตโนมัติเมื่อแท็บปิดอยู่

  • Callback

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

    Chrome เวอร์ชัน 67 ขึ้นไป

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

    ()=>void

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

  • Promise<void>

    Chrome เวอร์ชัน 88 ขึ้นไป

    Promiss รองรับเฉพาะไฟล์ Manifest V3 ขึ้นไป ส่วนแพลตฟอร์มอื่นๆ จะต้องใช้โค้ดเรียกกลับ

setTitle()

สัญญา 
chrome.browserAction.setTitle(
  details: object,
  callback?: function,
)

ตั้งชื่อการทำงานของเบราว์เซอร์ ชื่อนี้จะปรากฏในเคล็ดลับเครื่องมือ

พารามิเตอร์

  • รายละเอียด

    ออบเจ็กต์

    • tabId

      ตัวเลข ไม่บังคับ

      จำกัดการเปลี่ยนแปลงไว้เฉพาะเมื่อมีการเลือกแท็บใดแท็บหนึ่ง รีเซ็ตโดยอัตโนมัติเมื่อแท็บปิดอยู่

    • title

      string

      สตริงที่เบราว์เซอร์จะแสดงเมื่อวางเมาส์เหนือ

  • Callback

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

    Chrome เวอร์ชัน 67 ขึ้นไป

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

    ()=>void

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

  • Promise<void>

    Chrome เวอร์ชัน 88 ขึ้นไป

    Promiss รองรับเฉพาะไฟล์ Manifest V3 ขึ้นไป ส่วนแพลตฟอร์มอื่นๆ จะต้องใช้โค้ดเรียกกลับ

กิจกรรม

onClicked

chrome.browserAction.onClicked.addListener(
  callback: function,
)

เริ่มทำงานเมื่อมีการคลิกไอคอนการทำงานของเบราว์เซอร์ ไม่เริ่มทำงานหากการทำงานของเบราว์เซอร์มีป๊อปอัป

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    (tab: tabs.Tab)=>void