1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
<div id="pageData-name" class="pageData">Storage</div>
<!-- BEGIN AUTHORED CONTENT -->
<p id="classSummary">
Use the <code>chrome.storage</code> module
to store, retrieve, and track changes to user data.
This API has been optimized
to meet the specific storage needs of extensions.
It provides the same storage capabilities as the
<a href="https://developer.mozilla.org/en/DOM/Storage#localStorage">localStorage API</a>
with the following key differences:
</p>
<ul>
<li>User data can be automatically synced with Chrome sync
(using <code>storage.sync</code>).</li>
<li>Your extension's content scripts can directly access user data
without the need for a background page.</li>
<li>A user's extension settings can be persisted
even when using
<a href="http://code.google.com/chrome/extensions/manifest.html#incognito">split incognito behavior</a>.</li>
<li>User data can be stored as objects
(the <code>localStorage API</code> stores data in strings).</li>
</ul>
<h2 id="manifest">Manifest</h2>
<p>You must declare the "storage" permission in the <a
href="manifest.html">extension manifest</a>
to use the storage API.
For example:</p>
<pre>{
"name": "My extension",
...
<b>"permissions": [
"storage"
]</b>,
...
}</pre>
<h2 id="using-sync">Usage</h2>
<p>
To store user data for your extension,
you can use either
<code>storage.sync</code> or
<code>storage.local</code>.
When using <code>storage.sync</code>,
the stored data will automatically be persisted
across any Chrome browser that the user is logged into
provided the user's has sync enabled.
</p>
<p>
When Chrome's offline,
Chrome stores the data locally.
The next time the browser is online,
Chrome syncs the data.
Even if a user disables syncing,
<code>storage.sync</code> will still work.
In this case, it will behave identically
to <code>storage.local</code>.
</p>
<p class="warning">
Confidential user information should not be stored!
The storage area isn't encrypted.
</p>
<h2 id="limits">Storage and throttling limits</h2>
<p>
Storage space is limited to:
</p>
<ul>
<li>100kB per extension</li>
<li>2kB per item—each item size is the sum
of its JSON serialization plus its key</li>
<li>512 items per extension</li>
</ul>
<p>
The throttling limit for modification calls
to the Storage API is 1000 operations per hour.
</p>
<h2 id="examples">Examples</h2>
<p>
Storing user data is
as simple as calling
<code>set()</code>.
The following example checks for
CSS code saved by a user on a form,
and if found,
stores it.
</p>
<pre>
function saveChanges() {
// Get the current CSS snippet from the form.
var cssCode = textarea.value;
// Check that there's some code there.
if (!cssCode) {
message('Error: No CSS specified');
return;
}
// Save it using the Chrome extension storage API.
chrome.experimental.storage.sync.set({'css': cssCode}, function() {
// Notify that we saved.
message('Settings saved');
});
}
</pre>
<p>
If you're interested in tracking changes made
to a data object,
you can add a listener
to its <code>onChanged</code> event.
Whenever anything changes in storage,
that event fires.
Here's sample code
to listen for saved css changes:
</p>
<pre>
chrome.storage.onChanged.addListener(saveChanges);
saveChanges();
</pre>
<p>
You can find examples that use this API on the
<a href="samples.html#sty">Samples page</a>.
</p>
<!-- END AUTHORED CONTENT -->
|
