应用扩展开发

文档的此部分涉及创建自己的应用扩展。

假定您已经安装了官方的应用扩展之一。 当您开始构建自己的应用扩展时,掌握这些经验将非常有价值。 如果遇到问题,请访问我们的Discord服务器的频道#app-extensions

入门

应用扩展是npm软件包。 有两个用于创建应用扩展的官方工具包。 除非用于将第三方库安装到Vue中,否则应使用官方的App Extension入门工具包来创建不提供UI(如组件或指令)的应用扩展。 第二个官方工具包是UI工具包。 它有一个用于创建组件/指令的ui文件夹、一个用于单独测试组件/指令的ui/devQuasar应用、以及一个用于创建应用扩展(此应用扩展通过Quasar CLI将您的组件/指令注入到Quasar应用)的app-extension文件夹。 也可以使用UI套件,以便您的组件/指令也可以与Vue CLI或UMD一起使用。

$ quasar create my-ext --kit app-extension
# 或
$ quasar create my-ext --kit ui

它将提示您有关您的特定需求。 您是否需要安装脚本、卸载脚本,是否会提示用户一些问题? 仅选择您要使用的内容。 如果您另有决定,可以稍后手动添加。

为了本文档,我们假设我们以my-ext回答了应用扩展“ext-id”问题(对应上述提示)。 请记住,应用扩展源文件夹的文件夹名称可以与实际的my-ext不同。 最后,我们将发布新的npm软件包(quasar-app-extension-my-ext)。

根据您的响应,Quasar CLI将为您的应用扩展的源代码创建一个文件夹,该文件夹具有以下结构:

# app-extension kit
.
├── package.json
└── src
    ├── index.js      # 在索引API中描述
    ├── install.js    # 在安装API中描述
    ├── prompts.js    # 在提示API中描述
    └── uninstall.js  # 在卸载API中描述

# ui kit
.
├── app-extension
│   ├── package.json
│   └── src
│       ├── index.js           # 在索引API中描述
│       ├── install.js         # 在安装API中描述
│       ├── prompts.js         # 在提示API中描述
│       └── uninstall.js       # 在卸载API中描述
└── ui
    ├── package.json
    ├── build                  # 构建脚本
    ├── dev                    # Quasar应用程序,用于测试组件/指令
    └── src
        ├── components         # (可选)您的组件的文件夹
        │   ├── Component.js   # (可选)您的组件的代码
        │   └── Component.sass # (可选)您的组件的Sass
        ├── directives         # (可选)您的指令的文件夹
        │   ├── Directive.js   # (可选)您的指令的代码
        │   └── Directive.sass # (可选)您的指令的Sass
        ├── mixins             # (可选)mixin源码
        ├── index.js           # 导出和Vue注入
        └── index.sass         # Sass导入

除了src/index.js(来自app-extension工具包)或app-extension/src/index.js(来自ui工具包) 以外,其他所有文件都是可选的。 您可以随时手动添加或删除它们。

当使用UI套件时,您将有两个npm软件包。 一个用于应用扩展,另一个用于UI模块。 为了使用dev应用进行测试,请从ui文件夹中键入yarn dev。 在dev文件夹中创建要测试的页面,它们将自动注入到测试应用程序中。 另外,请查看package.json中的scripts部分,以了解可用的内容。 当您yarn build时,将创建一个dist文件夹,并填充各种类型的软件包(common、esm和umd)。

应用扩展脚本说明

名称说明
src/prompts.js在安装应用扩展时处理提示
src/install.js扩展应用扩展的安装过程
src/index.jsquasar devquasar build上执行
src/uninstall.js扩展了应用扩展的卸载过程

处理软件包依赖关系

如果您的应用扩展对某些软件包具有自己的依赖关系才能运行(除了Quasar CLI提供的软件包,例如“quasar”、“@quasar/extras”,“@quasar/app”,则您应该在/install.js和/index.js脚本中使用“api.compatibleWith()”-查阅安装API索引API),然后将它们yarn/npm安装到您的应用扩展文件夹中,这会将它们提供给托管应用。

示例:您正在创建一个依赖于“my-table”npm软件包的UI组件(名称是假的,只是为了在此处指出),那么您应该在您的应用扩展文件夹中yarn/npm安装“my-table”。

WARNING

绝对不要yarn/npm安装Quasar CLI提供的软件包,因为应用扩展不应具有如此侵入性,并迫使用户使用特定的Quasar版本。取而代之的是使用“api.compatibleWith(),这相当于轻声地说“对不起,如果您想使用我的应用扩展,则需要安装此版本的Quasar”。

