高级 Sencha Cmd

本指南涵盖了高级用户可用的 Sencha Cmd 功能。

先决条件

建议在继续之前阅读以下指南

• Sencha Cmd 简介.
• 使用 Sencha Cmd.

安装注意事项

位置

安装程序允许你选择目标路径，但更改此路径可能会产生副作用（请参阅“多个已安装版本”部分）。理想情况下，所有版本的 Sencha Cmd 都安装在单个基础文件夹中，子文件夹以版本号命名。在 Windows 上，单用户安装的默认安装文件夹如下所示

C:\Users\myself\bin\Sencha\Cmd\n.n.n.n\

如果你更改此路径，请保留版本号文件夹，并在同一父文件夹中安装任何其他版本的 Sencha Cmd。

多个已安装版本

在命令提示符下，对 sencha 的所有调用都将转到最新安装的 Sencha Cmd 版本。有时此版本可能与当前应用程序不兼容。例如，如果应用程序出于某种原因特别需要 Sencha Cmd 5.1.3.61，你可以按如下所示调整控制台/终端的 PATH。

在 Windows 上，如下所示（n 是当前版本）

set PATH=C:\Users\Me\bin\Sencha\Cmd\5.1.3.61;%PATH%
sencha ....

在 OS X 和 Linux 上，如下所示

set PATH=~/bin/Sencha/Cmd/5.1.3.61:$PATH
sencha ....

通过上述调整，sencha 将路由到当前控制台或终端的所需版本。

配置

可以在命令行中传递给 Sencha Cmd 的任何参数都可以作为以下讨论的配置文件之一中的配置选项进行设置。如果你知道命令行选项，则只需将该选项添加到配置文件即可。

例如，要在配置中指定 sencha compile 的 ignore 参数，请添加此行

sencha.compile#ignore=attic

此特定设置不一定是推荐做法，但它只是为了说明语法。命令中位于 # 之前的部分是 Sencha Cmd 命令，用点分隔。在 # 之后是选项名称。

要设置全局选项（如 debug 日志记录），请执行以下操作

sencha#debug=true

随着 Sencha Cmd（尤其是编译器）的发展，配置变得越来越重要。

要查看当前配置属性，请运行此命令

sencha diag show

配置文件

类似于 Apache Ant（Sencha Cmd 的许多方面都基于它），配置应用于“先写先赢”模型。这对于允许命令行覆盖属性值至关重要。

加载配置的过程从当前目录开始搜索，并沿文件系统向上进行，直到找到工作区。在此过程中，Sencha Cmd 查找应用程序或 Sencha Framework SDK 的存在。在加载过程结束时，Sencha Cmd 按此顺序加载它检测到的以下任何文件

• ${app.dir}/app.json - 应用程序配置，当在应用程序文件夹中时，最具体的加载优先。
• ${app.dir}/.sencha/app/sencha.cfg - 应用程序配置，当在应用程序文件夹中时，最具体的加载优先。
• ${package.dir}/package.json - 包配置，当在包文件夹中时，最具体的加载优先。
• ${package.dir}/.sencha/package/sencha.cfg - 包配置，当在包文件夹中时，最具体的加载优先。
• ${workspace.dir}/workspace.json - 当您在工作区（或工作区中的应用程序或包）中时，工作区配置接下来应用。
• ${workspace.dir}/.sencha/workspace/sencha.cfg - 当您在工作区（或工作区中的应用程序或包）中时，工作区配置接下来应用。
• ${framework.dir}/cmd/sencha.cfg - 基于当前目录中应用程序或包的适用框架，这些属性接下来加载。
• ${home.dir}/.sencha/cmd/sencha.cfg - 您的个人配置接下来加载。这通常只设置高级属性。
• ${cmd.dir}/../sencha.cfg - 本地计算机 Sencha Cmd 配置接下来加载。这通常只设置高级属性。这从正在运行的 Sencha Cmd 的父文件夹加载，该文件夹保存 Sencha Cmd 的各种已安装版本。
• ${cmd.dir}/sencha.cfg - 最后，加载特定于 Sencha Cmd 版本的配置。

最重要的配置属性是命令行上传递的属性。这些属性将覆盖来自上述任何文件的属性。例如

sencha config -prop foo=42 then ...

