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

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

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 d ชุดไอคอนสามารถประกอบด้วย ข้อกำหนดไอคอนขนาดใดก็ได้ และ 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

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

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

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

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

enable()

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

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

พารามิเตอร์

  • tabId

    หมายเลข ไม่บังคับ

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

  • Callback

    ไม่บังคับ

    Chrome 67 ขึ้นไป

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

    () => void

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

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

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

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

getBadgeBackgroundColor()

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

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

พารามิเตอร์

  • รายละเอียด

    TabDetails

  • Callback

    ไม่บังคับ

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

    (result: ColorArray) => void

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

  • Promise&lt;ColorArray&gt;

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

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

getBadgeText()

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

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

พารามิเตอร์

  • รายละเอียด

    TabDetails

  • Callback

    ไม่บังคับ

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

    (result: string) => void

    • ผลลัพธ์

      สตริง

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

  • คำมั่นสัญญา<สตริง>

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

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

getPopup()

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

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

พารามิเตอร์

  • รายละเอียด

    TabDetails

  • Callback

    ไม่บังคับ

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

    (result: string) => void

    • ผลลัพธ์

      สตริง

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

  • คำมั่นสัญญา<สตริง>

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

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

getTitle()

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

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

พารามิเตอร์

  • รายละเอียด

    TabDetails

  • Callback

    ไม่บังคับ

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

    (result: string) => void

    • ผลลัพธ์

      สตริง

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

  • คำมั่นสัญญา<สตริง>

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

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

setBadgeBackgroundColor()

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

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

พารามิเตอร์

  • รายละเอียด

    ออบเจ็กต์

    • สี

      string | ColorArray

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

    • tabId

      หมายเลข ไม่บังคับ

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

  • Callback

    ไม่บังคับ

    Chrome 67 ขึ้นไป

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

    () => void

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

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

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

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

setBadgeText()

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

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

พารามิเตอร์

  • รายละเอียด

    ออบเจ็กต์

    • tabId

      หมายเลข ไม่บังคับ

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

    • ข้อความ

      string ไม่บังคับ

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

  • Callback

    ไม่บังคับ

    Chrome 67 ขึ้นไป

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

    () => void

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

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

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

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

setIcon()

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

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

พารามิเตอร์

  • รายละเอียด

    ออบเจ็กต์

    • ข้อมูลรูปภาพ

      ImageData | ออบเจ็กต์ไม่บังคับ

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

    • เส้นทาง

      string | ออบเจ็กต์ไม่บังคับ

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

    • tabId

      หมายเลข ไม่บังคับ

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

  • Callback

    ไม่บังคับ

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

    () => void

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

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

    Chrome 116 ขึ้นไป

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

setPopup()

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

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

พารามิเตอร์

  • รายละเอียด

    ออบเจ็กต์

    • ป๊อปอัป

      สตริง

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

    • tabId

      หมายเลข ไม่บังคับ

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

  • Callback

    ไม่บังคับ

    Chrome 67 ขึ้นไป

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

    () => void

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

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

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

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

setTitle()

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

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

พารามิเตอร์

  • รายละเอียด

    ออบเจ็กต์

    • tabId

      หมายเลข ไม่บังคับ

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

    • title

      สตริง

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

  • Callback

    ไม่บังคับ

    Chrome 67 ขึ้นไป

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

    () => void

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

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

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

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

กิจกรรม

onClicked

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

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    (tab: tabs.Tab) => void