高级 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 的许多方面都基于它）类似，配置以“先写先赢”模型应用。这对于允许命令行覆盖属性值至关重要。

加载配置的过程从当前目录开始搜索，并向上遍历文件系统，直到找到 Workspace。在此过程中，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 插件只是一个 Ant 脚本，包含在名为 "plugin.xml" 的文件中，尽管对于在应用程序或工作区中执行的任何给定命令，可能存在多个活动插件。

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

• ${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 调用。例如，如果找到应用程序插件，它将包含工作区插件的 import。该插件包含框架插件的 import，最后，框架插件包含默认插件的 import。

扩展点

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

例如，如果您想检查新的模型定义是否遵循项目指南（例如，第一个字段始终是 id:string），请将其添加到应用程序或工作区的 "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 Compiler 参考