为了方便使用VSCode的开发者,ASCF团队开发并维护了VSCode插件——ASCF开发助手,提供了一键式项目创建快速转换及调试功能,帮助开发者开发元服务。
在使用VSCode插件前,需要先安装DevEco Studio并配置好环境变量。



可以通过切换左侧的模板类型为行业模板,自行选择对应的行业模板进行体验开发。当前已提供教育、电商、新闻、阅读和外卖模板。


| 项目信息 | 描述 |
|---|---|
| App ID | 可通过在HarmonyOS 开发者中心上,可以通过“开发者管理”左侧 > ID、证书和Profile > APP ID,可查询元服务的appid。 |
| 项目名 | 创建的该项目的项目名。 |
| 项目路径 | 创建的项目保存的路径,请确保选择的路径文件夹为空。 |
| 设备类型 | 可选择元服务可运行的设备类型,当前支持运行在手机/平板上。 |
App ID可以通过HarmonyOS 开发者中心查询,但是vscode插件目前不支持元服务生成签名,需要开发者将对应App ID的签名配置到新建项目根路径下的build-profile.json5文件signingConfigs字段中。其中签名配置可以使用DevEco Studio项目自动生成或者已有的签名。
例如:

可以点击VSCode下方运行按钮,编译元服务。如果已连接设备,会自动在已选择设备上运行元服务。

启动构建后,会自动打开ASCF Assistant运行日志面板,可以点击旁边齿轮按钮进行日志级别查看。

ASCF助手1.0.8及以上版本,支持HarmonyOS 4及以下设备上投屏功能,启动运行阶段自动开启投屏显示。
1、Mac OSX系统暂不支持投屏。
2、需要关闭运行时启动投屏功能,可以在setting > Ascf-plugin: Run And Start Screen Casting配置取消勾选即可。
开发者可以点击“选择设备”(功能按钮介绍图中的标注①),选择已连接在电脑的设备。如果连接设备发生变化,需要重新选择。开发者可以点击“选择设备”(功能按钮介绍图中的标注①),选择已连接在电脑的设备。如果连接设备发生变化,需要重新选择。支持HarmonyOS 4及以下设备、HarmonyOS 5.0及以上设备上调试运行。在设备选择列表会展示设备名称和系统版本,选择对应的设备进行调试运行。

切换连接设备后,需要在运行之前点击“选择设备”按钮切换设备。
开发者可以点击“编译环境”(功能按钮介绍图中的标注②),切换编译环境。
支持调试/发布编译环境。

选择HarmonyOS 4及以下设备,元服务有以下产物:
选择编译环境:调试,不分包,产物为entry\build\default\outputs\default\entry-default-signed.hap;
选择编译环境:调试,分包,在ascf\ascf_src目录添加ascf.config.json文件并配置{ "disableSubpackages": false },产物为ascf\build\name-default.zip;
在HarmonyOS 4及以下系统设备上,需要下载安装快应用加载器调试运行元服务,可使用adb命令在快应用加载器上运行上述产物。
通过服务器的方式:在上述产物目录下启动服务器,${appid}替换为自己的appid,${app}替换为产物名。
http-server -p 3000
adb reverse tcp:3000 tcp:3000
adb shell am start -a android.intent.action.VIEW -d hap://app/com.atomicservice.${appid} -p com.huawei.fastapp.dev --es pkgUrl http://127.0.0.1:3000/${app} 通过本地推包的方式:path/to/app替换为上述产物的路径,${appid}替换为自己的appid,${app}替换为产物名。
adb push path/to/app /data/local/tmp/
adb shell am start -a android.intent.action.VIEW -d hap://app/com.atomicservice.${appid} -p com.huawei.fastapp.dev --es pkgUrl file:///data/local/tmp/${app} 开发者可以点击“打开日志”(功能按钮介绍图中的标注④),开发者可通过日志级别和搜索关键词来筛选日志信息,还可以使用日志导出、折行显示、清空窗口日志等功能。设备连接电脑后可以点击
启动日志功能。

设备连接电脑,启动了ASCF元服务后,可以启动HiLog日志功能,查看对应级别日志。
HiLog日志窗口各个按钮的作用为:
单击该按钮可开启日志进程。
单击该按钮可暂停日志输出。
单击该按钮可恢复日志输出。
单击该按钮可以保存日志缓存到指定文件。
单击该按钮可以日志自动换行显示,否则日志按行显示。
单击该按钮可退出日志进程。
HarmonyOS 5.0及以上设备默认会根据项目的bundleName查询运行中的元服务的进程,查看该进程的日志。如果没有匹配到进程,自动选择“不限制”。如果需要查看启动日志需要先根据“不限制”启动日志,然后再运行元服务。

HarmonyOS 4及以下设备默认会查询运行中的元服务的进程,查看该进程的日志。如果没有匹配到进程,自动选择“不限制”。如果需要查看启动日志需要先根据“不限制”启动日志,然后再运行兼容版元服务。

元服务图标生成工具分为两部分:IDE工具和SDK。
IDE工具
和DevEco Studio中生成元服务图标的方式类似,在ASCF助手中开发也可以直接生成元服务图标。
ASCF助手1.0.5及以上版本支持使用元服务图标生成工具。
在安装ASCF助手并打开ASCF项目之后,在项目中右键任意文件夹,点击“生成元服务图标”即可打开元服务图标生成工具,如下图所示。

打开元服务图标生成工具之后,按照提示,点击选择一张图片。图片具体格式参考:元服务图标设计规范。