手动测试

我们需要创建一个Quasar项目文件夹,以便在开发扩展程序时能够对其进行测试:

$ quasar create test-app

安装和提示脚本

TIP

详细了解如何使用提示API安装API.

在测试的Quasar项目文件夹中,我们手动添加了应用扩展。 请注意,由于我们要测试未发布的工作,因此我们并未指定npm软件包名称(尚未发布!),而是指定了用于开发的应用扩展文件夹的路径:

$ yarn add --dev file://path/to/our/app/ext/root
# or
$ yarn add --dev link://path/to/our/app/ext/root

您将需要确定哪个命令最适合您的环境。

WARNING

通过file:link:进行链接出现问题的报告很多。 这超出了Quasar的能力,但可能与您的开发环境有关,也就是说,您使用Windows的版本会有所不同。

然后我们调用它。 调用过程假定已经安装了应用扩展的软件包(我们之前已经完成了),并且跳过了这一步:

# 我们说我们的<ext-id>将是“my-ext”,因此:
$ quasar ext invoke my-ext

这将触发我们新的应用扩展安装。 每次进行更改并要测试它们时,都需要重做这两个步骤。

此外,如果您希望在开发应用扩展时在测试应用程序中具有HMR(热模块重载)功能,则您的quasar.conf.js > devServer > watchOptions将如下所示:

// quasar.conf.js
devServer: {
  watchOptions: {
    ignored: [
      'node_modules',

      // 确保将下面的<myextid>
      // 更改为您的应用扩展的名称:
      '!node_modules/quasar-app-extension-<myextid>'
    ]
  }
}

卸载脚本

TIP

详细了解如何使用卸载API.

假设您已按照上述部分安装了应用扩展,我们现在可以测试卸载脚本(如果有):

$ quasar ext uninvoke my-ext

上面的命令同样不会修改package.json和node_modules中的npm软件包。 它只是调用卸载脚本,并将其从测试Quasar应用程序项目文件夹中已注册/安装的应用扩展列表中删除。 但是您的最终用户将调用$ quasar ext remove my-ext来卸载它,这也会卸载npm软件包。

每次对卸载脚本进行更改并要对其进行测试时,都需要重做这些安装步骤并发出uninvoke命令。

索引脚本

在以上各节中,我们描述了如何测试提示、安装和卸载脚本。 现在是时候编写索引脚本了,这是您的App Extension的核心。

在这里,您可以篡改所有quasar.config.js选项、扩展Webpack配置、注册Quasar CLI命令、启动开发应用程序所需的外部服务等等。

结果是,每次执行$ quasar dev$ quasar build都会运行索引脚本。

为了测试索引脚本,您每次在应用扩展脚本代码中进行更改时,都可以重复上述卸载和安装过程。 但这变得非常乏味。 如果您在Unix OS(MacOS,Linux)上进行开发,则可以利用yarn link命令来创建符号链接将测试应用程序的node_modules文件夹链接到扩展程序的文件夹中:

$ cd /path/to/app/extension/folder

# 我们通过yarn注册扩展
$ yarn link

$ cd /path/to/quasar/testing/app/folder

$ yarn link quasar-app-extension-<ext-id>
# 在我们的演示案例中,是这样的:
# $ yarn link quasar-app-extension-my-ext

请记住,如果您需要yarn/npm install任何依赖项到您的应用扩展中,那么您还必须卸载您的应用扩展并将其重新安装在测试应用程序中:

$ cd /path/to/app/extension/folder

# 运行 yarn/npm command (install/uninstall, etc)

# 然后

$ cd /path/to/quasar/testing/app/folder

# 卸载应用扩展
$ quasar ext uninvoke my-ext

# 重新安装应用扩展
$ quasar ext invoke my-ext

您实际上只需要quasar ext invoke my-ext(安装)应用程序扩展来重新安装它。 以上信息仅供参考。

WARNING

在Windows上,有许多关于“ yarn link”问题的报告。 这超出了Quasar的能力,但可能与您的开发环境有关,也就是说,您使用Windows的版本会有所不同。

TIP

详细了解如何使用索引API.

发布

在完成您的App Extension并准备部署它之后,您所需要做的就是将其发布到npm存储库中。

在您的App Extension文件夹中,运行yarn publishnpm publish。 两者都做同样的事情。

WARNING

重要的是要记住不要从扩展程序的package.jsonname属性中删除quasar-app-extension-前缀,否则Quasar CLI将无法识别它。