chrome.contextMenus

คำอธิบาย

ใช้ chrome.contextMenus API เพื่อเพิ่มรายการลงในเมนูบริบทของ Google Chrome คุณเลือกประเภทของออบเจ็กต์ที่จะใช้เมนูตามบริบทเพิ่มเติมได้ เช่น รูปภาพ ไฮเปอร์ลิงก์ และหน้าเว็บ

สิทธิ์

contextMenus

คุณต้องประกาศสิทธิ์ "contextMenus" ในไฟล์ Manifest ของส่วนขยายจึงจะใช้ API ได้ นอกจากนี้ คุณควรระบุไอคอนขนาด 16 x 16 พิกเซลเพื่อแสดงข้างรายการเมนู เช่น

{
  "name": "My extension",
  ...
  "permissions": [
    "contextMenus"
  ],
  "icons": {
    "16": "icon-bitty.png",
    "48": "icon-small.png",
    "128": "icon-large.png"
  },
  ...
}

แนวคิดและการใช้งาน

รายการเมนูบริบทจะปรากฏในเอกสารใดก็ได้ (หรือเฟรมภายในเอกสาร) แม้แต่เอกสารที่มี URL รูปแบบ file:// หรือ chrome:// หากต้องการควบคุมเอกสารที่รายการจะปรากฏ ให้ระบุช่อง documentUrlPatterns เมื่อเรียกใช้เมธอด create() หรือ update()

คุณสร้างรายการเมนูตามบริบทได้เท่าที่ต้องการ แต่หากมีรายการจากส่วนขยายปรากฏขึ้นมากกว่า 1 รายการพร้อมกัน Google Chrome จะยุบรายการเหล่านั้นเป็นเมนูหลักรายการเดียวโดยอัตโนมัติ

ตัวอย่าง

หากต้องการลองใช้ API นี้ ให้ติดตั้งตัวอย่าง contextMenus API จากที่เก็บchrome-extension-samples

ประเภท

ContextType

Chrome 44 ขึ้นไป

บริบทต่างๆ ที่เมนูอาจปรากฏ การระบุ "all" เทียบเท่ากับการรวมบริบทอื่นๆ ทั้งหมดยกเว้น "launcher" บริบท "launcher" รองรับเฉพาะแอปเท่านั้นและใช้เพื่อเพิ่มรายการเมนูลงในเมนูตามบริบทที่ปรากฏขึ้นเมื่อคลิกไอคอนแอปใน Launcher/แถบงาน/แท่นชาร์จ/ฯลฯ แพลตฟอร์มต่างๆ อาจมีข้อจำกัดเกี่ยวกับสิ่งที่รองรับในเมนูตามบริบทของ Launcher

ค่าแจกแจง

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

"launcher"

"browser_action"

"page_action"

"action"

CreateProperties

Chrome 123 ขึ้นไป

