chrome.storage

คำอธิบาย

ใช้ chrome.storage API เพื่อจัดเก็บ ดึงข้อมูล และติดตามการเปลี่ยนแปลงข้อมูลผู้ใช้

สิทธิ์

storage

หากต้องการใช้ Storage API ให้ประกาศสิทธิ์ "storage" ในไฟล์ Manifest ของส่วนขยาย เช่น

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

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงพื้นที่เก็บข้อมูล local, sync และ session

ตัวอย่าง (Local)

await chrome.storage.local.set({ key: value });
console.log("Value is set");
const result = await chrome.storage.local.get(["key"]);
console.log("Value is " + result.key);

ตัวอย่าง (Sync)

await chrome.storage.sync.set({ key: value });
console.log("Value is set");
const result = await chrome.storage.sync.get(["key"]);
console.log("Value is " + result.key);

ตัวอย่าง (Session)

await chrome.storage.session.set({ key: value });
console.log("Value is set");
const result = await chrome.storage.session.get(["key"]);
console.log("Value is " + result.key);

หากต้องการดูการสาธิตอื่นๆ ของ Storage API ให้สำรวจตัวอย่างต่อไปนี้

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

Storage API มีวิธีเฉพาะของส่วนขยายในการเก็บข้อมูลผู้ใช้และสถานะไว้ ซึ่งคล้ายกับ Storage API ของแพลตฟอร์มเว็บ (IndexedDB และ Storage) แต่ได้รับการออกแบบมาเพื่อตอบสนองความต้องการพื้นที่เก็บข้อมูลของส่วนขยาย ฟีเจอร์หลักๆ บางส่วนมีดังนี้

ส่วนขยายใช้ Web Storage API ได้ไหม

แม้ว่าส่วนขยายจะใช้อินเทอร์เฟซ Storage (เข้าถึงได้จาก window.localStorage) ในบางบริบท (ป๊อปอัปและหน้า HTML อื่นๆ) ได้ แต่เราไม่แนะนำให้ใช้ด้วยเหตุผลต่อไปนี้

  • Service Worker ของส่วนขยายไม่สามารถใช้ Web Storage API ได้
  • สคริปต์เนื้อหาจะแชร์พื้นที่เก็บข้อมูลกับหน้าโฮสต์
  • ข้อมูลที่บันทึกไว้โดยใช้ Web Storage API จะหายไปเมื่อผู้ใช้ล้างประวัติการท่องเว็บ

วิธีย้ายข้อมูลจาก Web Storage API ไปยัง Storage API ของส่วนขยายจาก Service Worker

  1. เตรียมหน้า HTML ของเอกสารนอกหน้าจอและไฟล์สคริปต์ ไฟล์สคริปต์ควรมีกิจวัตรการแปลงและตัวแฮนเดิล onMessage
  2. ใน Service Worker ของส่วนขยาย ให้ตรวจสอบ chrome.storage เพื่อหาข้อมูล
  3. หากไม่พบข้อมูล ให้เรียก createDocument()
  4. หลังจากที่ Promise ที่ส่งคืนได้รับการแก้ไขแล้ว ให้เรียก sendMessage() เพื่อเริ่มกิจวัตรการแปลง
  5. ภายในตัวแฮนเดิล onMessage ของเอกสารนอกหน้าจอ ให้เรียกกิจวัตรการแปลง

นอกจากนี้ยังมีรายละเอียดปลีกย่อยบางอย่างเกี่ยวกับวิธีการทำงานของ Web Storage API ในส่วนขยาย ดูข้อมูลเพิ่มเติมได้ในบทความ พื้นที่เก็บข้อมูลและคุกกี้

ขีดจำกัดของพื้นที่เก็บข้อมูลและการควบคุมปริมาณ

