browser.storage

คำอธิบาย

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

สิทธิ์

storage

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

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

ตัวอย่าง

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

ตัวอย่าง (ในพื้นที่)

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

ตัวอย่าง (ซิงค์)

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

ตัวอย่าง (เซสชัน)

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

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

• ส่วนขยายการค้นหาทั่วโลก
• ส่วนขยายการแจ้งเตือนน้ำ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ในพื้นที่

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

ที่จัดการ

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

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

เซสชัน

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

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

ซิงค์

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

เราขอแนะนำให้ใช้ storage.sync เพื่อรักษาการตั้งค่าของผู้ใช้ในเบราว์เซอร์ที่ซิงค์ หากคุณทำงานกับข้อมูลผู้ใช้ที่ละเอียดอ่อน ให้ใช้ storage.session แทน โดยค่าเริ่มต้น storage.sync จะแสดงต่อสคริปต์เนื้อหา แต่ลักษณะการทำงานนี้สามารถเปลี่ยนแปลงได้โดยการเรียกใช้ browser.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 ได้

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

ส่วนต่อไปนี้แสดง Use Case ทั่วไปสำหรับ Storage API

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

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

background.js:

browser.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;
  browser.storage.sync.set({ options });
});

// Initialize the form with the user's option settings
const data = await browser.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
browser.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 = browser.storage.sync.get().then((items) => {
  // Copy the data retrieved from storage into storageCache.
  Object.assign(storageCache, items);
});

browser.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;
  browser.storage.sync.set(storageCache);
});

เครื่องมือสำหรับนักพัฒนาเว็บ

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

ประเภท

AccessLevel

Chrome 102 ขึ้นไป

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

ค่าแจกแจง

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

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

StorageChange

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

• newValue

  ไม่บังคับ

  ค่าใหม่ของสินค้า หากมีค่าใหม่

• oldValue

  ไม่บังคับ

  ค่าเดิมของสินค้า หากมีค่าเดิม

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

local

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

ประเภท

StorageArea และออบเจ็กต์

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

• QUOTA_BYTES

  10485760
  

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

managed

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

ประเภท

StorageArea

session

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

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

ประเภท

StorageArea และออบเจ็กต์

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

• QUOTA_BYTES

  10485760
  

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

sync

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

ประเภท

StorageArea และออบเจ็กต์

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

• MAX_ITEMS

  512
  

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

• MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

  1000000
  

  เลิกใช้งานแล้ว

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

• MAX_WRITE_OPERATIONS_PER_HOUR

  1800
  

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

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

• MAX_WRITE_OPERATIONS_PER_MINUTE

  120
  

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

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

• QUOTA_BYTES

  102400
  

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

• QUOTA_BYTES_PER_ITEM

  8192
  

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

กิจกรรม

onChanged

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

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

พารามิเตอร์

• callback

  ฟังก์ชัน

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

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

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

    ออบเจ็กต์

  • areaName

    สตริง