开发

宿主扩展工具 swan-extension-cli

介绍

swan-extension-cli 是一个面向开源宿主，扩展 extension 特色能力的自动化工具，提供：

  • 交互式的项目脚手架。
  • 一套标准化的宿主扩展模板，包括 API、组件能力的扩展。
  • 生成复杂能力模板的简易命令。
  • 一个运行时服务环境，该服务支持：
    • 基于 webpack 的打包构建功能，可产出 extension 编译产物；
    • 可本地调试。

swan-extension-cli 致力于为开源宿主扩展能力提供标准化的基础工具，开发者可以专注于开发能力上，而不必纠结于如何应用。

安装

预备环境

nodejs > 10.0.0

安装 cli

下载工具包之后，解压包，操作如下图：
图片

包目录结构如下

1
2
3
4
5
cli.zip
    ├── package.json
    ├── ext-demo // 宿主扩展能力最佳实践
    ├── index.js // 逻辑代码
    └── index.js.map

执行以下命令

cd cli
// 将 ext 命令链接到全局
sudo npm link

如图所示为执行成功
图片

Tips：ext 命令可在全局使用，建议避开 cli 目录

使用

安装之后，可以用下列命令检查版本是否正确

ext --version
// or ext -v

可以通过下列命令查看帮助

ext --help
// or ext -h

图片

Init 初始化项目

快速创建

ext init
// or ext i

在当前目录下，创建的为百度小程序宿主扩展包项目。

示例

1
2
3
4
5
6
# 创建项目
ext init

# 你会被提示：
# 起一个项目名称 (swan-ext)
# 想要哪种能力的扩展模板  (api | component | all)

图片

如果我们创建一个只扩展了 API 能力的基础项目 swan-ext ，那么项目结构如下：

1
2
3
4
5
6
7
swan-ext
    ├── config 打包配置
    ├── scripts 执行脚本
    └── src
        ├── api 扩展能力目录
        ├── common 通用逻辑处理函数目录
        └── utils 工具类函数目录

Tips：下面所有命令都要基于 swan-ext 这个项目根目录下执行。

add 添加模板

当你使用 ext init 来创建一个新项目的时候，有些模板会根据你选择的被预安装好。如果你想在一个已经被创建好的项目中添加其他模板，可以使用 ext add 命令，下面详细说下用法。

使用命令

// 基于 swan-ext 项目根目录
cd swan-ext
ext add <template>

template 参数说明

  • api：拉取扩展 API 能力模板到当前目录
  • component: 拉取扩展组件模板到当前目录

示例

1
2
3
4
5
# 添加 API 扩展模板
ext add api

# 添加组件扩展模板
ext add component

如下图所示，我们在 swan-ext 项目中添加组件模板，那么 /src 下会出现 component 文件夹。

图片

generate 生成模板/描述表

在一个已经创建好的项目中，当你作为一个不懂前端的小白，可能无法区分扩展能力属于哪一个类别，对应写在哪个文件里。在已经理解什么是扩展 API 的基础上，我们可以使用 ext generate 命令，来生成对应的能力模板。下面详细说下用法。

使用命令

// 基于 swan-ext 项目根目录
cd swan-ext
ext generate <option> // or ext g <option>

option 参数说明

  • –desc, -d 生成 API 的客户端描述表，
  • –method, -m 生成扩展复杂 API 的方法函数。

示例 1

1
2
3
4
5
6
7
8
# 生成单个 API 的描述表
ext generate --desc
or
ext g -d

# 你会被提示：
# 填写客户端、调起方式、apiName、参数等信息
# 生成描述表成功，请到 xxx 文件中查看

ext generate –desc 可以生成规范的描述表，存放在当前目录下的 descriptions 文件夹中。

图片

生成成功后，进入相应的 json 文件中查看，描述表如下图：

图片

示例 2

1
2
3
4
5
6
7
8
# 生成单个复杂 API 的 method 文件
ext generate --method
or
ext g -m

# 你会被提示：
# 选择扩展复杂 API 的类型 (有前端参数特殊处理的API | 有复杂上下文逻辑的 API | 纯前端 API | 监听类 API)
# 生成描述表成功，请到 xxx 文件中查看

ext generate –method 可以生成某种类型的扩展 API 的模板，详见扩展方式详述，并存入项目中对应的目录。

举例我们生成一个有复杂上下文逻辑的 method：

图片

生成成功后，进入相应的文件中查看，method 如下图，宿主可在该文件中进行能力的编写：

图片

check 校验格式

因为描述表配置错误，会造成该能力不可用。而 canIUseMap 格式不合规范，会造成该能力被判断为不可用。

因此，在开发过程中，请及时校验描述表 / canIUseMap 的格式是否正确，避免影响功能使用。

可以使用 ext check 命令，下面说下详细用法。

使用命令

// 基于 swan-ext 项目根目录
cd swan-ext
ext check <option> <filePath>

/**
* - option：校验文件的类型，必传。文件类型包括：描述表、canIUseMap。
* - filePath：校验文件的路径，只支持本地路径。
*    - 校验描述表时必传。
*    - 校验 canIUseMap 时，若没有指定文件路径，默认寻找当前模板下的固定文件路径。
*    - 文件需为 json 格式，否则无法校验。
*/

option 参数说明

  • –desc, -d 校验描述表
  • –caniuse, -c 校验 canIUseMap

示例 1

1
2
# 校验描述表是否符合规范
ext check --desc ./description.json

图片

示例 2

1
2
# 校验 canIUseMap 是否符合规范，不填路径默认查找当前项目中的 can i use
ext check -c (/src/can-i-use-map.json)

图片

build 打包

ext build 用于开发 / 生产环境打包，打包产出的 extension 包可用于调试 / 发布，下面说明详细用法。

Tips：确保 swan-ext 这个项目根目录安装了依赖，若无请执行npm i。

使用命令

// 基于 swan-ext 项目根目录
cd swan-ext
ext build <option>

option 参数说明

  • –dev, -d 开发环境打包
  • –prod, -p 生产环境打包

示例

1
2
3
4
5
# 打出开发环境可用的宿主扩展包
ext build --dev

# 打出生产环境可用的宿主扩展包
ext build --prod

如下图，打包成功后，在项目的 output 目录下可看到 extension.zip 包，里面包含了 extension.js 和 extension.css 文件。

图片

将该 zip 包发布上线即可使用。

serve 本地调试

ext serve 是启动本地调试服务，下面说明详细用法。

Tips：确保 swan-ext 这个项目根目录安装了依赖，若无请执行npm i。

使用命令

// 基于 swan-ext 项目根目录
cd swan-ext
ext serve [option]

option 参数说明

  • –port -p 指定服务端口，默认 8080

示例

1
2
3
4
5
# 启动本地调试服务，默认打包上传 http://localhost:8080
ext serve

# 启动本地调试服务，指定端口号为9000，打包上传 http://localhost:9000
ext serve -p 9000

启动本地服务，这个过程需要等待几分钟。

图片

编译成功会产出宿主扩展包 extension.zip 的二维码，已经宿主调试工具小程序的二维码。

图片

宿主替换 extension 包成功后，冷启宿主 app，即可生效。

扩展能力规范 打包与替换
版权声明： 创作共用-署名-禁止演绎