Storage API มีข้อจำกัดในการใช้งานดังนี้

  • การจัดเก็บข้อมูลมีค่าใช้จ่ายด้านประสิทธิภาพ และ API มีโควต้าพื้นที่เก็บข้อมูล วางแผนข้อมูลที่คุณต้องการจัดเก็บเพื่อให้มีพื้นที่เก็บข้อมูลเพียงพอ
  • การจัดเก็บอาจใช้เวลาสักครู่ จัดโครงสร้างโค้ดเพื่อคำนึงถึงเวลาดังกล่าว

ดูรายละเอียดเกี่ยวกับข้อจำกัดของพื้นที่เก็บข้อมูลและสิ่งที่เกิดขึ้นเมื่อใช้เกินขีดจำกัดได้ที่ข้อมูลโควต้าสำหรับ sync, local และ session

พื้นที่เก็บข้อมูล

Storage API แบ่งออกเป็นพื้นที่เก็บข้อมูลต่อไปนี้

Local

ระบบจะจัดเก็บข้อมูลไว้ในเครื่องและล้างข้อมูลเมื่อนำส่วนขยายออก ขีดจำกัดของพื้นที่เก็บข้อมูลคือ 10 MB (5 MB ใน Chrome 113 และเวอร์ชันก่อนหน้า) แต่สามารถเพิ่มได้โดยขอสิทธิ์ "unlimitedStorage" เราขอแนะนำให้ใช้ storage.local เพื่อจัดเก็บข้อมูลจำนวนมากขึ้น โดยค่าเริ่มต้น ระบบจะแสดงข้อมูลนี้ต่อสคริปต์เนื้อหา แต่คุณสามารถเปลี่ยนลักษณะการทำงานนี้ได้โดยเรียก chrome.storage.local.setAccessLevel()

Managed

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

โดยค่าเริ่มต้น ระบบจะแสดง storage.managed ต่อสคริปต์เนื้อหา แต่คุณสามารถเปลี่ยนลักษณะการทำงานนี้ได้โดยเรียก chrome.storage.managed.setAccessLevel() ดูข้อมูลเกี่ยวกับนโยบายได้ที่ เอกสารประกอบสำหรับผู้ดูแลระบบ ดูข้อมูลเพิ่มเติมเกี่ยวกับพื้นที่เก็บข้อมูล managed ได้ที่ ไฟล์ Manifest สำหรับพื้นที่เก็บข้อมูล

Session

พื้นที่เก็บข้อมูลของเซสชันจะเก็บข้อมูลไว้ในหน่วยความจำขณะที่โหลดส่วนขยาย ระบบจะล้างพื้นที่เก็บข้อมูลหากปิดใช้ โหลดซ้ำ อัปเดตส่วนขยาย และเมื่อรีสตาร์ทเบราว์เซอร์ โดยค่าเริ่มต้น ระบบจะไม่แสดงข้อมูลนี้ต่อสคริปต์เนื้อหา แต่คุณสามารถเปลี่ยนลักษณะการทำงานนี้ได้โดยเรียก chrome.storage.session.setAccessLevel() ขีดจำกัดของพื้นที่เก็บข้อมูลคือ 10 MB (1 MB ใน Chrome 111 และเวอร์ชันก่อนหน้า)

อินเทอร์เฟซ storage.session เป็นหนึ่งในหลายๆ อินเทอร์เฟซที่เราแนะนำสำหรับ Service Worker

Sync

หากผู้ใช้เปิดใช้การซิงค์ ระบบจะซิงค์ข้อมูลกับเบราว์เซอร์ Chrome ทุกเบราว์เซอร์ที่ผู้ใช้เข้าสู่ระบบ หากปิดใช้ ระบบจะทำงานเหมือน storage.local Chrome จะจัดเก็บข้อมูลไว้ในเครื่องเมื่อเบราว์เซอร์ออฟไลน์ และจะกลับมาซิงค์อีกครั้งเมื่อเบราว์เซอร์กลับมาออนไลน์ ข้อจำกัดของโควต้าอยู่ที่ประมาณ 100 KB โดยมีขนาด 8 KB ต่อรายการ

