微加载器

“微加载器”是 Sencha 的数据驱动型动态 JavaScript 和 CSS 加载器的名称。微加载器由 Sencha Cmd 作为生成的应用程序的一部分提供。本指南将使您对微加载器的作用以及如何根据您的特定要求对其进行调整有扎实的了解。

重要的是要澄清，Ext 6 使用的微加载器与 Ext JS 5 或 Sencha Touch 使用的微加载器当前是不同的实现。Ext JS 6 微加载器提供与 Sencha Touch 微加载器提供的所有相同功能，但在 "app.json" 文件中进行了一些改进和新的控件，这将在本文档后面进一步讨论。所有微加载器实现均由 Sencha Cmd 提供，微加载器的升级将通过“sencha app upgrade”过程应用。

Manifest 文件

app.json

此文件是您指定有关应用程序详细信息的位置。此配置文件首先由 Sencha Cmd 构建过程使用。Sencha Cmd 转换 "app.json" 的内容，并将生成的 manifest 文件传递给微加载器以在运行时使用。最后，Ext JS 本身也会查阅运行时 manifest 文件以获取配置选项。

Ext.manifest

当您启动应用程序时，您将找到作为“Ext.manifest”加载的 "app.json" 的已处理内容。Ext JS 6 使用您指定的 Ext.manifest 属性来执行启用兼容性层等操作。微加载器支持多种选项来加载此对象，我们将在稍后讨论。

脚本标签

要使用微加载器，您的页面将需要包含以下脚本标签

<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”将包含在连接的构建输出中，并从运行时 manifest 文件中删除。

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

要简单地传递条目以供微加载器加载（并且不被构建过程复制），请添加“remote”（远程）属性，如下所示

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

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

注意：对于 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 文件将附加到生成的 manifest 文件的“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 包。

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”指定）来生成它。

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

Application Cache（应用程序缓存）

Application Cache（应用程序缓存）是一个 manifest 文件，用于确定浏览器应存储哪些资源以供离线访问。要启用此功能，只需切换输出对象中 appCache 属性的 enable 标志。例如

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

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

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

Local Storage Cache（本地存储缓存）

Local Storage Cache（本地存储缓存）系统是与浏览器内置 Application Cache（应用程序缓存）分离的离线缓存系统。资源通过唯一的键存储在本地存储中，并且在启动引导期间，将首先请求这些资源，然后再尝试任何远程加载。这允许应用程序加载速度非常快且无需互联网连接。此缓存还允许资源的增量补丁，这意味着只有您的资源、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"
    }
]

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

"cache": {
    "enable": false
}

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

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

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

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();
            }
        }
    );
}

更多

我们看到的许多属性都是对构建过程的指令，而另一些属性则由微加载器处理。如前所述，manifest 文件也被 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" 的基本内容，以生成如下所述的输出 manifest 文件。在这种情况下，“theme”（主题）属性是每个构建配置文件唯一被修改的内容。

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

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

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

生成 Manifest 文件

如前所述，"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]);
}

包

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

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

除了“js”和“css”条目外，每个必需包的 package.json 文件的内容都会被稍微清理一下，并添加到最终 manifest 文件中名为“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 中，将用于构建的加载顺序添加到 manifest 文件中，并用于以相同的顺序加载文件。虽然这使 manifest 文件大得多，但它仅在开发期间使用。

加载 Manifest 文件

微加载器将按照 "app.json" 中描述并在 Ext.manifest 中传递的方式加载您的应用程序。为此，微加载器必须首先加载 manifest 文件。有三种基本方法可以完成此操作。

嵌入式 Manifest 文件

对于典型的应用程序，只有一个主题、区域设置和框架选择，这会导致生成单个 manifest 文件。可以将此 manifest 文件放置在输出标记文件中，以优化下载时间。

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

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

此设置将 manifest 文件和微加载器嵌入到标记文件中。

命名 Manifest 文件

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

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

这种方法是在服务器端管理构建配置文件的一种有用方式，通过生成名称而不是硬编码名称。

动态 Manifest

有时您可能希望在客户端选择构建配置文件。为了简化此操作，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”manifest 而不是 "app.json"。

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

平台检测 / 响应式

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

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

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

manifest 指定的标签

manifest 还提供了一个“tags”属性，用于设置可用的标签。此属性可以是字符串数组

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

也可以是对象字面量，以标签名称作为键，其中值将是该标签的值。

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

当提供时，这些标签将优先于自动检测到的值。由于这些值由 manifest 提供，因此它们将不可用于“beforeLoad”方法，并且在发生标签名称冲突时，将覆盖该方法对标签所做的任何更新。