SDK
为了满足服务商使用场景,ASCF提供了SDK版本,帮助服务商集成元服务图标生成能力。
npm install @atomicservice/as-icon-generator
import { AsIconGenerator } from '@atomicservice/as-icon-generator';
// 注意:srcImg既可以是url也可以为image对象
const img = new Image();
img.src = 'src/assets/test.jpg';
const asIconGenerator = new AsIconGenerator({ srcImg: img });
// 获取颜色
const colors = await asIconGenerator.getColors();
// 注意:需要界面中展示出来所有可选的颜色,方便用户能够根据颜色来选择合适的颜色
asIconGenerator.setColor(colors[0]);
// 生成图片, agc: true 表示同时生成agc中使用的图标
const result = await asIconGenerator.generate({ agc: true });
// result.outputImage
// result.agcImage
如果选择的图片存在跨域的问题,由源图片的服务器配置支持跨域。
开发者主页在ASCF项目中的默认效果如下图所示:

当未打开ASCF项目时,点击元服务图标,如下图所示。点击图标可以新建、导入ASCF项目或者将小程序项目转换为ASCF项目。

元服务基础信息
元服务基础信息模块有:元服务图标、AppName、AppID、签名配置、运行时版本五个部分。

开发者主页左上角图标即为当前元服务项目的图标,点击开发者主页左上角的图标,即可打开元服务图标生成工具。点击元服务图标生成工具界面以外的地方或者点击工具界面下方的“关闭”按钮,可以关闭该工具。

AppName即为当前元服务项目的名称,点击“编辑名称”按钮,在弹出的对话框中可以修改元服务名称,之后点击保存即可修改元服务名称。

当前元服务项目的AppID。
显示当前元服务项目是否配置debug或者release签名。
根据元服务项目根路径下的build-profile.json5的signingConfigs字段来显示签名是否配置,不支持开发者自定义的targets签名配置。
点击“参考”,即可打开签名配置参考文档。点击“配置”,会打开build-profile.json5文件,开发者修改signingConfigs字段保存之后,开发者主页会自动刷新签名配置状态。

显示当前项目运行时版本。
快捷操作
点击“权限配置”,即可打开权限配置窗口。

勾选下方“未获取权限”列表中的权限,然后点击“申请权限”按钮,在弹出的界面中输入申请原因和调用时机,点击“保存”按钮后即可添加权限申请配置。

勾选上方“已获取权限”列表中的权限,然后点击“修改权限”按钮,在弹出的界面中修改申请原因和调用时机,点击“保存”按钮后即可修改权限申请配置。

在勾选权限之后,点击“删除权限”,可以删除不要的权限配置信息

使用分析包大小功能之前,请确保项目是可以正常编译的。
点击“分析包大小”按钮,即可开始对当前项目的包进行多种维度的分析。

点击“关闭服务”,即可关闭包大小分析。

基础配置
点击“编辑域名”按钮,会在浏览器跳转打开华为开发者官网配置服务器域名指南页面,方便查看配置指南文档。
点击“前往配置”按钮,会在浏览器跳转打开华为开发者官网为HarmonyOS应用开启华为开放能力指南页面,方便查看配置指南文档。
资源中心
点击“开发者文档”、“接口文档”、“服务商文档”、“鸿蒙小助手”、“元服务社区”这几个按钮,将在浏览器打开华为开发者官网相应的指导文档,方便查看相应的指导文档。
| ID | 标题 | 描述 |
|---|---|---|
| ascf-plugin.addProject | Create ASCF Project | 创建ASCF项目 |
| ascf-plugin.ascfBuild | Build ASCF | 构建ASCF |
| ascf-plugin.ascfBuild.clean | Clean | 清除 |
| ascf-plugin.ascfBuild.install | Install dependencies | 安装依赖 |
| ascf-plugin.ascfBuild.stop | Stop build ASCF | 停止构建 |
| ascf-plugin.ascfBuild.sync | Sync | 同步 |
| ascf-plugin.ascfBuildAndDebug | Build and debug ASCF | 构建并调试ASCF |
| ascf-plugin.ascfBuildAndDebug.stop | Stop build ASCF | 停止构建 |
| ascf-plugin.ascfBuildApp | Build ASCF App | 构建ASCF App |
| ascf-plugin.ascfDebugger.start | Start Debugger | 启动调试 |
| ascf-plugin.ascfDebugger.stop | Stop Debugger | 关闭调试 |
| ascf-plugin.chooseDevice | Choose device | 选择设备 |
| ascf-plugin.createAscfComponent | New ASCF Component | 创建ASCF组件 |
| ascf-plugin.createAscfPage | New ASCF Page | 创建ASCF页面 |
| ascf-plugin.createServiceWidget | New ASCF Service Widget | 创建ASCF服务卡片 |
| ascf-plugin.deleteRecentProject | Remove recent ASCF project | 移除最近的ASCF项目 |
| ascf-plugin.hilog | Hilog | Hilog |
| ascf-plugin.hilog.stop | Stop Hilog | 停止Hilog |
| ascf-plugin.importProject | Import miniprogram | 转换小程序资源 |
| ascf-plugin.initTypings | Init typings | 初始化typings |
| ascf-plugin.openProject | Open ASCF project | 导入ASCF项目 |
| ascf-plugin.openSelectProject | Open ASCF project | 导入ASCF项目 |
| ascf-plugin.showConvertReport | Show convert report | 显示转换报告 |
| ascf-plugin.startAbility | Start ability | 启动 |
| ascf-plugin.startScreenCast | Start ScreenCast | 启动投屏 |