chrome.contentSettings

คำอธิบาย

ใช้ chrome.contentSettings API เพื่อเปลี่ยนการตั้งค่าที่ควบคุมว่าเว็บไซต์จะสามารถใช้ฟีเจอร์อย่างคุกกี้, JavaScript และปลั๊กอินได้หรือไม่ โดยทั่วไปแล้ว การตั้งค่าเนื้อหาจะช่วยให้คุณปรับแต่งลักษณะการทำงานของ Chrome ในแต่ละเว็บไซต์แทนที่จะเป็นการตั้งค่าทั่วโลก

สิทธิ์

contentSettings

คุณต้องประกาศสิทธิ์ "contentSettings" ในไฟล์ Manifest ของส่วนขยายเพื่อใช้ API เช่น

{   "name": "My extension",   ...   "permissions": [     "contentSettings"   ],   ... }

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

รูปแบบการตั้งค่าเนื้อหา

คุณใช้รูปแบบเพื่อระบุเว็บไซต์ที่การตั้งค่าเนื้อหาแต่ละรายการมีผลได้ เช่น https://*.youtube.com/* ระบุ youtube.com และโดเมนย่อยทั้งหมด ไวยากรณ์สำหรับรูปแบบการตั้งค่าเนื้อหา จะเหมือนกับรูปแบบการจับคู่ โดยมีความแตกต่างกันเล็กน้อย ดังนี้

  • สำหรับ URL http, https และ ftp เส้นทางต้องเป็นไวลด์การ์ด (/*) สำหรับ URL file ต้องระบุเส้นทางให้ครบถ้วนและต้องไม่มีไวลด์การ์ด
  • รูปแบบการตั้งค่าเนื้อหาจะระบุหมายเลขพอร์ตได้ ซึ่งแตกต่างจากรูปแบบการจับคู่ หากระบุหมายเลขพอร์ต รูปแบบจะตรงกับเว็บไซต์ที่มีพอร์ตนั้นเท่านั้น หากไม่ได้ระบุหมายเลขพอร์ต รูปแบบจะตรงกับพอร์ตทั้งหมด

ลำดับความสำคัญของรูปแบบ

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

ตัวอย่างเช่น รูปแบบต่อไปนี้จะเรียงตามลำดับความสำคัญ

  1. https://www.example.com/*
  2. https://*.example.com/* (ตรงกับ example.com และโดเมนย่อยทั้งหมด)
  3. <all_urls> (จับคู่ทุก URL)

ไวลด์การ์ด 3 ประเภทมีผลต่อความเฉพาะเจาะจงของรูปแบบ ดังนี้

  • ไวลด์การ์ดในพอร์ต (เช่น https://www.example.com:*/*)
  • ไวลด์การ์ดในสคีมา (เช่น *://www.example.com:123/*)
  • ไวลด์การ์ดในชื่อโฮสต์ (เช่น https://*.example.com:123/*)

หากรูปแบบหนึ่งมีความเฉพาะเจาะจงมากกว่าอีกรูปแบบหนึ่งในส่วนหนึ่ง แต่มีความเฉพาะเจาะจงน้อยกว่าในอีกส่วน ระบบจะตรวจสอบส่วนต่างๆ ตามลำดับต่อไปนี้ ชื่อโฮสต์ รูปแบบ พอร์ต ตัวอย่างเช่น รูปแบบต่อไปนี้จะเรียงตามลำดับความสำคัญ

  1. https://www.example.com:*/* ระบุชื่อโฮสต์และรูปแบบ
  2. *:/www.example.com:123/* ไม่สูงเท่า เนื่องจากแม้จะระบุชื่อโฮสต์ แต่ก็ไม่ได้ระบุรูปแบบ
  3. https://*.example.com:123/* ต่ำกว่าเนื่องจากแม้ว่าจะระบุพอร์ตและรูปแบบ แต่ก็มีอักขระไวด์การ์ดในชื่อโฮสต์

รูปแบบหลักและรูปแบบรอง

URL ที่นำมาพิจารณาเมื่อตัดสินใจเลือกการตั้งค่าเนื้อหาที่จะใช้จะขึ้นอยู่กับประเภทเนื้อหา เช่น การตั้งค่าสำหรับ contentSettings.notifications จะอิงตาม URL ที่แสดงใน แถบอเนกประสงค์ URL นี้เรียกว่า URL "หลัก"

เนื้อหาบางประเภทอาจพิจารณา URL เพิ่มเติม ตัวอย่างเช่น การอนุญาตให้เว็บไซต์ ตั้งค่า contentSettings.cookies จะพิจารณาจาก URL ของคำขอ HTTP (ซึ่งเป็น URL หลักในกรณีนี้) รวมถึง URL ที่แสดงในแถบอเนกประสงค์ (ซึ่งเรียกว่า URL "รอง")

หากกฎหลายข้อมีรูปแบบหลักและรูปแบบรอง กฎที่มีรูปแบบหลัก ที่เฉพาะเจาะจงกว่าจะมีลำดับความสำคัญสูงกว่า หากมีหลายกฎที่มีรูปแบบหลักเหมือนกัน กฎที่มีรูปแบบรองที่เฉพาะเจาะจงกว่าจะมีลำดับความสำคัญสูงกว่า ตัวอย่างเช่น รายการคู่รูปแบบหลัก/รองต่อไปนี้จะเรียงตามลำดับความสำคัญ

ลำดับความสำคัญรูปแบบหลักรูปแบบรอง
1https://www.moose.com/*https://www.wombat.com/*
2https://www.moose.com/*<all_urls>
3<all_urls>https://www.wombat.com/*
4<all_urls><all_urls>

การตั้งค่าเนื้อหารูปภาพไม่รองรับรูปแบบรอง

ตัวระบุทรัพยากร

ตัวระบุทรัพยากรช่วยให้คุณระบุการตั้งค่าเนื้อหาสำหรับประเภทย่อยที่เฉพาะเจาะจงของประเภทเนื้อหาได้ ปัจจุบันมีเพียงเนื้อหาประเภท contentSettings.plugins เท่านั้นที่รองรับตัวระบุทรัพยากร โดยตัวระบุทรัพยากรจะระบุปลั๊กอินที่เฉพาะเจาะจง เมื่อใช้การตั้งค่าเนื้อหา ระบบจะตรวจสอบ การตั้งค่าสำหรับปลั๊กอินที่เฉพาะเจาะจงก่อน หากไม่พบการตั้งค่าสำหรับปลั๊กอินที่เฉพาะเจาะจง ระบบจะตรวจสอบการตั้งค่าเนื้อหาทั่วไปสำหรับปลั๊กอิน

เช่น หากกฎการตั้งค่าเนื้อหามีตัวระบุทรัพยากร adobe-flash-player และรูปแบบ <all_urls> กฎดังกล่าวจะมีความสำคัญเหนือกว่ากฎที่ไม่มีตัวระบุทรัพยากรและรูปแบบ https://www.example.com/* แม้ว่ารูปแบบนั้นจะมีความเฉพาะเจาะจงมากกว่าก็ตาม

คุณดูรายการตัวระบุทรัพยากรสำหรับเนื้อหาประเภทหนึ่งๆ ได้โดยเรียกใช้เมธอด contentSettings.ContentSetting.getResourceIdentifiers() รายการที่แสดงอาจเปลี่ยนแปลงได้ตามชุดปลั๊กอินที่ติดตั้งในเครื่องของผู้ใช้ แต่ Chrome จะพยายามรักษาตัวระบุให้คงที่ ในการอัปเดตปลั๊กอิน

ตัวอย่าง

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

ประเภท

AutoVerifyContentSetting

Chrome 113 ขึ้นไป

ค่าแจกแจง

"allow"

"block"

CameraContentSetting

Chrome 46 ขึ้นไป

ค่าแจกแจง

"allow"

"block"

"ask"

ClipboardContentSetting

Chrome 121 ขึ้นไป

ค่าแจกแจง

"allow"

"block"

"ask"

ContentSetting

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

  • ล้าง

    เป็นโมฆะ

    ล้างกฎการตั้งค่าเนื้อหาทั้งหมดที่ส่วนขยายนี้ตั้งไว้

    ฟังก์ชัน clear มีลักษณะดังนี้ 

    (details: object) => {...}

    • รายละเอียด

      ออบเจ็กต์

      • ขอบเขต

        ขอบเขต ไม่บังคับ

        ตำแหน่งที่จะล้างการตั้งค่า (ค่าเริ่มต้น: ปกติ)

    • returns

      Promise<void>

      Chrome 96 ขึ้นไป
  • รับ

    เป็นโมฆะ

    รับการตั้งค่าเนื้อหาปัจจุบันสำหรับ URL 2 รายการที่ระบุ

    ฟังก์ชัน get มีลักษณะดังนี้ 

    (details: object) => {...}

    • รายละเอียด

      ออบเจ็กต์

      • ไม่ระบุตัวตน

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

        ว่าจะตรวจสอบการตั้งค่าเนื้อหาสำหรับเซสชันส่วนตัวหรือไม่ (ค่าเริ่มต้นเป็นเท็จ)

      • primaryUrl

        สตริง

        URL หลักที่ควรดึงการตั้งค่าเนื้อหา โปรดทราบว่าความหมายของ URL หลักจะขึ้นอยู่กับประเภทเนื้อหา

      • resourceIdentifier

        ResourceIdentifier ไม่บังคับ

        ตัวระบุที่เจาะจงมากขึ้นของประเภทเนื้อหาที่ควรดึงการตั้งค่า

      • secondaryUrl

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

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

    • returns

      Promise<object>

      Chrome 96 ขึ้นไป
  • getResourceIdentifiers

    เป็นโมฆะ

    ฟังก์ชัน getResourceIdentifiers มีลักษณะดังนี้ 

    () => {...}

  • ตั้งค่า

    เป็นโมฆะ

    ใช้กฎการตั้งค่าเนื้อหาใหม่

    ฟังก์ชัน set มีลักษณะดังนี้ 

    (details: object) => {...}

    • รายละเอียด

      ออบเจ็กต์

      • primaryPattern

        สตริง

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

      • resourceIdentifier

        ResourceIdentifier ไม่บังคับ

        ตัวระบุทรัพยากรสำหรับประเภทเนื้อหา

      • ขอบเขต

        ขอบเขต ไม่บังคับ

        ตำแหน่งที่จะตั้งค่า (ค่าเริ่มต้น: ปกติ)

      • secondaryPattern

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

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

      • การตั้งค่า

        ใดๆ

        การตั้งค่าที่ใช้โดยกฎนี้ ดูค่าที่เป็นไปได้ในคำอธิบายของออบเจ็กต์ ContentSetting แต่ละรายการ

    • returns

      Promise<void>

      Chrome 96 ขึ้นไป

CookiesContentSetting

Chrome 44 ขึ้นไป

ค่าแจกแจง

"allow"

"block"

"session_only"

FullscreenContentSetting

Chrome 44 ขึ้นไป

ค่า

"allow"

ImagesContentSetting

Chrome 44 ขึ้นไป

ค่าแจกแจง

"allow"

"block"

JavascriptContentSetting

Chrome 44 ขึ้นไป

ค่าแจกแจง

"allow"

"block"

LocationContentSetting

Chrome 44 ขึ้นไป

ค่าแจกแจง

"allow"

"block"

"ask"

MicrophoneContentSetting

Chrome 46 ขึ้นไป

ค่าแจกแจง

"allow"

"block"

"ask"

MouselockContentSetting

Chrome 44 ขึ้นไป

ค่า

"allow"

MultipleAutomaticDownloadsContentSetting

Chrome 44 ขึ้นไป

ค่าแจกแจง

"allow"

"block"

"ask"

NotificationsContentSetting

Chrome 44 ขึ้นไป

ค่าแจกแจง

"allow"

"block"

"ask"

PluginsContentSetting

Chrome 44 ขึ้นไป

ค่า

"block"

PopupsContentSetting

Chrome 44 ขึ้นไป

ค่าแจกแจง

"allow"

"block"

PpapiBrokerContentSetting

Chrome 44 ขึ้นไป

ค่า

"block"

ResourceIdentifier

ประเภทเนื้อหาเดียวที่ใช้ตัวระบุทรัพยากรคือ contentSettings.plugins ดูข้อมูลเพิ่มเติมได้ที่ตัวระบุทรัพยากร

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

  • คำอธิบาย

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

    คำอธิบายทรัพยากรที่มนุษย์อ่านได้

  • id

    สตริง

    ตัวระบุทรัพยากรสำหรับประเภทเนื้อหาที่ระบุ

Scope

Chrome 44 ขึ้นไป

ขอบเขตของ ContentSetting อย่างใดอย่างหนึ่งต่อไปนี้ regular: การตั้งค่าสำหรับโปรไฟล์ปกติ (ซึ่งโปรไฟล์ไม่ระบุตัวตนจะรับค่ามาหากไม่ได้ลบล้างที่อื่น) incognito\_session\_only: การตั้งค่าสำหรับโปรไฟล์ไม่ระบุตัวตนซึ่งตั้งค่าได้เฉพาะในเซสชันไม่ระบุตัวตนและจะถูกลบเมื่อเซสชันไม่ระบุตัวตนสิ้นสุดลง (ลบล้างการตั้งค่าปกติ)

ค่าแจกแจง

"regular"

"incognito_session_only"

SoundContentSetting

รอดำเนินการ

ค่าแจกแจง

"allow"

"block"

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

automaticDownloads

เลือกว่าจะอนุญาตให้เว็บไซต์ดาวน์โหลดไฟล์หลายไฟล์โดยอัตโนมัติหรือไม่ ตัวเลือกใดตัวเลือกหนึ่งต่อไปนี้ allow: อนุญาตให้เว็บไซต์ดาวน์โหลดหลายไฟล์โดยอัตโนมัติ block: ไม่อนุญาตให้เว็บไซต์ดาวน์โหลดหลายไฟล์โดยอัตโนมัติ ask: ถามเมื่อเว็บไซต์ต้องการดาวน์โหลดไฟล์โดยอัตโนมัติหลังจากไฟล์แรก ค่าเริ่มต้นคือ ask URL หลักคือ URL ของเฟรมระดับบนสุด ระบบจะไม่ใช้ URL รอง

ประเภท

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

Chrome 113 ขึ้นไป

เลือกว่าจะอนุญาตให้เว็บไซต์ใช้ Private State Tokens API หรือไม่ อย่างใดอย่างหนึ่ง allow: อนุญาตให้เว็บไซต์ใช้ Private State Tokens API block: บล็อกไม่ให้เว็บไซต์ใช้ Private State Tokens API ค่าเริ่มต้นคือ allow เมื่อเรียกใช้ set() รูปแบบ URL หลักต้องเป็น <all_urls> ระบบจะไม่ใช้ URL รอง

ประเภท

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46 ขึ้นไป

ว่าจะอนุญาตให้เว็บไซต์เข้าถึงกล้องหรือไม่ ตัวเลือกมีดังนี้ allow: อนุญาตให้เว็บไซต์เข้าถึงกล้อง block: ไม่อนุญาตให้เว็บไซต์เข้าถึงกล้อง ask: ถามเมื่อเว็บไซต์ต้องการเข้าถึงกล้อง ค่าเริ่มต้นคือ ask URL หลักคือ URL ของเอกสารที่ขอสิทธิ์เข้าถึงกล้อง ระบบจะไม่ใช้ URL รอง หมายเหตุ: การตั้งค่า "อนุญาต" จะไม่ถูกต้องหากทั้ง 2 รูปแบบเป็น "<all_urls>"

ประเภท

ContentSetting<CameraContentSetting>

clipboard

Chrome 121 ขึ้นไป

ไม่ว่าจะอนุญาตให้เว็บไซต์เข้าถึงคลิปบอร์ดผ่านความสามารถขั้นสูงของ Async Clipboard API หรือไม่ ความสามารถ "ขั้นสูง" รวมถึงทุกอย่างนอกเหนือจากการเขียนรูปแบบในตัวหลังจากท่าทางของผู้ใช้ เช่น ความสามารถในการอ่าน ความสามารถในการเขียนรูปแบบที่กำหนดเอง และความสามารถในการเขียนโดยไม่ต้องใช้ท่าทางของผู้ใช้ ตัวเลือกใดตัวเลือกหนึ่งต่อไปนี้ allow: อนุญาตให้เว็บไซต์ใช้ความสามารถของคลิปบอร์ดขั้นสูง block: ไม่อนุญาตให้เว็บไซต์ใช้ความสามารถของคลิปบอร์ดขั้นสูง ask: ถามเมื่อเว็บไซต์ต้องการใช้ความสามารถของคลิปบอร์ดขั้นสูง ค่าเริ่มต้นคือ ask URL หลักคือ URL ของเอกสารที่ขอสิทธิ์เข้าถึงคลิปบอร์ด ระบบจะไม่ใช้ URL รอง

ประเภท

ContentSetting<ClipboardContentSetting>

cookies

จะอนุญาตให้เว็บไซต์ตั้งค่าคุกกี้และข้อมูลอื่นๆ ในเครื่องหรือไม่ ค่าใดค่าหนึ่งต่อไปนี้ allow: ยอมรับคุกกี้ block: บล็อกคุกกี้ session\_only: ยอมรับคุกกี้เฉพาะเซสชันปัจจุบัน ค่าเริ่มต้นคือ allow URL หลักคือ URL ที่แสดงต้นทางของคุกกี้ URL รองคือ URL ของเฟรมระดับบนสุด

ประเภท

ContentSetting<CookiesContentSetting>

fullscreen

เลิกใช้งานแล้ว ไม่มีผลอีกต่อไป ตอนนี้ระบบจะให้สิทธิ์โหมดเต็มหน้าจอสำหรับทุกเว็บไซต์โดยอัตโนมัติ ค่าจะเป็น allow เสมอ

ประเภท

ContentSetting<FullscreenContentSetting>

images

จะแสดงรูปภาพหรือไม่ อย่างใดอย่างหนึ่ง allow: แสดงรูปภาพ block: ไม่แสดงรูปภาพ ค่าเริ่มต้นคือ allow URL หลักคือ URL ของเฟรมระดับบนสุด URL รองคือ URL ของรูปภาพ

ประเภท

ContentSetting<ImagesContentSetting>

javascript

ว่าจะเรียกใช้ JavaScript หรือไม่ ข้อใดข้อหนึ่ง allow: เรียกใช้ JavaScript block: ไม่เรียกใช้ JavaScript ค่าเริ่มต้นคือ allow URL หลักคือ URL ของเฟรมระดับบนสุด ระบบจะไม่ใช้ URL รอง

ประเภท

ContentSetting<JavascriptContentSetting>

location

ว่าจะอนุญาตตำแหน่งทางภูมิศาสตร์หรือไม่ ตัวเลือกมีดังนี้ allow: อนุญาตให้เว็บไซต์ติดตามตำแหน่งจริงของคุณ block: ไม่อนุญาตให้เว็บไซต์ติดตามตำแหน่งจริงของคุณ ask: ถามก่อนอนุญาตให้เว็บไซต์ติดตามตำแหน่งจริงของคุณ ค่าเริ่มต้นคือ ask URL หลักคือ URL ของเอกสารที่ขอข้อมูลตำแหน่ง URL รองคือ URL ของเฟรมระดับบนสุด (ซึ่งอาจแตกต่างจาก URL ที่ส่งคำขอหรือไม่ก็ได้)

ประเภท

ContentSetting<LocationContentSetting>

microphone

Chrome 46 ขึ้นไป

ว่าจะอนุญาตให้เว็บไซต์เข้าถึงไมโครโฟนหรือไม่ ตัวเลือกมีดังนี้ allow: อนุญาตให้เว็บไซต์เข้าถึงไมโครโฟน block: ไม่อนุญาตให้เว็บไซต์เข้าถึงไมโครโฟน ask: ถามเมื่อเว็บไซต์ต้องการเข้าถึงไมโครโฟน ค่าเริ่มต้นคือ ask URL หลักคือ URL ของเอกสารที่ขอสิทธิ์เข้าถึงไมโครโฟน ระบบจะไม่ใช้ URL รอง หมายเหตุ: การตั้งค่า "อนุญาต" จะไม่ถูกต้องหากทั้ง 2 รูปแบบเป็น "<all_urls>"

ประเภท

ContentSetting<MicrophoneContentSetting>

mouselock

เลิกใช้งานแล้ว ไม่มีผลอีกต่อไป ตอนนี้ระบบจะให้สิทธิ์การล็อกเมาส์สำหรับทุกเว็บไซต์โดยอัตโนมัติ ค่าจะเป็น allow เสมอ

ประเภท

ContentSetting<MouselockContentSetting>

notifications

ว่าจะอนุญาตให้เว็บไซต์แสดงการแจ้งเตือนบนเดสก์ท็อปหรือไม่ ตัวเลือกใดตัวเลือกหนึ่งต่อไปนี้ allow: อนุญาตให้เว็บไซต์แสดงการแจ้งเตือนในเดสก์ท็อป block: ไม่อนุญาตให้เว็บไซต์แสดงการแจ้งเตือนในเดสก์ท็อป ask: ถามเมื่อเว็บไซต์ต้องการแสดงการแจ้งเตือนในเดสก์ท็อป ค่าเริ่มต้นคือ ask URL หลักคือ URL ของเอกสารที่ต้องการแสดงการแจ้งเตือน ระบบจะไม่ใช้ URL รอง

ประเภท

ContentSetting<NotificationsContentSetting>

plugins

เลิกใช้งานแล้ว เมื่อ Chrome 88 นำการรองรับ Flash ออกไปแล้ว สิทธิ์นี้จึงไม่มีผลอีกต่อไป ค่าจะเป็น block เสมอ ระบบจะไม่สนใจการโทรไปยัง set() และ clear()

ประเภท

ContentSetting<PluginsContentSetting>

popups

ว่าจะอนุญาตให้เว็บไซต์แสดงป๊อปอัปหรือไม่ อย่างใดอย่างหนึ่ง allow: อนุญาตให้เว็บไซต์แสดงป๊อปอัป block: ไม่อนุญาตให้เว็บไซต์แสดงป๊อปอัป ค่าเริ่มต้นคือ block URL หลักคือ URL ของเฟรมระดับบนสุด ระบบจะไม่ใช้ URL รอง

ประเภท

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

เลิกใช้งานแล้ว ก่อนหน้านี้ นโยบายนี้ควบคุมว่าจะอนุญาตให้เว็บไซต์เรียกใช้ปลั๊กอินที่ไม่ได้อยู่ในแซนด์บ็อกซ์หรือไม่ อย่างไรก็ตาม เมื่อนำกระบวนการตัวกลาง Flash ออกใน Chrome 88 สิทธิ์นี้จะไม่มีผลอีกต่อไป ค่าจะเป็น block เสมอ ระบบจะไม่สนใจการโทรไปยัง set() และ clear()

ประเภท

ContentSetting<PpapiBrokerContentSetting>