这在加载配置文件之前将“foo”设置为 42，并且在 Sencha Cmd v3.1 及更高版本中，此设置“获胜”。

在大多数情况下，您可以通过其前缀来判断属性的来源

• app. -- 请参阅 "app.json" 和 ".sencha/app/sencha.cfg"。
• package. -- 请参阅 "package.json" 和 ".sencha/package/sencha.cfg"。
• workspace. -- 请参阅 "workspace.json" 和 ".sencha/workspace/sencha.cfg"。
• framework. -- 请参阅 Ext JS 或 Sencha Touch SDK 中的 "cmd/sencha.cfg"。
• cmd. -- 请参阅 Sencha Cmd 安装文件夹中的 "sencha.cfg"。

不需要在这些文件中设置这些属性，但这是默认设置，遵循此约定将帮助您管理这些设置。也就是说，有时可能需要应用程序覆盖工作区设置。为此，必须在 ".sencha/app/sencha.cfg" 中设置 workspace.foo 属性，因为这是应用程序级别的配置文件。当偏离约定时，建议留下评论。

使用 JSON 描述符

从 Sencha Cmd 5 开始，JSON 文件现在始终被视为比其对应的 "sencha.cfg" 文件具有更高的优先级。以前，这只适用于基于 Sencha Touch 的应用程序。

诸如 "app.json"、"package.json" 和 "workspace.json" 之类的文件的的内容被扁平化为具有应用的文件名前缀的属性（"app"、"package" 或 "workspace"）。例如，如果您将以下 JSON 对象放在 "workspace.json" 中

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

这会将 workspace.foo.bar 属性设置为值“42”。

此机制允许从 "app.json" 导入 app.id 属性以用于构建过程。

Java 系统属性

可能需要为 Sencha Cmd 设置 Java 系统属性，例如 HTTP 代理服务器设置。Cmd 安装文件夹中的 "sencha.cfg" 文件具有代理的默认设置，这些设置可以检测您的系统定义的代理。有关更多信息，请参阅 "${cmd.dir}/sencha.cfg" 中的注释。

注意：如果您需要更改其中任何设置，请使用 "${cmd.dir}/../sencha.cfg" 文件，以便在 Cmd 升级中保留这些设置。

这些属性影响 Sencha Cmd 访问 Web 以执行 sencha upgrade 或下载包的能力。这些选项在 Cmd v3.1.1 及更高版本中。

命令行详细信息

如果您经常使用 Sencha Cmd，这些技巧会有帮助。

最短唯一前缀

Sencha Cmd 中的所有命令、类别和选项都可以通过其全名或唯一的最短前缀指定。

为了说明，由于 generate 是 Sencha Cmd 中目前以字母“g”开头的唯一顶级类别，同样，app 是该类别中唯一以“a”开头的命令，因此以下命令是等效的

sencha generate app MyApp ../MyApp
sencha gen ap MyApp ../MyApp

重要提示虽然这在控制台或终端上可能很方便，但不是在脚本中使用极短/简洁的前缀的良好做法。在脚本中使用简洁的命令会使脚本难以理解或维护，并且如果新命令使短形式变得模棱两可，则可能会中断脚本。

命令链接

Sencha Cmd 命令行处理器执行给它的所有命令，直到它们全部分派完毕。这意味着您可以避免重新启动 Sencha Cmd 进程来执行多条命令的开销。要利用这一点，请在命令之间插入 and 或 then。

and 和 then 命令基于 Sencha Cmd 的执行模型及其命令和类别的层次结构。and 命令用于在与前一个命令相同的类别中执行另一个命令。这是最常见的用例。

例如，要生成一个控制器和两个模型，请使用以下命令

cd /path/to/MyApp
sencha generate controller Central and model User id:int and model Ticket id,name,email

在上面，两次使用 and 导致执行了两个 generate model 命令。then 命令类似于 and，不同之处在于下一个命令将是根类别的一部分（即 sencha 命令）。

例如，以下命令生成一个新模型，然后构建应用程序

cd /path/to/MyApp
sencha generate model User id:int,name then app build

响应文件

当命令链接开始使命令行变得太长而无法读取时，例如在复杂的构建脚本中，您可以将命令行参数放在一个文件中，并告诉 Sencha Cmd 从该文件中读取参数。