เราขอแนะนำให้ใช้ storage.sync เพื่อเก็บรักษาการตั้งค่าของผู้ใช้ในเบราว์เซอร์ที่ซิงค์ หากคุณกำลังทำงานกับข้อมูลผู้ใช้ที่ละเอียดอ่อน ให้ใช้ storage.session แทน โดยค่าเริ่มต้น ระบบจะแสดง storage.sync ต่อสคริปต์เนื้อหา แต่คุณสามารถเปลี่ยนลักษณะการทำงานนี้ได้โดยเรียก chrome.storage.sync.setAccessLevel()

เมธอดและเหตุการณ์

พื้นที่เก็บข้อมูลทั้งหมดใช้ StorageArea อินเทอร์เฟซ

get()

เมธอด get() ช่วยให้คุณอ่านคีย์อย่างน้อย 1 รายการจาก StorageArea ได้

getBytesInUse()

เมธอด getBytesInUse() ช่วยให้คุณดูโควต้าที่ StorageArea ใช้ได้

getKeys()

เมธอด getKeys() ช่วยให้คุณรับคีย์ทั้งหมดที่จัดเก็บไว้ใน StorageArea ได้

remove()

เมธอด remove() ช่วยให้คุณนำรายการออกจาก StorageArea ได้

set()

เมธอด set() ช่วยให้คุณตั้งค่ารายการใน StorageArea ได้

setAccessLevel()

เมธอด setAccessLevel() ช่วยให้คุณควบคุมการเข้าถึง StorageArea ได้

clear()

เมธอด clear() ช่วยให้คุณล้างข้อมูลทั้งหมดจาก StorageArea ได้

onChanged

เหตุการณ์ onChanged ช่วยให้คุณตรวจสอบการเปลี่ยนแปลงใน StorageArea ได้

กรณีการใช้งาน

ส่วนต่อไปนี้แสดงกรณีการใช้งานทั่วไปสำหรับ Storage API

ตอบสนองต่อการอัปเดตพื้นที่เก็บข้อมูล

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

background.js:

chrome.storage.onChanged.addListener((changes, namespace) => {
  for (let [key, { oldValue, newValue }] of Object.entries(changes)) {
    console.log(
      `Storage key "${key}" in namespace "${namespace}" changed.`,
      `Old value was "${oldValue}", new value is "${newValue}".`
    );
  }
});

เราสามารถขยายแนวคิดนี้ให้กว้างขึ้นได้ ในตัวอย่างนี้ เรามีหน้าตัวเลือกที่ ช่วยให้ผู้ใช้สลับ "โหมดแก้ไขข้อบกพร่อง" ได้ (ไม่ได้แสดงการใช้งานที่นี่) หน้าตัวเลือกจะบันทึกการตั้งค่าใหม่ลงใน storage.sync ทันที และ Service Worker จะใช้ storage.onChanged เพื่อใช้การตั้งค่าโดยเร็วที่สุด

options.html:

<!-- type="module" allows you to use top level await -->
<script defer src="options.js" type="module"></script>
<form id="optionsForm">
  <label for="debug">
    <input type="checkbox" name="debug" id="debug">
    Enable debug mode
  </label>
</form>

options.js:

// In-page cache of the user's options
const options = {};
const optionsForm = document.getElementById("optionsForm");

// Immediately persist options changes
optionsForm.debug.addEventListener("change", (event) => {
  options.debug = event.target.checked;
  chrome.storage.sync.set({ options });
});

// Initialize the form with the user's option settings
const data = await chrome.storage.sync.get("options");
Object.assign(options, data.options);
optionsForm.debug.checked = Boolean(options.debug);

background.js:

function setDebugMode() { /* ... */ }

// Watch for changes to the user's options & apply them
chrome.storage.onChanged.addListener((changes, area) => {
  if (area === 'sync' && changes.options?.newValue) {
    const debugMode = Boolean(changes.options.newValue.debug);
    console.log('enable debug mode?', debugMode);
    setDebugMode(debugMode);
  }
});

