使用 Sencha Cmd 构建渐进式 Web 应用

Cmd 6.5+ 帮助您将任何 Ext JS 应用程序转变为渐进式 Web 应用。

渐进式 Web 应用使用现代 Web 技术提供原生应用程序体验。Google 提供了对渐进式 Web 应用的精彩介绍：您的第一个渐进式 Web 应用

Cmd 专门允许开发人员

• 显示应用程序横幅，邀请 Android 用户将应用程序安装到他们的主屏幕。

• 通过基于 service-worker 的缓存为支持此功能的浏览器提供离线支持。

注意： 您必须首先在本地安装 Node JS 才能使用 Cmd 渐进式 Web 应用集成。

要求

使用渐进式 Web 应用功能需要 Node JS 6+

添加到主屏幕横幅

要向您的应用程序添加“添加到主屏幕”横幅，请将 progressive 配置对象添加到您的 app.json。progressive 配置对象有两个项目：manifest 和 serviceWorker。manifest 配置包含 web app manifest 的数据。一旦此配置到位，Cmd 会在构建时自动将必需的 <link rel=”manifest”/> 标记添加到您应用程序的 index.html 文件中。

web app manifest 的存在并不一定意味着受支持的浏览器会立即显示添加到主屏幕横幅。例如，Chrome 使用一组标准，包括 service worker 的使用、SSL 状态和访问频率启发式方法来确定何时 显示横幅。

示例

"progressive": {
    "manifest": {

        "name": "My App",
        "short_name": "My App",
        "icons": [{
            "src": "resources/icon-small.png",
            "sizes": "96x96"
        }, {
            "src": "resources/icon-medium.png",
            "sizes": "192x192"
        }, {
            "src": "resources/icon-large.png",
            "sizes": "256x256"
        }],
        "theme_color": "#054059",
        "background_color": "#054059",
        "display": "standalone",
        "orientation": "portrait",
        "start_url": "/index.html"
    }
}

使用 Service Workers 进行缓存

注意：sw-precache 的使用已被弃用，转而使用 Workbox。Sencha Cmd 将在即将发布的版本中支持 Workbox。

渐进式 Web 应用最重要的功能也许是提供离线功能。通常，这是通过缓存应用程序 shell（显示您的应用程序所需的 HTML、JavaScript、CSS、字体和图像资源）以及内容来完成的，这些内容通常通过 AJAX 调用 REST API 来检索。

渐进式 Web 应用使用 service workers 来提供缓存。当“progressive”配置存在于您的 app.json 中时，Cmd 会在构建时使用 sw-precache 创建一个 service worker，该 service worker 会自动缓存应用程序 shell。您还可以通过在您的代码中添加 @sw-cache 注释来让 service worker 缓存 AJAX 请求。

// @sw-cache

想象一下一家商店，它从服务器检索即将发生的事件列表。我们可以让 Cmd 生成的 service worker 缓存 API 调用，以便在离线时结果可用，方法是将 @sw-cache 注释添加到 url

Ext.define('App.store.UpcomingEvents', {
    extend: 'Ext.data.Store',
    proxy: {
        type: 'ajax',

        // @sw-cache
        url: '/api/upcoming-events.json',
        reader: {
            type: 'json'
        }
    }
});

@sw-cache 注释可以放在任何字符串或对象属性之上。它所附加到的字符串应该是要缓存的 url。当 url 是动态的时（例如，它在路径或查询字符串中包含 id），您可以选择指定“urlPattern”配置来控制缓存哪些请求。例如，想象一下针对特定事件的 AJAX 请求

Ext.define('App.model.Event', {
    extend: 'Ext.data.Model',
    fields: ['id', 'name', 'date'],

    proxy: {
        type: 'rest',

        // @sw-cache { urlPattern: "\\/api\\/events\\/\\d+" }
        url : '/events'
    }
});

控制缓存行为

@sw-cache 注释接受许多选项

• urlPattern：一个正则表达式，当匹配时，会导致响应被缓存

• handler：默认为“networkFirst”。可以是以下之一

  • networkFirst 尝试通过从网络获取来处理请求。如果成功，将响应存储在缓存中。否则，尝试从缓存中满足请求。这是用于基本直读式缓存的策略。它也适用于 API 请求，在 API 请求中，您始终希望在可用时获得最新鲜的数据，但宁愿拥有陈旧的数据也不愿没有数据。

  • cacheFirst 如果请求与缓存条目匹配，则使用该条目进行响应。否则，尝试从网络获取资源。如果网络请求成功，则更新缓存。此选项适用于不更改或具有某些其他更新机制的资源。

  • fastest 并行地从缓存和网络请求资源。使用首先返回的任何一个进行响应。通常，这将是缓存版本（如果存在）。一方面，即使资源被缓存，此策略也将始终发出网络请求。另一方面，如果/当网络请求完成时，缓存将被更新，以便将来的缓存读取将是最新的。

  • cacheOnly 从缓存中解析请求，否则失败。当您需要保证不会发出网络请求时，此选项非常有用，例如在移动设备上节省电池电量。

  • networkOnly 尝试从网络获取 URL 来处理请求。如果获取失败，则请求失败。本质上，与根本不为 URL 创建路由相同。

