创建 Sencha Cmd 包

Sencha Cmd 包含 Sencha 包管理器。即使您不打算分发您创建的包，包也有很多用途。本指南涵盖创建自己的包以及分发它们的流程。有关使用包的信息，请参阅 Sencha Cmd 包。

生成包

在我们生成新包之前，我们必须首先为其创建一个家：工作区。对于此示例，我们将为此包使用 Ext JS，因此我们从以下命令开始

sencha -sdk /path/to/ext-n.n.n generate workspace /path/to/workspace

现在，我们导航到新工作区并生成包

cd /path/to/workspace
sencha generate package foo

包的剖析

上述步骤生成一个包含许多常用部分的入门包。你可以删除其中的许多部分，但重要的是保持".sencha"文件夹完好无损。

由sencha generate package生成的包的结构如下

packages/
    local/
        foo/                        # Top-level folder for the package
            .sencha/
                package/
                    sencha.cfg      # Sencha Cmd configuration for this package
                    build-impl.xml  # Generated build script for package
                    plugin.xml      # Sencha Cmd plugin for this package
                    codegen.json    # Data to support 3-way merge in code generator
            classic/                # Classic toolkit-specific src code
            examples/               # Example applications demonstrating the package
            licenses/               # License agreement
            modern/                 # Modern toolkit-specific src code
            overrides/              # Folder for automatically activated overrides
            resources/              # Static resources (typically has images folder)
            sass/                   # Container for styling code
                etc/                # General, non-component oriented styling
                example/            # - internal use
                src/                # Style rules named by component
                var/                # Variables and mixins named by component
            src/                    # Folder for normal JavaScript code
            build.xml               # Build script (called by `sencha package build`)
            package.json            # Package descriptor
            Readme.md               # High-level information about this package

虽然上述内容非常广泛，但成为包的唯一必需部分是"package.json"和".sencha/package/sencha.cfg"。

"package.json"文件包含包的描述。来自"theme-neptune"包的一个示例

{
    "name": "theme-neptune",
    "type": "theme",
    "creator": "Sencha",
    "summary": "Ext JS Neptune Theme",
    "detailedDescription": "The Neptune Theme provides a clean, modern style for Ext JS",
    "version": "n.n.n",
    "compatVersion": "n.n.n",
    "format": "1",
    "extend": "theme-neutral"
}

creator属性是你需要作为包作者设置的属性。没有对该文本进行验证，但它必须与你稍后讨论的本地包存储库中分配的名称相匹配。

在应用程序构建中集成包

大多数包的目的是（最终）集成到应用程序中。为了实现此目的，Sencha Cmd 在sencha app build过程中将每个必需包的各个部分合并到应用程序中。

具体如何进行取决于包的type。

包类型

不同类型的包扮演着不同的角色。Sencha Cmd 理解以下类型的包

• code - 应用程序或其他包使用的任意代码包。这些包是通用包，当有选择它们的require语句时包含在内。
• theme - 用作应用程序主题的包。主题很特别，因为在构建中只允许一个类型为theme的包“处于活动状态”。此主题由app.json中的theme属性选择。主题还可以使用extend从另一个主题包继承样式和资源。
• locale - 此包类型已被弃用，取而代之的是标准code包，其中classpath中包含theme.name。请参阅 Ext JS locale包以获取示例。

源代码

"src"文件夹是放置自定义组件或其他有用代码的类的地方。此代码自动包含在应用程序或其他包的classpath中，以便require和使用。

这可能是你放置大部分 JavaScript 代码的位置。放置在此文件夹中的类应遵循编译器友好代码准则。

样式

"sass"文件夹包含三个子文件夹，旨在处理样式编译的不同方面。

• "sass/etc" - 与 JavaScript 类无直接关系的代码
• "sass/var" - 变量定义（反映 JavaScript 类层次结构）
• "sass/src" - 混合和规则（反映 JavaScript 类层次结构）

