Microloader

“Microloader”是 Sencha 用于 JavaScript 和 CSS 的数据驱动动态加载器的名称。Microloader 由 Sencha Cmd 作为生成应用程序的一部分提供。本指南将让你深入了解 Microloader 的作用以及如何针对你的特定要求进行调整。

需要澄清的是，Ext 6 使用的 Microloader 目前与 Ext JS 5 或 Sencha Touch 使用的 Microloader 不同。Ext JS 6 Microloader 提供了与 Sencha Touch microloader 提供的所有相同功能，但有一些改进和新的控件可在 "app.json" 文件中使用，稍后将在本文档中进一步讨论。所有 microloader 实现都由 Sencha Cmd 提供，microloader 的升级将通过“sencha app upgrade”进程应用。

清单

app.json

此文件用于指定应用程序的详细信息。此配置文件首先由 Sencha Cmd 构建进程使用。Sencha Cmd 转换 "app.json" 的内容，并将生成的清单传递给 Microloader 以在运行时使用。最后，Ext JS 本身也会咨询运行时清单以获取配置选项。

Ext.manifest

启动应用程序时，您会发现 "app.json" 的已处理内容加载为 “Ext.manifest”。Ext JS 6 使用您指定的 Ext.manifest 属性来执行诸如启用兼容性层之类的操作。Microloader 支持多种选项来加载此对象，我们将在后面讨论。

脚本标记

要使用 Microloader，您的页面需要包含以下脚本标记

<script id="microloader" data-app="12345" type="text/javascript" src="bootstrap.js"></script>

默认情况下，此脚本标记将被构建进程替换，但在开发期间用于加载应用程序。data-app 属性应在应用程序脚手架期间为您生成。这是一个在本地存储中使用的唯一 ID，用于防止数据冲突。

默认值和自定义

由 Sencha Cmd 生成的 "app.json" 文件包含许多您可能想要调整的属性。这些属性已在内联中记录，以解释它们各自控制的内容。

如果您要升级项目，则您的 "app.json" 可能不包含所有可能选项。执行升级后，任何缺失属性的默认值都可以在 “.sencha/app/app.defaults.json” 中找到。

以下是经常引起关注的属性。

indexHtmlPath

这是应用程序 HTML 文档的路径（相对于 "app.json" 文件）。默认情况下，此属性设置为 "index.html"。如果您的服务器使用 PHP、ASP、JSP 或其他技术，您可以更改此值以指向正确的文件，如下所示

"indexHtmlPath": "../page.jsp"

如果您更改此设置，您可能还需要更改您的 "output" 选项（见下文）。

framework

框架的名称；“ext”或“touch”。例如

"framework": "ext"

theme

对于 Ext JS 应用程序，这是主题包的名称。例如

"theme": "ext-theme-crisp"

toolkit

对于 Ext JS 6 应用程序，这是工具包包的名称。例如

"toolkit": "classic"

js

要加载的 JavaScript 代码文件的描述数组。默认情况下，Ext JS 6 应用程序将具有类似以下内容

"js": [{
    "path": "app.js",
    "bundle": true
}]

此条目指定应用程序的入口点。“bundle”标志表示当您运行 “sencha app build” 时，此条目应替换为构建的连接输出。您可以像这样向此数组添加其他文件

"js": [{
    "path": "library.js",
    "includeInBundle": true
},{
    "path": "app.js",
    "bundle": true
}]

当您添加额外文件时，有一些可选属性表示构建进程将如何处理它们。例如，在上述情况下，“library.js” 将包含在连接的构建输出中，并从运行时清单中删除。

如果您删除了 “includeInBundle”，则假定 “library.js” 驻留在您的应用程序文件夹中，然后将其复制到构建输出文件夹。该条目将保留在清单中，并由 Microloader 单独加载。

要简单地传递 Microloader 加载的条目（而不是被构建进程复制），请像这样添加 “remote” 属性

"js": [{
    "path": "library.js",
    "remote": true
},{
    "path": "app.js",
    "bundle": true
}]

虽然您可以向此数组添加条目，但大多数依赖项将出现在代码中的 “requires” 语句或 "app.json" 中（以要求包）。

注意：对于 Sencha Touch，您通常会在 “js” 数组中看到 “sencha-touch-debug.js”。Ext JS 6 不需要此条目，因为 “framework” 设置已足够。

css

您的 CSS 资产的处理方式与 JavaScript 略有不同。这是因为在库存 Sencha Cmd 应用程序中，CSS 是从 .scss 源编译的。 “css” 属性的初始内容看起来像这样

"css": [{
    "path": "boostrap.css",
    "bootstrap": true
}],

