diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 7e666dc..bed7c76 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -16,5 +16,6 @@ - [Helpers](/helpers) - [Vue compatibility](/vue) - [CDN](/cdn) + - [Offline Mode(PWA)new](/pwa) - [Changelog](/changelog) \ No newline at end of file diff --git a/docs/pwa.md b/docs/pwa.md new file mode 100644 index 0000000..5939341 --- /dev/null +++ b/docs/pwa.md @@ -0,0 +1,111 @@ +# Offline Mode + +[Progressive Web Apps](https://developers.google.com/web/progressive-web-apps/)(PWA) are experiences that combine the best of the web and the best of apps. we can enhance our website with service workers to work **offline** or on low-quality networks. +It is also very easy to use it. + +## Create serverWorker +Create a sw.js file in your documents root directory and copy this code. + +*sw.js* + +```js +/* =========================================================== + * docsify sw.js + * =========================================================== + * Copyright 2016 @huxpro + * Licensed under Apache 2.0 + * Register service worker. + * ========================================================== */ + +const RUNTIME = 'docsify'; +const HOSTNAME_WHITELIST = [ + self.location.hostname, + 'fonts.gstatic.com', + 'fonts.googleapis.com' +] + +// The Util Function to hack URLs of intercepted requests +const getFixedUrl = (req) => { + var now = Date.now(); + url = new URL(req.url) + + // 1. fixed http URL + // Just keep syncing with location.protocol + // fetch(httpURL) belongs to active mixed content. + // And fetch(httpRequest) is not supported yet. + url.protocol = self.location.protocol + + // 2. add query for caching-busting. + // Github Pages served with Cache-Control: max-age=600 + // max-age on mutable content is error-prone, with SW life of bugs can even extend. + // Until cache mode of Fetch API landed, we have to workaround cache-busting with query string. + // Cache-Control-Bug: https://bugs.chromium.org/p/chromium/issues/detail?id=453190 + url.search += (url.search ? '&' : '?') + 'cache-bust=' + now; + return url.href +} + +/** + * @Lifecycle Activate + * New one activated when old isnt being used. + * + * waitUntil(): activating ====> activated + */ +self.addEventListener('activate', event => { + event.waitUntil(self.clients.claim()); +}); + + +/** + * @Functional Fetch + * All network requests are being intercepted here. + * + * void respondWith(Promise r); + */ +self.addEventListener('fetch', event => { + // Skip some of cross-origin requests, like those for Google Analytics. + if (HOSTNAME_WHITELIST.indexOf(new URL(event.request.url).hostname) > -1) { + // Stale-while-revalidate + // similar to HTTP's stale-while-revalidate: https://www.mnot.net/blog/2007/12/12/stale + // Upgrade from Jake's to Surma's: https://gist.github.com/surma/eb441223daaedf880801ad80006389f1 + const cached = caches.match(event.request); + const fixedUrl = getFixedUrl(event.request); + const fetched = fetch(fixedUrl, {cache: 'no-store'}); + const fetchedCopy = fetched.then(resp => resp.clone()); + + // Call respondWith() with whatever we get first. + // If the fetch fails (e.g disconnected), wait for the cache. + // If there’s nothing in cache, wait for the fetch. + // If neither yields a response, return offline pages. + event.respondWith( + Promise.race([fetched.catch(_ => cached), cached]) + .then(resp => resp || fetched) + .catch(_ => {/* eat any errors */}) + ); + + // Update the cache with the version we fetched (only for ok status) + event.waitUntil( + Promise.all([fetchedCopy, caches.open(RUNTIME)]) + .then(([response, cache]) => response.ok && cache.put(event.request, response)) + .catch(_ => {/* eat any errors */}) + ); + } +}); +``` + +## Register + +Now, register it in your `index.html`. It only works on some modern browsers, so we need to judge. + +*index.html* + +```html + +``` + +## Enjoy it + +Release your website and start experiencing magical offline feature. :ghost: You can turn off Wi-Fi and refresh the current site to experience it. diff --git a/docs/zh-cn/_sidebar.md b/docs/zh-cn/_sidebar.md index 952a6fd..9d374bb 100644 --- a/docs/zh-cn/_sidebar.md +++ b/docs/zh-cn/_sidebar.md @@ -16,5 +16,6 @@ - [文档助手](zh-cn/helpers) - [兼容 Vue](zh-cn/vue) - [CDN](zh-cn/cdn) + - [离线模式(PWA)new](zh-cn/pwa) - [Changelog](zh-cn/changelog) \ No newline at end of file diff --git a/docs/zh-cn/pwa.md b/docs/zh-cn/pwa.md new file mode 100644 index 0000000..cd7151d --- /dev/null +++ b/docs/zh-cn/pwa.md @@ -0,0 +1,111 @@ +# 离线模式 + +[Progressive Web Apps](https://developers.google.com/web/progressive-web-apps/)(PWA) 是一项融合 Web 和 Native 应用各项优点的解决方案。我们可以利用其支持离线功能的特点，让我们的网站可以在信号差或者离线状态下正常运行。 +要使用它也非常容易。 + +## 创建 serverWorker +这里已经整理好了一份代码，你只需要在网站根目录下创建一个 `sw.js` 文件，并张贴下面的代码。 + +*sw.js* + +```js +/* =========================================================== + * docsify sw.js + * =========================================================== + * Copyright 2016 @huxpro + * Licensed under Apache 2.0 + * Register service worker. + * ========================================================== */ + +const RUNTIME = 'docsify'; +const HOSTNAME_WHITELIST = [ + self.location.hostname, + 'fonts.gstatic.com', + 'fonts.googleapis.com' +] + +// The Util Function to hack URLs of intercepted requests +const getFixedUrl = (req) => { + var now = Date.now(); + url = new URL(req.url) + + // 1. fixed http URL + // Just keep syncing with location.protocol + // fetch(httpURL) belongs to active mixed content. + // And fetch(httpRequest) is not supported yet. + url.protocol = self.location.protocol + + // 2. add query for caching-busting. + // Github Pages served with Cache-Control: max-age=600 + // max-age on mutable content is error-prone, with SW life of bugs can even extend. + // Until cache mode of Fetch API landed, we have to workaround cache-busting with query string. + // Cache-Control-Bug: https://bugs.chromium.org/p/chromium/issues/detail?id=453190 + url.search += (url.search ? '&' : '?') + 'cache-bust=' + now; + return url.href +} + +/** + * @Lifecycle Activate + * New one activated when old isnt being used. + * + * waitUntil(): activating ====> activated + */ +self.addEventListener('activate', event => { + event.waitUntil(self.clients.claim()); +}); + + +/** + * @Functional Fetch + * All network requests are being intercepted here. + * + * void respondWith(Promise r); + */ +self.addEventListener('fetch', event => { + // Skip some of cross-origin requests, like those for Google Analytics. + if (HOSTNAME_WHITELIST.indexOf(new URL(event.request.url).hostname) > -1) { + // Stale-while-revalidate + // similar to HTTP's stale-while-revalidate: https://www.mnot.net/blog/2007/12/12/stale + // Upgrade from Jake's to Surma's: https://gist.github.com/surma/eb441223daaedf880801ad80006389f1 + const cached = caches.match(event.request); + const fixedUrl = getFixedUrl(event.request); + const fetched = fetch(fixedUrl, {cache: 'no-store'}); + const fetchedCopy = fetched.then(resp => resp.clone()); + + // Call respondWith() with whatever we get first. + // If the fetch fails (e.g disconnected), wait for the cache. + // If there’s nothing in cache, wait for the fetch. + // If neither yields a response, return offline pages. + event.respondWith( + Promise.race([fetched.catch(_ => cached), cached]) + .then(resp => resp || fetched) + .catch(_ => {/* eat any errors */}) + ); + + // Update the cache with the version we fetched (only for ok status) + event.waitUntil( + Promise.all([fetchedCopy, caches.open(RUNTIME)]) + .then(([response, cache]) => response.ok && cache.put(event.request, response)) + .catch(_ => {/* eat any errors */}) + ); + } +}); +``` + +## 注册 + +现在，到 `index.html` 里注册它。这个功能只能工作在一些现代浏览器上，所以我们需要加个判断。 + +*index.html* + +```html + +``` + +## 体验一下 + +发布你的网站，并开始享受离线模式的魔力吧！:ghost: 当然你现在看到的 docsify 的文档网站已经支持离线模式了，你可以关掉 Wi-Fi 体验一下。