chrome.browserAction

refresh date: 2026-09-25 robots: noindex

คำอธิบาย

ใช้การทำงานของเบราว์เซอร์เพื่อวางไอคอนในแถบเครื่องมือหลักของ 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 dip อย่างไรก็ตาม หากไม่ได้ระบุขนาดที่แน่นอน การปรับขนาดนี้อาจทำให้ไอคอนสูญเสียรายละเอียดหรือดูไม่ชัดเจน

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

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

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

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

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

ไอคอน

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

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

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

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

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

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

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

ป้าย

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

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

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

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

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

เคล็ดลับ

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

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

ตัวอย่าง

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

ประเภท

TabDetails

Chrome 88 ขึ้นไป

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

  • tabId

    number ไม่บังคับ

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

เมธอด

disable()

Promise 
chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
): Promise<void>

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

พารามิเตอร์

  • tabId

    number ไม่บังคับ

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

  • callback

    function ไม่บังคับ

    Chrome 67 ขึ้นไป

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

    () => void

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

  • Promise<void>

    Chrome 88 ขึ้นไป

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

enable()

Promise 
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
): Promise<void>

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

พารามิเตอร์

  • tabId

    number ไม่บังคับ

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

  • callback

    function ไม่บังคับ

    Chrome 67 ขึ้นไป

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

    () => void

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

  • Promise<void>

    Chrome 88 ขึ้นไป

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

getBadgeBackgroundColor()

Promise 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
): Promise<extensionTypes.ColorArray>

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

พารามิเตอร์

  • รายละเอียด

    TabDetails

  • callback

    function ไม่บังคับ

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

    (result: ColorArray) => void

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

  • Chrome 88 ขึ้นไป

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

getBadgeText()

Promise 
chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
): Promise<string>

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

พารามิเตอร์

  • รายละเอียด

    TabDetails

  • callback

    function ไม่บังคับ

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

    (result: string) => void

    • ผลลัพธ์

      สตริง

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

  • Promise<string>

    Chrome 88 ขึ้นไป

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

getPopup()

Promise 
chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
): Promise<string>

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

พารามิเตอร์

  • รายละเอียด

    TabDetails

  • callback

    function ไม่บังคับ

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

    (result: string) => void

    • ผลลัพธ์

      สตริง

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

  • Promise<string>

    Chrome 88 ขึ้นไป

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

getTitle()

Promise 
chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

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

พารามิเตอร์

  • รายละเอียด

    TabDetails

  • callback

    function ไม่บังคับ

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

    (result: string) => void

    • ผลลัพธ์

      สตริง

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

  • Promise<string>

    Chrome 88 ขึ้นไป

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

setBadgeBackgroundColor()

Promise 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
): Promise<void>

กำหนดสีพื้นหลังให้กับป้าย

พารามิเตอร์

  • รายละเอียด

    ออบเจ็กต์

    • สี

      string | ColorArray

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

    • tabId

      number ไม่บังคับ

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

  • callback

    function ไม่บังคับ

    Chrome 67 ขึ้นไป

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

    () => void

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

  • Promise<void>

    Chrome 88 ขึ้นไป

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

setBadgeText()

Promise 
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
): Promise<void>

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

พารามิเตอร์

  • รายละเอียด

    ออบเจ็กต์

    • tabId

      number ไม่บังคับ

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

    • ข้อความ

      สตริง ไม่บังคับ

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

  • callback

    function ไม่บังคับ

    Chrome 67 ขึ้นไป

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

    () => void

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

  • Promise<void>

    Chrome 88 ขึ้นไป

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

setIcon()

Promise 
chrome.browserAction.setIcon(
  details: object,
  callback?: function,
): Promise<void>

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

    • tabId

      number ไม่บังคับ

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

  • callback

    function ไม่บังคับ

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

    () => void

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

  • Promise<void>

    Chrome 116 ขึ้นไป

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

setPopup()

Promise 
chrome.browserAction.setPopup(
  details: object,
  callback?: function,
): Promise<void>

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

พารามิเตอร์

  • รายละเอียด

    ออบเจ็กต์

    • ป๊อปอัป

      สตริง

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

    • tabId

      number ไม่บังคับ

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

  • callback

    function ไม่บังคับ

    Chrome 67 ขึ้นไป

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

    () => void

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

  • Promise<void>

    Chrome 88 ขึ้นไป

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

setTitle()

Promise 
chrome.browserAction.setTitle(
  details: object,
  callback?: function,
): Promise<void>

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

พารามิเตอร์

  • รายละเอียด

    ออบเจ็กต์

    • tabId

      number ไม่บังคับ

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

    • title

      สตริง

      สตริงที่การทำงานของเบราว์เซอร์ควรแสดงเมื่อวางเมาส์เหนือ

  • callback

    function ไม่บังคับ

    Chrome 67 ขึ้นไป

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

    () => void

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

  • Promise<void>

    Chrome 88 ขึ้นไป

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

กิจกรรม

onClicked

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

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (tab: tabs.Tab) => void