การโหลดล่วงหน้าแบบไม่พร้อมกันจากพื้นที่เก็บข้อมูล

เนื่องจาก Service Worker ไม่ได้ทำงานตลอดเวลา ส่วนขยาย Manifest V3 จึงอาจต้องโหลดข้อมูลจากพื้นที่เก็บข้อมูลแบบไม่พร้อมกันก่อนที่จะเรียกใช้ตัวแฮนเดิลเหตุการณ์ ในการดำเนินการนี้ ข้อมูลโค้ดต่อไปนี้จะใช้ตัวแฮนเดิลเหตุการณ์ action.onClicked แบบไม่พร้อมกันที่รอให้มีการป้อนข้อมูลลงในตัวแปรส่วนกลาง storageCache ก่อนที่จะเรียกใช้ตรรกะ

background.js:

// Where we will expose all the data we retrieve from storage.sync.
const storageCache = { count: 0 };
// Asynchronously retrieve data from storage.sync, then cache it.
const initStorageCache = chrome.storage.sync.get().then((items) => {
  // Copy the data retrieved from storage into storageCache.
  Object.assign(storageCache, items);
});

chrome.action.onClicked.addListener(async (tab) => {
  try {
    await initStorageCache;
  } catch (e) {
    // Handle error that occurred during storage initialization.
  }

  // Normal action handler logic.
  storageCache.count++;
  storageCache.lastTabId = tab.id;
  chrome.storage.sync.set(storageCache);
});

DevTools

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

ประเภท

AccessLevel

Chrome 102 ขึ้นไป

ระดับการเข้าถึงของพื้นที่เก็บข้อมูล

ค่าแจกแจง

"TRUSTED_CONTEXTS"
ระบุบริบทที่มาจากส่วนขยายเอง

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
ระบุบริบทที่มาจากภายนอกส่วนขยาย

StorageChange

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

  • newValue

    ค่าใดก็ได้ (ไม่บังคับ)

    ค่าใหม่ของรายการ หากมีค่าใหม่

  • oldValue

    ค่าใดก็ได้ (ไม่บังคับ)

    ค่าเดิมของรายการ หากมีค่าเดิม

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

local

รายการในพื้นที่เก็บข้อมูล local จะอยู่ในเครื่องแต่ละเครื่อง

ประเภท

StorageArea & ออบเจ็กต์

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

  • QUOTA_BYTES

    10485760

    ปริมาณข้อมูลสูงสุด (เป็นไบต์) ที่จัดเก็บไว้ในพื้นที่เก็บข้อมูลในเครื่องได้ โดยวัดจากสตริง JSON ของค่าแต่ละค่ารวมกับความยาวของคีย์แต่ละรายการ ระบบจะละเว้นค่านี้หากส่วนขยายมีสิทธิ์ unlimitedStorage การอัปเดตที่จะทำให้เกินขีดจำกัดนี้จะล้มเหลวทันทีและตั้งค่า runtime.lastError เมื่อใช้ Callback หรือ Promise ที่ถูกปฏิเสธหากใช้ async/await

managed

รายการในพื้นที่เก็บข้อมูล managed จะกำหนดโดยนโยบายขององค์กรที่ผู้ดูแลระบบโดเมนกำหนดค่าไว้ และส่วนขยายจะอ่านได้อย่างเดียว การพยายามแก้ไขเนมสเปซนี้จะทำให้เกิดข้อผิดพลาด ดูข้อมูลเกี่ยวกับการกำหนดค่านโยบายได้ที่ ไฟล์ Manifest สำหรับพื้นที่เก็บข้อมูล

ประเภท

StorageArea

session

Chrome 102 ขึ้นไป MV3 ขึ้นไป

รายการในพื้นที่เก็บข้อมูล session จะจัดเก็บไว้ในหน่วยความจำและจะไม่จัดเก็บไว้ในดิสก์

ประเภท