例如

cd /path/to/MyApp
sencha @file.sencha

在上面，读取 "file.sencha" 文件，并将每一行视为命令行参数，除非该行以“#”开头，在这种情况下将跳过该行。指定文件中的所有行都插入到命令行参数中，就好像它们在那里键入而不是 "@file.sencha" 一样。这意味着 "file.sencha" 也可以包含响应文件插入（例如，"@file2.sencha"）。

类别状态

出于性能原因，某些类别在多次执行的命令中维护状态。最好的例子是新的 compile 命令类别。compile 类别不会为每个命令读取所有源，而是维护类路径中所有文件的缓存。然后，此上下文可用于该类别中的所有命令。

以下命令在仅读取框架源一次的情况下重新构建 ext-all-dev.js 和 ext-all.js 文件

cd /path/to/MyApp
sencha compile -c sdk/src --debug=true concat -o sdk/ext-all-dev.js \
    and --debug=false concat -c -o sdk/ext-all.js

如果您不想使用此缓存，可能是因为下一组输出的文件集不同，请使用 then 命令，如下所示

cd /path/to/MyApp
sencha compile -c sdk/src --debug=true concat -o sdk/ext-all-dev.js \
     then compile -c app/foo --debug=true concat -o app/foo/foo-all.js

目前，只有 compile 类别在命令之间维护状态。

插件

虽然 Ext JS 和 Sencha Touch 都使用相同的 Sencha Cmd 安装，但很多时候命令会根据框架执行略有不同的操作。此外，某些命令可能只适用于一个框架。

为了适应这一点，Sencha Cmd 的功能被划分为两层：命令行（正确称为“Sencha Cmd”）和用于 Ant 的较低级别接口。具有这些特殊问题的命令从命令行路由到插件中。

Sencha Cmd 插件只是一个名为 "plugin.xml" 的文件中包含的 Ant 脚本，尽管对于在应用程序或工作区中执行的任何给定命令，可能有多个活动插件。

该过程首先查找最具体的可用插件，如下所示

• ${app.dir}/.sencha/app/plugin.xml
• ${workspace.dir}/.sencha/workspace/plugin.xml
• ${cmd.dir}/plugins/${framework.name}/${framework.plugin.version}/plugin.xml
• ${cmd.dir}/plugin.xml（也称为“默认插件”）

首先找到的这些插件基于当前目录。然后，Sencha Cmd 仅加载该插件，并根据给定的命令调用特定目标。但是，这些插件包含在下一级别加载插件所需的 Ant 调用。例如，如果找到应用程序插件，则它包含 workspace 插件的 import。该插件包含 framework 插件的 import，最后，该插件包含默认插件的 import。

扩展点

从技术上讲，最低的两级（framework 和默认插件）是唯一包含实际代码的插件。应用程序和 workspace 插件在默认情况下为空，但存在以允许用户扩展这些内置命令。这样做的目的是允许您添加逻辑，以强制执行对 Sencha Cmd 发出的代码生成请求的项目或应用程序标准。

例如，如果您想检查新模型定义是否遵循项目准则，即第一个字段始终为 id:string，请将其添加到应用程序或 workspace "plugins.xml"

<target name="-before-generate-model">
    <if>
        <not><matches string="${args.fields}" pattern="^id\:string,.*"/></not>
        <then>
            <fail>Models must have "id:string" as first field.</fail>
        </then>
    </if>
</target>

同样，您还可以提供一个挂钩，以便在添加新模型时更新其他系统。

<target name="-after-generate-model">
    ... post new/updated Model ${args.name} and ${args.fields} ...
</target>

实际目标名称因您扩展的插件而异。有关具体信息，请参阅各个 "plugin.xml" 文件中的注释。

注意。默认的 "plugin.xml" 文件导入 Ant Contrib，它提供了许多 有用的任务。

在 Ant 中使用

虽然 Sencha Cmd 的主要用途是在命令行（因此得名），但 Sencha Cmd 也可直接从 Ant 中使用。有关此级别提供的许多命令的详细信息，请参阅 Ant 集成 指南。

后续步骤

• Ant 集成
• Sencha Cmd 软件包
• Sencha 编译器参考