| OLD | NEW |
|---|
| (Empty) |
| 1 <!-- BEGIN AUTHORED CONTENT --> | |
| 2 <p id="classSummary"> | |
| 3 Use the <code>chrome.storage</code> module | |
| 4 to store, retrieve, and track changes to user data. | |
| 5 This API has been optimized | |
| 6 to meet the specific storage needs of extensions. | |
| 7 It provides the same storage capabilities as the | |
| 8 <a href="https://developer.mozilla.org/en/DOM/Storage#localStorage">localStorage
API</a> | |
| 9 with the following key differences: | |
| 10 </p> | |
| 11 <ul> | |
| 12 <li>User data can be automatically synced with Chrome sync | |
| 13 (using <code>storage.sync</code>).</li> | |
| 14 <li>Your extension's content scripts can directly access user data | |
| 15 without the need for a background page.</li> | |
| 16 <li>A user's extension settings can be persisted | |
| 17 even when using | |
| 18 <a href="manifest.html#incognito">split incognito behavior</a>.</li> | |
| 19 <li>User data can be stored as objects | |
| 20 (the <code>localStorage API</code> stores data in strings).</li> | |
| 21 </ul> | |
| 22 <h2 id="manifest">Manifest</h2> | |
| 23 <p>You must declare the "storage" permission in the <a | |
| 24 href="manifest.html">extension manifest</a> | |
| 25 to use the storage API. | |
| 26 For example:</p> | |
| 27 <pre>{ | |
| 28 "name": "My extension", | |
| 29 ... | |
| 30 <b>"permissions": [ | |
| 31 "storage" | |
| 32 ]</b>, | |
| 33 ... | |
| 34 }</pre> | |
| 35 <h2 id="using-sync">Usage</h2> | |
| 36 <p> | |
| 37 To store user data for your extension, | |
| 38 you can use either | |
| 39 <code>storage.sync</code> or | |
| 40 <code>storage.local</code>. | |
| 41 When using <code>storage.sync</code>, | |
| 42 the stored data will automatically be synced | |
| 43 to any Chrome browser that the user is logged into, | |
| 44 provided the user has sync enabled. | |
| 45 </p> | |
| 46 <p> | |
| 47 When Chrome is offline, | |
| 48 Chrome stores the data locally. | |
| 49 The next time the browser is online, | |
| 50 Chrome syncs the data. | |
| 51 Even if a user disables syncing, | |
| 52 <code>storage.sync</code> will still work. | |
| 53 In this case, it will behave identically | |
| 54 to <code>storage.local</code>. | |
| 55 </p> | |
| 56 <p class="warning"> | |
| 57 Confidential user information should not be stored! | |
| 58 The storage area isn't encrypted. | |
| 59 </p> | |
| 60 <h2 id="limits">Storage and throttling limits</h2> | |
| 61 <p><code>chrome.storage</code> is not a big truck. | |
| 62 It's a series of tubes. | |
| 63 And if you don't understand, | |
| 64 those tubes can be filled, | |
| 65 and if they are filled | |
| 66 when you put your message in, | |
| 67 it gets in line, | |
| 68 and it's going to be delayed | |
| 69 by anyone that puts into that tube | |
| 70 enormous amounts of material. | |
| 71 <p>For details on the current limits | |
| 72 of the storage API, and what happens | |
| 73 when those limits are exceeded, please | |
| 74 see the <a href="#apiReference">API reference</a>. | |
| 75 <h2 id="examples">Examples</h2> | |
| 76 <p> | |
| 77 The following example checks for | |
| 78 CSS code saved by a user on a form, | |
| 79 and if found, | |
| 80 stores it. | |
| 81 </p> | |
| 82 <pre> | |
| 83 function saveChanges() { | |
| 84 // Get a value saved in a form. | |
| 85 var theValue = textarea.value; | |
| 86 // Check that there's some code there. | |
| 87 if (!theValue) { | |
| 88 message('Error: No value specified'); | |
| 89 return; | |
| 90 } | |
| 91 // Save it using the Chrome extension storage API. | |
| 92 chrome.storage.sync.set({'value': theValue}, function() { | |
| 93 // Notify that we saved. | |
| 94 message('Settings saved'); | |
| 95 }); | |
| 96 } | |
| 97 </pre> | |
| 98 <p> | |
| 99 If you're interested in tracking changes made | |
| 100 to a data object, | |
| 101 you can add a listener | |
| 102 to its <code>onChanged</code> event. | |
| 103 Whenever anything changes in storage, | |
| 104 that event fires. | |
| 105 Here's sample code | |
| 106 to listen for saved changes: | |
| 107 </p> | |
| 108 <pre> | |
| 109 chrome.storage.onChanged.addListener(function(changes, namespace) { | |
| 110 for (key in changes) { | |
| 111 var storageChange = changes[key]; | |
| 112 console.log('Storage key "%s" in namespace "%s" changed. ' + | |
| 113 'Old value was "%s", new value is "%s".', | |
| 114 key, | |
| 115 namespace, | |
| 116 storageChange.oldValue, | |
| 117 storageChange.newValue); | |
| 118 } | |
| 119 }); | |
| 120 </pre> | |
| 121 <p> | |
| 122 You can find examples that use this API on the | |
| 123 <a href="samples.html#sty">Samples page</a>. | |
| 124 </p> | |
| 125 <!-- END AUTHORED CONTENT --> | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 10750017:
Extensions Docs Server: Intro data source (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src