-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathhistory-based-api.html
210 lines (158 loc) · 7.4 KB
/
history-based-api.html
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
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
<!DOCTYPE html>
<html xmlns='http://www.w3.org/1999/xhtml' lang='en'>
<head>
<meta charset='utf-8'/>
<title>Custom Scroll Restoration - History-based API
</title>
<script class='remove'>
var respecConfig = {
specStatus: "unofficial"
, shortName: ""
, editors: [
{ name: "Majid Valipour"
, company: "Google"
, companyURL: "https://www.google.com/" }
]
, edDraftURI: "https://majido.github.io/scroll-restoration-proposal/history-based-api.html"
, otherLinks: [{
key: 'Participation',
data: [
{
value: 'GitHub repository',
href: 'https://github.com/majido/scroll-restoration-proposal/'
}, {
value: 'File a bug / view open issues',
href: 'https://github.com/majido/scroll-restoration-proposal/issues'
}, {
value: 'E-mail feedback',
href: 'mailto:whatwg@whatwg.org?subject=%5BScrollRestoration%5D'
}
]
}]
, copyrightStart: 2015
, noIDLIn: true
, wg: ""
, wgURI: ""
, wgPublicList: "whatwg"
, wgPatentURI: "XXX"
, isRecTrack: false
, isNoTrack: true
, issueBase: ""
, format: 'markdown'
};
</script>
<script src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove' async></script>
</head>
<body>
<section id='abstract'>
This document describes an API that gives web authors additional control over
user agent's restoration of persisted user state in particular the document's
scroll position.
*NOTE*: The proposed API is now part of [WhatWG HTML Living
Standard](https://html.spec.whatwg.org/multipage/browsers.html#dom-history-scroll-restoration)
</section>
<section id='sotd'>
We actively solicit comments on this document either via emailing to
[whatwg@whatwg.org mailing list][whatwg-mailinglist] or opening an issue
on [GitHub][github-repo] for this repository.
</section>
## Design
We propose to modify History API and make it possible for web authors to
explicitly disable the default scroll restoration behavior. This is achieved
by adding a new attribute, `scrollRestoration`, to `window.history`.
This new attribute can take two values: 'auto', 'manual' with 'auto' being the
default.
Setting `scrollRestoration` to a new value updates the [current entry
][current-entry-def] in history session. Also any future entry that is added
to history session for the same document will use this new `scrollRestoration`
value. However, changing this value does not impact any previous entries in
sessions history including those that belong to the same document.
Furthermore, any navigation to a new page with a different document resets the
`scrollRestoration` to its default value.
Note that this ensures that changes to `scrollRestoration` only affect entries that
will be created for the same document (e.g., entries created using pushState,
or due to fragment navigation).
### Child Frames
Disabling scroll restoration in one frame should not impact the
scroll restoration for any other frame including any of its child frames.
### Web IDL
<pre class="idl">
enum ScrollRestoration { "auto", "manual" };
partial interface History {
attribute ScrollRestoration scrollRestoration;
};
</pre>
<dl>
<dt><dfn>scrollRestoration</dfn></dt>
<dd>
Indicates whether the user agent should restore scroll position when
traversing to this entry. Anytime this attribute is modified the current
entry in joint session history should be updated to reflect the change.
</dd>
</dl>
<section class="informative">
## Usage
Web applications that want to implement their own custom scroll restoration
logic can disable user-agent's scroll restoration by setting the
scrollRestoration attribute. Most applications want to use the same scroll
restoration value for all of their history entries in which case they should
set the scrollRestoration attribute as soon as possible (e.g., first script
tag in the document's <head>) to ensure that any entry that is added to
the history session gets the desired scroll restoration value.
<pre class='highlight example'>
<head>
<script>
history.scrollRestoration = 'manual';
</script>
</head>
</pre>
Checking for existence of the `scrollRestoration` can be used as a way to feature detect:
<pre class='highlight example'>
let canControlScrollRestoration = 'scrollRestoration' in window.history
</pre>
</section>
## Spec Changes
### History traversal
Modify the [history traversal algorithm][history-traverse-algorithm], add the
following new section to the spec defining persisted user state restoration
process and update steps 3 and 9 as following:
9\. If the specified entry has persisted user state, and the user agent wants
to update aspects of the document and its rendering **it should run the
`persisted user state restoration` steps.**
#### Persisted user state restoration
Run the following steps immediately:
1. If the entry has an scroll restoration value, let *scrollRestoration* be that.
2. If *scrollRestoration* is 'manual' the user agent should not
restore the scroll position for the document otherwise it may.
3. Set `history.scrollRestoration` to *scrollRestoration*
4. User agent may now update other aspects of the document and its
rendering, for instance values of form fields, that it had previously
recorded.
### Push State
Modify the [pushState algorithm][pushstate-algorithm] and update a step 4.3 as following:
(4\.)3\. If appropriate, update the current entry to reflect any state that
the user agent wishes to persist, **and current history scroll restoration
value**. The entry is then said to be an entry with persisted user state.
### Navigating to Fragment
Modify the [navigating to a fragment identifier algorithm][scroll-to-frag-algorithm]
and update step 3 as following:
3\. Append a new entry at the end of the History object representing the new
resource and its Document object, related state, **and current history
scroll restoration value**. Its URL must be set to the address to which the
user agent was navigating. The title must be left unset.
### Navigating to a new page
Modify the [update the session history with the new page][update-session-algorithm]
algorithm and update step 2.2 as following:
(2\.)2\. Append a new entry at the end of the History object representing
the new resource and its Document object and related state **and with default
history scroll restoration value i.e. "auto"**.
[whatwg-mailinglist]: https://lists.w3.org/Archives/Public/public-whatwg-archive/
[github-repo]: https://github.com/majido/scroll-restoration-proposal
[background]: https://docs.google.com/document/d/1Tiu8PjvBtNOAgeh6yrs7bOrXxQcavQLiNtRJ_ToLlVM/edit
[history-traverse-algorithm]: https://html.spec.whatwg.org/#history-traversal
[pushstate-algorithm]: https://html.spec.whatwg.org/#dom-history-pushstate
[scroll-to-frag-algorithm]: https://html.spec.whatwg.org/#scroll-to-fragid
[update-session-algorithm]: https://html.spec.whatwg.org/#update-the-session-history-with-the-new-page
[current-entry-def]: https://html.spec.whatwg.org/#current-entry
</body>
</html>