此 CSS 文件是一个简单的存根，它导入 "sass" 文件夹的构建。 “bootstrap” 标志表示该条目用于开发，但应从构建输出中删除。对于构建，已编译的 CSS 文件将附加到生成清单的 “css” 数组中。

最初，“bootstrap.css” 从框架中导入主题，看起来像这样

@import "..../ext-theme-neptune/build/ext-theme-neptune-all.css";

在您构建应用程序时，此文件会更新以指向最近构建的 CSS 文件。例如，如果您运行“sencha app build”，则生产 CSS 文件将由“bootstrap.css”导入，如下所示

@import "..../build/..../app-all.css";

“css”条目还支持“remote”属性。当未设置 remote 时，它们的操作方式与“js”条目相同，即它们被复制到构建输出文件夹中。

requires

此数组包含所需包的名称。当 Sencha Cmd 处理此列表时，它会自动下载并解压任何缺失的包到您的工作区中。同样，包可以在其“package.json”中包含requires。这些包也会根据需要下载并解压。

这些包名称还可以包含版本要求。有关指定版本号的详细信息，请参阅Sencha Cmd Packages。

output

“output”对象使您能够控制构建输出的生成位置和方式。此对象可以控制构建输出的许多方面。在我们上面对indexHtmlPath的使用中，我们告诉 Sencha Cmd 页面源是"../page.jsp"。为了完成此过程，我们使用output告诉 Sencha Cmd 构建的页面相对于构建的 JavaScript 和 CSS 的位置。为了保持与源树中相同的相对排列，我们将此添加到"app.json"

"output": {
    "page": {
        "path": "../page.jsp",
        "enable": false
    },
    appCache: {
        "enable": false
    },
    "manifest": {
        "name": "bootstrap.js"
    }
}

在这种情况下，我们还添加了“enable”并将其设置为 false。此组合告诉 Sencha Cmd 最终页面的位置，但不要通过复制源（如“indexHtmlPage”所指定）来生成它。

由于我们没有生成页面，因此 Microloader 脚本标记将包含相同的“src”值“bootstrap.js”。上面的“manifest”选项指示 Sencha Cmd 使用相同名称生成构建的 Microloader。对于 JSP 或 ASP 等服务器端模板环境，以及其他环境，这是常见的需求。

应用程序缓存

应用程序缓存是一个清单，用于确定浏览器应存储哪些资产以进行脱机访问。要启用此功能，只需切换输出对象中appCache属性的enable标志。例如

"output": {
    "page": "index.html",
    "appCache": {
        "enable": true
    }
}

此处看到的appCache属性用于确定构建过程是否会生成应用程序缓存清单文件。如果将其设置为 true，则清单将从 app.json 中顶级appCache配置对象生成。它看起来像这样

"appCache": {
    "cache": [
        "index.html"
    ],
    "network": [
        "*"
    ],
    "fallback": []
}

本地存储缓存

本地存储缓存系统是浏览器内置应用程序缓存中的一个独立脱机缓存系统。资产通过唯一键存储在本地存储中，在引导期间，这些资产将在尝试任何远程加载之前首先被请求。这允许应用程序非常快速地加载，并且无需互联网连接。此缓存还允许资产的增量修补，这意味着只有资产、css 或 js 的更改位才会通过网络加载。然后文件将在本地存储中修补并传递给用户。

此缓存通过update属性对每个资产启用。这可以设置为“full”或“delta”。以下是启用本地存储缓存的 JS 和 CSS 资产的示例。

// app.js will be delta patched on updates
"js": [
    {
        "path": "app.js",
        "bundle": true,
        "update": "delta"
    }
],

// app.css will be fully downloaded on updates
"css": [
    {
        "path": "app.css",
        "update": "full"
    }
]

在资产上启用本地存储缓存后，必须全局启用cache配置"app.json"。通常在开发构建期间，人们希望将其设置为 false，而在生产构建中将其设置为 true。

"cache": {
    "enable": false
}

还可以配置增量路径和生成。当deltas属性设置为真值时，所有使用本地存储缓存的资产都将在构建的"deltas"文件夹中生成增量。如果deltas设置为字符串，则该值将用作保存所有补丁文件的文件名。如果enable设置为 false，则增量切换将不起作用。

"cache": {
    "enable": true,
    "deltas": true
}

应用程序缓存和本地存储缓存都会立即加载文件以进行脱机访问。因此，更新的文件不会加载到用户的当前应用程序体验中。一旦 Microloader 检测并加载了新的应用程序缓存或本地存储文件，它将分派一个全局事件，允许您提示用户重新加载应用程序以获取最新更新。您可以通过将以下代码添加到应用程序来侦听此事件

