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”过程应用。

Manifest

app.json

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

Ext.manifest

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

script 标签

要使用 Microloader，您的页面将需要包含以下 script 标签

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

默认情况下，此 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 中，并由 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 文件将附加到生成的 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”条目相同，因为它们会被复制到构建输出文件夹。

language

随着 Javascript 多年来的发展，不同版本的 ECMA Script 引入了新的特性和功能。由于有如此多的不同版本级别，Sencha Cmd 可以使用应用程序源代码的输入 ES 级别进行配置。这设置了解析源代码的正确级别，并用于确定是否需要转译输出。

默认情况下，Sencha Cmd 将输入语言设置为 ESNext（Google Closure Compiler 支持的最新 ES 级别），并且构建输出将转译为 ES5。这些值可以根据需要进行配置。

“language（语言）”配置用于更改这些默认值，并放置在“app.json”（或“package.json”，如果适用）或“workspace.json”中，用作应用程序和包的默认值。

例如，如果输入级别设置为 ES7，输出级别设置为 ES5，Sencha Cmd 将针对 ES7 语法解析输入，拒绝遇到的任何更高级别的语法。然后，它会将构建输出转译为 ES5。当您希望在更高版本的 ECMA Script 中进行开发，但又希望您的构建能够在可能不支持此类 ES 级别的系统上运行时，转译输入源代码非常有用。

Sencha Cmd 识别以下输入和输出的 ES 级别

"input": `ES5`, `ES6`, `ES7`, `ES8`, and `NEXT`
"output": `ES5`, `ES6`, `ES7`, `ES8`, `NEXT` and `ANY`

注意：即使输入值仅针对特定级别达到 ES8，Cmd 7.8.0 附带的当前版本的 closure compiler 也可以解析到 ES11。

“ANY”输出表示您不希望转译输入源代码，而应仅对其进行压缩。

以下是一些常见的用例。

默认语言配置 - 输入 ESNext 并将输出转译为 ES5

虽然这是默认语言配置，并且未在生成的 app.json 中指定，但以下是显式等效项，向您展示了如何手动配置它

 "language": {
     "js": {
         "input": "NEXT",  // Input ES level is closure compiler's highest supported level
         "output": "ES5"   // Transpile input source to ES5
     }
  },

配置 ES5 输入（不会发生转译）

以下内容将拒绝所有 ES6+ 语法（仅允许 ES5），并且由于默认输出为 ES5，因此不会发生转译。

   "language": {
       "js": {
           "input": "ES5" // Parse source against ES5, rejecting any higher level source
        }
    },

配置 ES6 输入并禁用转译器

如果您的目标环境本身支持高达 ES6，则可以并且应该禁用转译器，以获得尺寸和性能优势。以下内容将接受 ES6（及更低版本）的输入语法。由于输入和输出级别相同，因此不会发生转译。

     "language": {
         "js": {
             "input": "ES6", // Input level is ES6
             "output": "ES6" // As input and output levels match, no transpilation will occur
         }
    },

配置 NEXT 输入并将输出转译为 ES7

如果您希望使用最新的 ES 语法进行编码，但您的目标系统仅支持 ES7，则可以通过将输出级别配置为 ES7 来完成此操作。输入将针对 NEXT 语法进行解析，如果遇到任何 ES8 或更高版本的语法，输出将转译为 ES7。

     "language": {
         "js": {
             "output": "ES7" // Transpile ES8+ syntax down to ES7
         }
    },

禁用转译器

如果您的目标环境本身支持 ES6 及更高版本，则可以并且应该禁用转译器，以获得尺寸和性能优势。以下内容将接受语法并禁用转译器。

 "language": {
      "js": {
          "output": "ANY"
       }
    },

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 script 标签将包含相同的 “src” 值 “bootstrap.js”。上面的 “manifest（manifest）” 选项指示 Sencha Cmd 使用相同的名称生成构建的 Microloader。这是服务器端模板环境（如 JSP 或 ASP）以及其他环境的常见需求。

Application Cache（应用程序缓存）

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

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

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

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

Local Storage 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
}

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

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

Application Cache 和 Local Storage Cache 都可以立即加载文件以供离线访问。因此，更新后的文件将不会加载到用户当前的应用程序体验中。一旦 Microloader 检测到并加载了新的 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();
               }
           }
       );
   }

更多

我们已经看到的许多属性都是针对构建过程的指令，而另一些则由 Microloader 处理。如前所述，manifest 也被 Ext JS 理解为配置其某些功能的一种方式。有关这些属性和其他属性的详细信息，请查看 "app.json" 中的注释。

构建配置文件

当应用程序有多个变体时，我们可以将一个 “builds” 对象添加到 "app.json" 中，以描述所需的构建，如下所示（取自 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

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

嵌入式 Manifest

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

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

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

此设置会将 manifest 和 Microloader 嵌入到标记文件中。

命名 Manifest

如果您使用构建配置文件，则嵌入 manifest 不是一个选项。相反，Microloader 可以在加载时根据名称请求 manifest。默认情况下，生成的 "app.json" 文件与标记文件放在同一文件夹中，这是默认的 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。此对象包含它检测到的各种平台标签作为属性。所有标签的集合如下

• 手机
• 平板电脑
• 桌面
• 触摸
• ios
• 安卓
• 黑莓
• 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” 方法，并且在标签名称冲突的情况下，将覆盖该方法对标签所做的任何更新。