คุณสมบัติของรายการในเมนูตามบริบทใหม่

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

  • เลือกไว้

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

    สถานะเริ่มต้นของช่องทําเครื่องหมายหรือปุ่มตัวเลือก: true สำหรับเลือกไว้ false สำหรับไม่ได้เลือก โดยเลือกปุ่มตัวเลือกได้เพียงทีละปุ่มในกลุ่มหนึ่งๆ เท่านั้น

  • บริบท

    [ContextType, ...ContextType[]] ไม่บังคับ

    รายการบริบทที่รายการเมนูนี้จะปรากฏ ค่าเริ่มต้นคือ ['page']

  • documentUrlPatterns

    string[] ไม่บังคับ

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

  • เปิดใช้อยู่

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

    รายการในเมนูตามบริบทนี้เปิดใช้หรือปิดใช้ ค่าเริ่มต้นคือ true

  • id

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

    รหัสที่ไม่ซ้ำกันที่จะกำหนดให้กับรายการนี้ ต้องระบุสำหรับหน้ากิจกรรม ต้องไม่เหมือนกับรหัสอื่นสำหรับส่วนขยายนี้

  • parentId

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

    รหัสของรายการเมนูหลัก ซึ่งจะทำให้รายการนี้เป็นรายการย่อยของรายการที่เพิ่มไว้ก่อนหน้านี้

  • targetUrlPatterns

    string[] ไม่บังคับ

    คล้ายกับ documentUrlPatterns ตัวกรองที่อิงตามแอตทริบิวต์ src ของแท็ก img, audio และ video และแอตทริบิวต์ href ของแท็ก a

  • title

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

    ข้อความที่จะแสดงในรายการ ต้องระบุ เว้นแต่ type จะเท่ากับ separator เมื่อบริบทคือ selection ให้ใช้ %s ภายในสตริงเพื่อแสดงข้อความที่เลือก เช่น หากค่าของพารามิเตอร์นี้คือ "แปล "%s" เป็นภาษาพิกลิก" และผู้ใช้เลือกคำว่า "เจ๋ง" รายการในเมนูบริบทสำหรับการเลือกจะเป็น "แปล "เจ๋ง" เป็นภาษาพิกลิก"

  • ประเภท

    ItemType ไม่บังคับ

    ประเภทของรายการในเมนู ค่าเริ่มต้นคือ normal

  • มองเห็นได้

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

    รายการจะแสดงในเมนูหรือไม่

  • onclick

    void ไม่บังคับ

    ฟังก์ชันที่เรียกกลับเมื่อมีการคลิกรายการเมนู การดำเนินการนี้ไม่พร้อมใช้งานภายใน Service Worker คุณควรลงทะเบียน Listener สำหรับ contextMenus.onClicked แทน

    ฟังก์ชัน onclick มีรูปแบบดังนี้ 

    (info: OnClickData, tab: Tab) => {...}

    • ข้อมูล

      OnClickData

      ข้อมูลเกี่ยวกับรายการที่คลิกและบริบทที่เกิดคลิก

    • แท็บ

      แท็บ

      รายละเอียดของแท็บที่มีการคลิก ไม่มีพารามิเตอร์นี้สําหรับแอปแพลตฟอร์ม

ItemType

Chrome 44 ขึ้นไป

ประเภทของรายการในเมนู

ค่าแจกแจง

"normal"

"checkbox"

"radio"

"separator"

OnClickData

ข้อมูลที่ส่งเมื่อมีการคลิกรายการในเมนูตามบริบท

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

  • เลือกไว้

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

    การแจ้งที่ระบุสถานะของช่องทําเครื่องหมายหรือรายการตัวเลือกหลังจากมีการคลิก

  • แก้ไขได้

    บูลีน

    การแจ้งที่ระบุว่าองค์ประกอบแก้ไขได้หรือไม่ (การป้อนข้อความ, textarea ฯลฯ)

  • frameId

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

    Chrome 51 ขึ้นไป

    รหัสของเฟรมขององค์ประกอบที่มีการคลิกเมนูตามบริบท หากอยู่ในเฟรม

  • frameUrl

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

    URL ของเฟรมขององค์ประกอบที่มีการคลิกเมนูตามบริบท หากอยู่ในเฟรม

  • linkUrl

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

    หากองค์ประกอบเป็นลิงก์ ให้ระบุ URL ที่ลิงก์ชี้ไป

  • mediaType

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

    "รูปภาพ" "วิดีโอ" หรือ "เสียง" รายการใดรายการหนึ่ง หากเปิดใช้งานเมนูตามบริบทในองค์ประกอบประเภทใดประเภทหนึ่งเหล่านี้

  • menuItemId

    สตริง | ตัวเลข

    รหัสของรายการเมนูที่มีการคลิก

  • pageUrl

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

    URL ของหน้าเว็บที่มีการคลิกรายการเมนู ระบบจะไม่ตั้งค่าพร็อพเพอร์ตี้นี้หากการคลิกเกิดขึ้นในบริบทที่ไม่มีหน้าปัจจุบัน เช่น ในเมนูบริบทของ Launcher

  • parentMenuItemId

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

    รหัสหลักของรายการที่คลิก (หากมี)

  • selectionText

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

    ข้อความสําหรับการเลือกบริบท (หากมี)

  • srcUrl

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

    จะแสดงสําหรับองค์ประกอบที่มี URL "src"

  • wasChecked

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

    การแจ้งที่ระบุสถานะของช่องทําเครื่องหมายหรือรายการตัวเลือกก่อนที่จะมีการคลิก

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