"sass/var"和"sass/src"中的文件夹和文件被组织成它们所应用的 JavaScript 类的镜像。这种对应关系允许 Sencha Cmd 包含应用程序所需的类。不符合此要求的这些文件夹中的文件将永远不会被包含，因为该过程通过将 JavaScript 类层次结构映射到文件系统而不是扫描这些文件夹来进行。

名称对应关系由"package.json"中的namespace属性驱动

{
    "name": "MyPkg",
    ...

    "sass": {
        "namespace": "MyPkg",
        ...
}

在将必需的 JavaScript 类的类名映射到适当的.scss文件时，命名空间发挥作用。例如，给定类MyPkg.foo.Bar和上面的namespace，Sencha Cmd 将删除“MyPkg.”，并在"sass/var"和"sass/src"文件夹中查找“foo/Bar.js”的相对路径。

注意：即使 Fashion 不是 Sass 的实现，但出于兼容性考虑，保留了“sass”配置名称。

资源

"resources"文件夹是你放置包所需的静态资源的位置。当应用程序使用包时，它们会将这些资源复制到自己的"resources"文件夹的子文件夹中，该子文件夹以包名称命名。在这种情况下，"resources/foo"。如果你使用提供的theme-background-image方法，CSS 文件中使用的相对路径将自动更正。

覆盖

"overrides" 文件夹专门用于您的软件包提供强制覆盖，因此得名。应谨慎使用此机制，因为您放置在此文件夹中的所有代码都将自动要求任何使用此软件包的应用程序。

Ext JS Neptune 主题使用此机制来更改各种组件上的某些默认配置属性。区域设置软件包使用此机制将自己的文本注入到各种组件的原型上，或为诸如日期格式化之类的操作提供特定于区域设置的逻辑。

软件包版本

软件包具有描述其当前版本号的 version 属性。除了当前版本（在 version 属性中）外，软件包还可以使用 compatVersion 属性指示其向后兼容的程度。

在解决软件包要求时使用这些版本。软件包的每个版本都应具有更新的版本号。Sencha 分配给版本号的含义可能对您有所帮助

x.y.z.b

x = Major release number (large, impacting changes and features)
y = Minor release number (new functionality but few if any breaking changes)
z = Patch release number (bug fix / maintenance release - goal of 100% compatible)
b = Build number (assigned by build system)

version 属性通常最容易维护。但是，compatVersion 是关于用户应该能够透明升级并且不需要代码更改的程度的故意声明。

软件包要求

软件包可以要求其他软件包，就像应用程序可以要求软件包一样。为此，您需要添加到 requires 数组

{
    "name": "bar",
    "type": "code",
    "creator": "anonymous",
    "summary": "Short summary",
    "detailedDescription": "Long description of package",
    "version": "1.0.0",
    "compatVersion": "1.0.0",
    "format": "1",
    "local": true,
    "requires": [
        'ext-easy-button'
    ]
}

注意：作为软件包作者使用版本限制时，重要的是要考虑应用程序和所有必需的软件包都必须同意一个通用版本。如果您过于严格，此过程将无法为所有必需的软件包找到一个共同商定的版本。

软件包继承

软件包的继承概念专门针对主题。这些是继承的软件包内容被纳入派生软件包的最重要方式

• 继承的软件包的 "resources" 文件夹被复制到 "build" 输出文件夹中的 "resources" 文件夹中。
• 基本软件包的 overrides 会自动包含在派生软件包的构建输出中。

构建软件包

要发布软件包，您需要使用以下命令构建它

sencha package build

这会在软件包中生成一个 "build" 文件夹。当应用程序在“开发模式”（未编译）下运行时，需要此文件夹。

它还会在工作区的 "build" 文件夹中生成 "foo.pkg" 文件。此文件未放置在软件包的 "build" 文件夹中，原因如下

• 它是软件包文件夹的 ZIP 文件。
• 软件包用户不需要它。

"foo.pkg" 文件用于将软件包添加到您的本地存储库。见下文。

框架

您需要手动将 package.framework 指定添加到您的 "package.json" 文件。

"framework": "ext"

主题

您需要手动将 package.theme 指定添加到您的 "package.json" 文件。该值将是用于生成 CSS 的主题软件包的名称。

"theme": "theme-triton"

本地存储库

本地存储库在 Sencha Cmd 软件包中引入，但是当您要分发您创建的软件包时，还有更多需要了解的内容。

结构

由 Sencha Cmd 生成的本地存储库如下所示

.sencha/
    repo/
        sencha.cfg                  # Sencha Cmd configuration for the repo
        plugin.xml                  # Plugin for repository hooks
        private-key.json            # Private key for repo

        remotes/                    # Storage for remote repositories
            remoteName/             # Name given at `sencha repo add`
                catalog.json        # Last catalog from this remote

        trust/                      # Unused in this release
            <somename>.cert.json    # Copy of `cert.json` (a public key)

pkgs/
    catalog.json                    # Catalog of all packages in this repo
    cert.json                       # Public key for this repo

    Foo/
        catalog.json                # Catalog for all versions of Foo package
        cert.json                   # Public key for creator of Foo package

        1.0/                        # Folder containing version 1.0
            Foo.pkg                 # Zip file of package
            package.json            # Extracted package descriptor
        1.1/
            ...

    Bar/
        ...

作者身份

当 Sencha Cmd 生成默认本地存储库时，它不要求您提供任何类型的身份。这对于其作为缓存的角色来说很好，但作为软件包作者，您需要在您发布的软件包上署名。在发布软件包之前，您需要使用身份初始化本地存储库

sencha package repo init -name "My Company" -email "[email protected]"

完成此步骤后，您的姓名和电子邮件地址将与新的 公钥/私钥对 一起记录在本地存储库中。

注意：name 参数必须与您在 "package.json" 中设置的 creator 属性的值匹配。

公钥/私钥

您的姓名、电子邮件和公钥存储在 "pkgs/cert.json" 文件中。此文件将自动添加到您创建的软件包中，以将您标识为软件包作者。

显然，从其名称来看，您的私钥不打算与他人共享。它存储在本地存储库中的 ".sencha/repo/private-key.json" 中。

您可能希望备份这两个文件，因为它们将在将来的版本中发挥更重要的作用。

内容

"pkgs" 文件夹是存储所有软件包的位置。这些软件包可能是您创建的软件包，也可能是您下载的软件包。

当您添加软件包 ".pkg" 文件时，这些文件将复制到 "pkgs" 文件夹树中。

存储库挂钩

".sencha/repo/plugin.xml" 文件是一个 Ant 脚本，您可以使用它来提供“挂钩”，用于存储库操作，例如 sencha package add。有关此内容的更多详细信息，请参阅生成的文件中的注释。

添加软件包

一旦您从构建中获得了 ".pkg" 文件，并且假设您在本地存储库中设置的 name 与在 "package.json" 中定义的 creator 属性匹配，则可以运行此命令

sencha package add foo.pkg

Sencha Cmd 将使用您的私钥生成 ".pkg" 文件的哈希，并将其添加到您指定的 ".pkg" 文件中，然后将其复制到本地存储库。

现在软件包驻留在存储库中，如果其他开发人员添加了您的存储库作为远程存储库，则他们可以 require 它。

要求 Sencha 将您的 ".pkg" 添加到 Sencha 软件包存储库的过程仍在最后确定，但您可以查看 Sencha Market 以了解此方面的更新。

托管软件包存储库

"pkgs" 文件夹的结构是远程存储库所需的结构。其他人 require 您创建的软件包所需的所有内容是让他们添加一个远程存储库

sencha package repo add my-company http://my.company.com/packages

也就是说，假设您已在上述 HTTP URL 中托管了 "pkgs" 文件夹内容。除了 HTTP GET 访问之外，该托管不需要任何内容，因此静态文件服务器或 CDN 将起作用。