StorageArea & ออบเจ็กต์

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

  • QUOTA_BYTES

    10485760

    ปริมาณข้อมูลสูงสุด (เป็นไบต์) ที่จัดเก็บไว้ในหน่วยความจำได้ โดยวัดจากการประมาณการใช้งานหน่วยความจำที่จัดสรรแบบไดนามิกของค่าและคีย์แต่ละรายการ การอัปเดตที่จะทำให้เกินขีดจำกัดนี้จะล้มเหลวทันทีและตั้งค่า runtime.lastError เมื่อใช้ Callback หรือเมื่อ Promise ถูกปฏิเสธ

sync

ระบบจะซิงค์รายการในพื้นที่เก็บข้อมูล sync โดยใช้การซิงค์ของ Chrome

ประเภท

StorageArea & ออบเจ็กต์

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

  • MAX_ITEMS

    512

    จำนวนรายการสูงสุดที่จัดเก็บไว้ในพื้นที่เก็บข้อมูลการซิงค์ได้ การอัปเดตที่จะทำให้เกินขีดจำกัดนี้จะล้มเหลวทันทีและตั้งค่า runtime.lastError เมื่อใช้ Callback หรือเมื่อ Promise ถูกปฏิเสธ

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    เลิกใช้งาน

    Storage.sync API ไม่มีโควต้าการดำเนินการเขียนแบบต่อเนื่องอีกต่อไป

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1800

    จำนวนการดำเนินการ set, remove หรือ clear สูงสุดที่ทำได้ในแต่ละชั่วโมง ซึ่งเท่ากับ 1 รายการทุกๆ 2 วินาที ซึ่งเป็นเพดานที่ต่ำกว่าขีดจำกัดการเขียนต่อนาทีที่สูงกว่าในระยะสั้น

    การอัปเดตที่จะทำให้เกินขีดจำกัดนี้จะล้มเหลวทันทีและตั้งค่า runtime.lastError เมื่อใช้ Callback หรือเมื่อ Promise ถูกปฏิเสธ

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

    จำนวนการดำเนินการ set, remove หรือ clear สูงสุดที่ทำได้ในแต่ละนาที ซึ่งเท่ากับ 2 รายการต่อวินาที ซึ่งให้ปริมาณงานสูงกว่าการเขียนต่อชั่วโมงในช่วงเวลาที่สั้นกว่า

    การอัปเดตที่จะทำให้เกินขีดจำกัดนี้จะล้มเหลวทันทีและตั้งค่า runtime.lastError เมื่อใช้ Callback หรือเมื่อ Promise ถูกปฏิเสธ

  • QUOTA_BYTES

    102400

    ปริมาณข้อมูลทั้งหมดสูงสุด (เป็นไบต์) ที่จัดเก็บไว้ในพื้นที่เก็บข้อมูลการซิงค์ได้ โดยวัดจากสตริง JSON ของค่าแต่ละค่ารวมกับความยาวของคีย์แต่ละรายการ การอัปเดตที่จะทำให้เกินขีดจำกัดนี้จะล้มเหลวทันทีและตั้งค่า runtime.lastError เมื่อใช้ Callback หรือเมื่อ Promise ถูกปฏิเสธ

  • QUOTA_BYTES_PER_ITEM

    8192

    ขนาดสูงสุด (เป็นไบต์) ของแต่ละรายการในพื้นที่เก็บข้อมูลการซิงค์ โดยวัดจากสตริง JSON ของค่ารวมกับความยาวของคีย์ การอัปเดตที่มีรายการขนาดใหญ่กว่าขีดจำกัดนี้จะล้มเหลวทันทีและตั้งค่า runtime.lastError เมื่อใช้ Callback หรือเมื่อ Promise ถูกปฏิเสธ

เหตุการณ์

onChanged

chrome.storage.onChanged.addListener(
  callback: function,
)

เริ่มทำงานเมื่อมีการเปลี่ยนแปลงรายการอย่างน้อย 1 รายการ

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (changes: object, areaName: string) => void

    • การเปลี่ยนแปลง

      ออบเจ็กต์

    • areaName

      สตริง