Ext.application({
name: 'MyApp',
mainView: 'MyMainView',
onAppUpdate: function () {
    Ext.Msg.confirm('Application Update', 'This application has an update, reload?',
        function (choice) {
            if (choice === 'yes') {
                window.location.reload();
            }
        }
    );
}

更多

我们看到的许多属性都是构建过程的指令，而其他属性则由 Microloader 处理。如上所述，清单文件也由 Ext JS 理解为配置其某些功能的一种方式。有关这些和其他属性的详细信息，请参阅 "app.json" 中的注释。

构建配置文件

当应用程序具有多个变体时，我们可以向 "app.json" 添加一个“builds”对象来描述所需的构建，如下所示（摘自 Kitchen Sink）

"builds": {
    "classic": {
        "theme": "ext-theme-classic"
    },
    "gray": {
        "theme": "ext-theme-gray"
    },
    "access": {
        "theme": "ext-theme-access"
    },
    "crisp": {
        "theme": "ext-theme-crisp"
    },
    "neptune": {
        "theme": "ext-theme-neptune"
    },
    "neptune-touch": {
        "theme": "ext-theme-neptune-touch"
    }
}

“builds”中的每个键称为“构建配置文件”。该值是一组属性覆盖，应用于 "app.json" 的基本内容，以生成如下所述的输出清单文件。在这种情况下，“theme”属性是针对每个构建配置文件进行修改的唯一属性。

此外，还有两个其他可选属性是应用程序构建的常见变体：“locales”和“themes”。这些属性用于自动化生成最终构建配置文件的过程。例如，Kitchen Sink 使用“locales”

"locales": [
    "en",
    "he"
],

当给出“locales”或“themes”时，每个值都与“builds”中的每个条目组合以生成最终清单文件。在这种情况下，“neptune-en”、“neptune-he”、“crisp-en”等是最终构建配置文件名称。

生成清单文件

如前所述，在构建过程中，"app.json" 会进行转换，然后在运行时作为“Ext.manifest”呈现。此过程包括合并对象，非常类似于 Ext.merge，但有一个区别：当两个数组“合并”时，它们会连接在一起。

此转换的第一步是合并所需构建“环境”的设置（例如，“production”或“testing”）。在此之后，如果正在使用构建配置文件，则合并其内容。然后，如果根或构建配置文件指定了“toolkit”（“classic”或“modern”），则合并该对象的属性。最后，如果配置了打包器（“cordova”或“phonegap”），则合并其属性。

在伪代码中，这类似于以下内容

var manifest = load('app.json');

// These would come from the "sencha app build" command:
var environment = 'production';
var buildProfile = 'native';

mergeConcat(manifest, manifest[environment]);
if (buildProfile) {
    mergeConcat(manifest, manifest.builds[buildProfile]);
}
if (manifest.toolkit) {
    mergeConcat(manifest, manifest[manifest.toolkit]);
}    
if (manifest.packager) {
    mergeConcat(manifest, manifest[manifest.packager]);
}

包

生成清单文件的最后一步是添加任何必需的包。

当必需的包在其 package.json 中指定“js”或“css”条目时，这些条目会按包依赖顺序连接到已生成数组的前面。这允许包自行处理此类依赖项。

除了“js”和“css”条目之外，每个必需包的 package.json 文件的内容都会进行一些清理，并添加到最终清单文件中的“packages”对象中，该对象由包名称作为键。如果 "app.json" 已包含“packages”对象，则该对象将与相应 package.json 文件的内容合并。优先考虑 "app.json"，以允许其属性作为配置选项传递给包（见下文）。

在伪代码中，"app.json" 和 package.json 内容的合并如下所示

var manifest;  // from above

manifest.packages = manifest.packages || {};

var js = [], css = [];

// Expand required packages and sort in dependency order
expandAndSort(manifest.requires).forEach(function (name) {
    var pkg = load('packages/' + name + '/package.json');

    js = js.concat(pkg.js);
    css = css.concat(pkg.css);
    manifest.packages[name] = merge(pkg, manifest.packages[name]);
});

manifest.css.splice(0, 0, css);

var k = isExtJS ? 0 : manifest.js.indexOf('sencha-touch??.js');
manifest.js.splice(k, 0, js);

这会生成一个可能如下所示的 Ext.manifest

{
    "name": "MyApp",
    "packages": {
        "ext": {
            "type": "framework",
            "version": "5.0.1.1255"
        },
        "ext-theme-neptune": {
            "type": "theme",
            "version": "5.0.1.1255"
        },
        ...
    },
    "theme": "ext-theme-neptune",
    "js": [{
        "path": "app.js"
    }],
    "css": [{
        "path": "app.css"
    }],
}

此合并的结果意味着包“foo”可以在其 package.json 中提供一些全局选项（例如，“bar”）并设置其默认值。任何使用 foo 包的应用程序都可以像在 "app.json" 中这样配置此选项

"packages": {
    "foo": {
        "bar": 42
    }
}

包像这样检索此值

console.log('bar: ' + Ext.manifest.packages.foo.bar);

加载顺序

在开发中加载应用程序和从构建中加载应用程序之间的主要区别之一是浏览器呈现各个文件时的顺序。在以前的版本中，app.js 文件几乎是浏览器处理的第一个文件。随着其要求的陈述，加载了更多文件，并发现了它们的要求，依此类推。

然而，在构建中，此顺序是相反的。app.js 文件几乎总是构建输出中的最后一个文件。这很容易导致代码在开发中正常工作但在生产中失败的情况 - 显然这是一个不希望出现的结果。

使用 Ext JS 5，将用于构建的加载顺序添加到清单文件中，并用于按相同顺序加载文件。虽然这会使清单文件大得多，但它仅在开发期间使用。

加载清单文件

Microloader 将按照 "app.json" 中的描述加载您的应用程序，并通过 Ext.manifest 传递。为此，Microloader 必须首先加载清单。有三种基本方法可以实现此目的。

嵌入式清单

对于典型应用程序，只有一个主题、语言环境和框架选择，这会生成一个清单。此清单可以放置在输出标记文件中，以优化下载时间。

要启用此选项，请将以下内容添加到 "app.json"

"output": {
    "manifest": {
        "embed": true
    }
}

此设置将在标记文件中嵌入清单和 Microloader。

命名清单

如果您使用构建配置文件，则嵌入清单并不是一个选项。相反，Microloader 可以根据给定的名称在加载时请求清单。默认情况下，生成的 "app.json" 文件放置在与标记文件相同的文件夹中，这是默认清单名称。要指定不同的名称，您可以这样做

<script type="text/javascript">
    var Ext = Ext || {};
    Ext.manifest = 'foo';  // loads "./foo.json" relative to your page
</script>

此方法是通过生成名称而不是对其进行硬编码来管理服务器端构建配置文件的有用方式。

动态清单

有时您可能希望在客户端选择构建配置文件。为了简化此操作，Microloader 定义了一个名为 “Ext.beforeLoad” 的挂钩方法。如果您像以下内容一样定义此方法，则可以在 Microloader 处理它之前控制 “Ext.manifest” 的名称或内容，同时利用其平台检测功能。

<script type="text/javascript">
    var Ext = Ext || {};
    Ext.beforeLoad = function (tags) {
        var theme = location.href.match(/theme=([\w-]+)/),
            locale = location.href.match(/locale=([\w-]+)/);

        theme  = (theme && theme[1]) || 'crisp';
        locale = (locale && locale[1]) || 'en';

        Ext.manifest = theme + "-" + locale;
    };
</script>

以上内容取自 Ext JS 5 Kitchen Sink 示例。该示例在几个主题和 2 个语言环境（英语 “en” 和希伯来语 “he”）中构建。通过提供此方法，构建配置文件名称将更改为 “crisp-en” 等值，指示 Microloader 加载 “crisp-en.json” 清单，而不是 "app.json"。

构建配置文件选择过程可以是您的应用程序所需的任何内容。服务器端框架可能会在呈现页面时选择此内容。这可以基于 cookie 或其他个人数据。在上述情况下，它纯粹基于 URL。

平台检测/响应性

通常，设备或浏览器是关键选择标准，因此 Microloader 会将名为 “tags” 的对象传递给 beforeLoad。此对象包含作为属性检测到的各种平台标记。所有标记的集合如下

• phone
• tablet
• desktop
• touch
• ios
• android
• blackberry
• safari
• chrome
• ie10
• windows
• tizen
• firefox

beforeLoad 方法可以使用这些标记，甚至可以修改它们。此对象随后用于控制资产（清单中描述的 js 或 css 项）的过滤，以及由 platformConfig 设置的运行时配置值。然后，此挂钩允许您控制这些过滤器将匹配的内容。但是，修改标记主要是为了添加对您的应用程序有意义的新标记。自定义标记应以 “ux-” 为前缀。Sencha 提供的标记不会以该前缀开头。

清单指定的标记

清单还提供了一个 "tags" 属性，用于设置可用标记。此属性可以是字符串数组

"tags": ["ios", "phone", "fashion"]

或作为对象字面量，键为标记名称，值为该标记的值。

"tags": {
    "ios": true,
    "phone": true,
    "desktop": false,
    "fashion": true
}

提供时，这些标记将优先于自动检测的值。由于这些值由清单提供，因此它们将不可用于 "beforeLoad" 方法，并且在标记名称冲突的情况下，将覆盖该方法对标记所做的任何更新。