• options：具有以下属性的对象

  • debug [Boolean] 确定是否将额外信息记录到浏览器的控制台。

  • networkTimeoutSeconds [Number] 应用于 toolbox.networkFirst 内置处理程序的超时。如果设置了 networkTimeoutSeconds，则任何花费的时间超过该时间的网络请求都将自动回退到缓存的响应（如果存在）。当未设置 networkTimeoutSeconds 时，将应用浏览器的本机网络超时逻辑。

  • cache [Object]

    • name [String] 用于存储 Response 对象的 Cache 的名称。使用唯一名称允许您自定义缓存的最大大小和条目的生存期。
    • maxEntries [Number] 对通过各种内置处理程序缓存的条目强制执行最近最少使用的缓存过期策略。您可以将此与专用于存储动态资源集条目且没有自然限制的缓存一起使用。将 cache.maxEntries 设置为例如 10 将意味着在缓存第 11 个条目后，最近最少使用的条目将自动删除。缓存永远不应超出 cache.maxEntries 条目。仅当也设置了 cache.name 时，此选项才会生效。它可以单独使用，也可以与 cache.maxAgeSeconds 结合使用。
    • maxAgeSeconds [Number] 对缓存条目强制执行最大生存期（以秒为单位）。您可以将此与专用于存储动态资源集条目且没有自然限制的缓存一起使用。将 cache.maxAgeSeconds 设置为例如 86400 将意味着任何超过一天的条目都将自动删除。仅当也设置了 cache.name 时，此选项才会生效。它可以单独使用，也可以与 cache.maxEntries 结合使用。

示例：限制 API 调用的缓存响应数量

如果我们只想缓存最近访问的十个即将发生的事件，我们可以通过添加

options: { cache: { name: ‘events’, maxEntries: 10 } }

到我们的 @sw-cache 注释来实现这一点。例如

Ext.define('App.model.Event', {
    extend: 'Ext.data.Model',
    fields: ['id', 'name', 'date'],

    proxy: {
        type: 'rest',
        // @sw-cache { urlPattern: "\\/api\\/events\\/\\d+", options: { cache: { name: 'events', maxEntries: 10 } } }
        url : '/events'
    }
});

注意： 在添加 @sw-cache 注释或更改 app.json 后，您需要运行“sencha app build”来测试您的更改。service-worker 仅包含在您应用程序的生产版本中。这是因为开发版本将每个代码文件作为单独的请求加载，因此在运行开发版本时，不可能预缓存应用程序 shell 所需的所有资源。请务必使用生产版本来测试缓存行为。

注意： 构建完成后，应用程序的首次重新加载将拾取对 progressive manifest 和缓存的更改。由于 service-worker 是在您在浏览器中重新加载应用程序时异步获取和安装的，因此它可能最初不会缓存在您的应用程序启动时发出的 API 调用。您可能需要第二次重新加载您的浏览器才能缓存启动期间发出的 API 调用。

serviceWorker 配置

除了 @sw-cache 注释之外，您还可以通过将 runtimeCaching 属性添加到 app.json 中的 progressive.serviceWorker 部分来配置 service worker 缓存请求。支持上面描述的所有选项。
因此，例如，要缓存即将发生的事件列表以及最近查看的十个事件的数据，您可以将以下内容添加到您的 app.json 中，而不是将 @sw-cache 注释添加到您的 store 和 model 类中。

这是一个包含 manifest 和 serviceWorker 配置的完整示例。

"progressive": {

    "manifest": {

        "name": "My App",
        "short_name": "My App",

        "icons": [{
            "src": "resources/icon-small.png",
            "sizes": "96x96"
        }, {
            "src": "resources/icon-medium.png",
            "sizes": "192x192"
        }, {
            "src": "resources/icon-large.png",
            "sizes": "256x256"
        }],

        "theme_color": "#054059",
        "background_color": "#054059",
        "display": "standalone",
        "orientation": "portrait",
        "start_url": "/index.html"
    },

    "serviceWorker": {

        "runtimeCaching": [
            {
                "urlPattern": "\\/api\\/events"
            }, 
            {
                "urlPattern": "\\/api\\/events\\/\d+",
                "options": {
                    "cache": {
                        "name": "events",
                        "maxEntries": 10
                    }
                }
            }
        ]
    }
}

注意：虽然您可以使用 app.json 中的 runtimeCaching 配置和 @sw-cache 注释来指定缓存行为，但 @sw-cache 注释将优先。因此，我们建议为您的应用程序选择一种方法，而不是混合使用两种方法。