ACTION_MENU_TOP_LEVEL_LIMIT

จํานวนสูงสุดของรายการชิ้นงานระดับบนสุดที่เพิ่มลงในเมนูบริบทของการดําเนินการของชิ้นงานได้ ระบบจะไม่คำนึงถึงรายการที่เกินขีดจำกัดนี้

ค่า

6

เมธอด

create()

chrome.contextMenus.create(
  createProperties: CreateProperties,
  callback?: function,
)

สร้างรายการเมนูตามบริบทใหม่ หากเกิดข้อผิดพลาดระหว่างการสร้าง ระบบอาจไม่ตรวจพบจนกว่าการเรียกกลับการสร้างจะเริ่มต้นขึ้น รายละเอียดจะอยู่ใน runtime.lastError

พารามิเตอร์

  • createProperties

    CreateProperties

  • Callback

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

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

    () => void

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

  • ตัวเลข | สตริง

    รหัสของสินค้าที่สร้างขึ้นใหม่

remove()

สัญญา 
chrome.contextMenus.remove(
  menuItemId: string | number,
  callback?: function,
)

นำรายการเมนูตามบริบทออก

พารามิเตอร์

  • menuItemId

    สตริง | ตัวเลข

    รหัสของรายการเมนูตามบริบทที่จะนำออก

  • Callback

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

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

    () => void

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

  • Promise<void>

    Chrome 123 ขึ้นไป

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

removeAll()

สัญญา 
chrome.contextMenus.removeAll(
  callback?: function,
)

นำรายการเมนูตามบริบททั้งหมดที่ส่วนขยายนี้เพิ่มออก

พารามิเตอร์

  • Callback

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

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

    () => void

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

  • Promise<void>

    Chrome 123 ขึ้นไป

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

update()

สัญญา 
chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
  callback?: function,
)

อัปเดตรายการเมนูตามบริบทที่สร้างไว้ก่อนหน้านี้

พารามิเตอร์

  • id

    สตริง | ตัวเลข

    รหัสของรายการที่จะอัปเดต

  • updateProperties

    ออบเจ็กต์

    พร็อพเพอร์ตี้ที่จะอัปเดต ยอมรับค่าเดียวกับฟังก์ชัน contextMenus.create

    • เลือกไว้

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

    • บริบท

      [ContextType, ...ContextType[]] ไม่บังคับ

    • documentUrlPatterns

      string[] ไม่บังคับ

    • เปิดใช้อยู่

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

    • parentId

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

      รหัสของรายการที่จะทําให้เป็นรายการหลักของรายการนี้ หมายเหตุ: คุณไม่สามารถตั้งค่ารายการให้กลายเป็นรายการย่อยของรายการที่สืบทอดมาเอง

    • targetUrlPatterns

      string[] ไม่บังคับ

    • title

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

    • ประเภท

      ItemType ไม่บังคับ

    • มองเห็นได้

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

      Chrome 62 ขึ้นไป

      รายการจะแสดงในเมนูหรือไม่

    • onclick

      void ไม่บังคับ

      ฟังก์ชัน onclick มีรูปแบบดังนี้ 

      (info: OnClickData, tab: Tab) => {...}

      • ข้อมูล

        OnClickData

        Chrome 44 ขึ้นไป
      • แท็บ

        แท็บ

        Chrome 44 ขึ้นไป

        รายละเอียดของแท็บที่มีการคลิก ไม่มีพารามิเตอร์นี้สําหรับแอปแพลตฟอร์ม

  • Callback

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

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

    () => void

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

  • Promise<void>

    Chrome 123 ขึ้นไป

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

กิจกรรม

onClicked

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

เริ่มทํางานเมื่อมีการคลิกรายการในเมนูตามบริบท

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    (info: OnClickData, tab?: tabs.Tab) => void