文档首页> Astro轻应用 AstroZero> 用户指南（低代码）> 经典版应用开发指导> 高级页面> 开发高级组件> 使用Scaffolding本地开发高级组件

更新时间：2023-04-24 GMT+08:00

查看PDF

使用Scaffolding本地开发高级组件

背景信息

为了提升组件开发、调测效率，AstroZero平台提供了一款脚手架工具（Scaffolding）。通过此工具创建本地资产工程，可帮助您快捷实现组件的新建、本地开发、调试、预览、发布、下载等主要功能。

Scaffolding脚手架工具，只支持在Windows上安装使用。

安装Scaffolding

在本地依次安装12.16.1~14.18.2版本之间的Node.js、yarn以及2.7.6版本的python，具体安装过程及环境变量的设置可参考相应官网。
- 如果是通过npm安装yarn，yarn的环境变量不会自动配置，需要在cmd命令行窗口执行“yarn global bin”，将命令执行结果显示的目录配置到电脑环境变量的“path”变量中。
- 在“计算机（win7）/此电脑（win10） > 属性”的高级系统设置中，单击“环境变量”，修改系统变量中的“path”变量，添加命令执行结果显示的目录。
单击下载链接，将工具压缩包“assets_starter.zip”下载到本地，进行解压，解压后目录结构如下图所示。

图1 Scaffolding脚手架工具目录结构

如果之前安装过Scaffolding脚手架，新工具解压后的目录可以覆盖原目录。
打开cmd命令窗口，进入解压后的assets_starter文件夹。
（由于工具升级过，如果之前安装过Scaffolding脚手架，安装目录不同且目录仍然存在，需先执行该步骤）卸载原工具。
在新解压后的assets_starter目录下，执行“yarn unlink”命令，显示如下类似信息，表示成功卸载原工具。
```
yarn unlink v1.12.3
success Unregistered "XXX".
info You can now run `yarn unlink "XXX"` in the projects where you no longer want to use this package.
Done in 0.14s.
```
首次使用Scaffolding脚手架工具，无需执行此步骤。其中上述显示的信息中“XXX”取决于已安装Scaffolding包“package.json”文件中“name”取值。例如“name”取值为“appengine-scaffolding”，“XXX”即为“appengine-scaffolding”。

使用yarn和npm之前，需要配置镜像地址，若之前没有配置过，请在cmd命令窗口执行如下命令按回车键。

若不配置，下一步安装Scaffolding时会报网络连接错误。

在cmd命令窗口执行如下命令按回车键，进行npm仓库配置：

npm config set registry https://repo.huaweicloud.com/repository/npm/
npm config set sass_binary_site https://repo.huaweicloud.com/node-sass
npm config set phantomjs_cdnurl https://repo.huaweicloud.com/phantomjs
npm config set electron_mirror https://repo.huaweicloud.com/electron/
npm config set cypress_install_binary 0
npm config set puppeteer_skip_chromium_download 0

在cmd命令窗口执行如下命令按回车键，进行yarn仓库配置：

yarn config set sass_binary_site https://repo.huaweicloud.com/node-sass
yarn config set phantomjs_cdnurl https://repo.huaweicloud.com/phantomjs
yarn config set electron_mirror https://repo.huaweicloud.com/electron
yarn config set registry https://repo.huaweicloud.com/repository/npm/
yarn config set cypress_install_binary 0
yarn config set puppeteer_skip_chromium_download 0

在assets_starter目录下，执行“yarn run bootstrap”命令安装Scaffolding。
显示如下类似信息且没有报错，表示安装成功。
```
success Registered "appengine-scaffolding".
info You can now run `yarn link "appengine-scaffolding"` in the projects where you want to use this package and it will be used instead.
Done in 147.28s.
```
- 安装过程中若出现“error No registered package found called "appengine-scaffolding".”错误，无需处理。
- 安装过程中若出现网络连接错误，例如“An unexpected error occurred: "https://registry.yarnpkg.com/killable/-/killable-1.0.0.tgz: connect ETIMEDOUT 104.16.19.35:443"”，这是由于资源地址请求超时造成的，更换一下请求地址即可。
为使用vue cli 2的模板功能，需要在cmd命令窗口，任意本地目录下执行如下加粗字体命令安装“vue/cli”和“vue/cli-init”。
```
yarn global add @vue/cli
yarn global add @vue/cli-init
```
显示如下类似信息，表示执行成功。
```
......
success Installed "@vue/cli@4.5.13" with binaries:
      - vue
Done in 23.56s.
```
执行如下加粗字体命令，使用yarn自身的workspace能力，来管理多个package的依赖。
```
yarn config set workspaces-experimental true
```
显示如下，表示执行成功。
```
success Set "workspaces-experimental" to "true".
Done in 0.07s.
```
（可选）若有新的工具压缩包需要升级，则直接使用新的包“assets_starter.zip”，重新解压覆盖本地包，执行“yarn run bootstrap”命令重新安装Scaffolding。

Scaffolding图形界面操作方式

成功安装脚手架工具后，您可通过界面操作方式使用该工具。

启动Scaffolding脚手架。

在cmd命令窗口任意目录下执行“magno ui”命令，会在浏览器中自动打开图形操作界面，如下图所示。
图2 Scaffolding图形操作界面首页
- 区域1所示为项目管理栏，可以新建或导入本地资产工程。
- 区域2所示为已有资产工程列表，首次使用Scaffolding脚手架工具此列表为空。
- 若未能正常启动脚手架工具，请参考异常处理中操作处理。
- 您也可以单击“导入”，导入已有应用工程包。

创建新应用（新应用即新资产工程）。

在Scaffolding图形界面首页中，单击“+ 新建”按钮。
在弹出的“创建新应用”弹窗中，设置新应用目录和名称。
图3 创建新应用-设置应用信息

若创建新应用时报错“failed to create app, TypeError: pinyin(...).flat is not a function”，处理步骤请参考•如果在命令行窗口执行“magno ui”命令打...。

单击“确认创建”按钮，完成应用创建。

应用创建成功后，会在脚手架图形界面首页应用列表中出现新建的应用，如下图所示。
图4 应用创建完成

新建的应用目录结构，如下图所示。

图5 应用工程目录

表1 目录说明
目录	功能
demos	预置的组件示例。
packages	用来存放创建的组件工程，每个组件都是一个package工程。
READMD.md	帮助文档，包含应用工程的初始化以及创建、预览、上传、及下载组件的命令行，您可以参考此文档通过命令行方式执行组件开发相关操作。

应用设置。

单击首页应用列表中新建的应用，进入组件管理页面。
图6 组件管理页面
以便您通过该脚手架工具访问AstroZero开发环境，进行组件调试、发布等操作，您需要使用OAuth 2.0协议客户端模式进行接入认证。若您已完成新建认证密钥操作，且已生成认证信息如下图所示。
图7 OAuth认证

单击上图操作列中“查看密钥”按钮，密钥信息会以文件形式下载到本地，您可以从中读取客户端ID（client_id）和客户端密钥（client_secret）信息，用于应用设置。

OAuth认证过程中新建认证密钥时授权类型需选择“客户端模式”，用户建议选择具有管理员权限（System Administrator Profile）的用户。关于OAuth认证的详细介绍，请参见认证鉴权。

单击组件管理页面中的“设置”，弹出“应用设置”弹窗（如下图所示），配置开发环境信息（参数说明见表2），单击“确定”。

图8 应用设置页面

表2 应用设置参数说明
参数	说明
AstroZero环境地址	AstroZero开发环境地址（例如：https://appcube.cn-north-4.huaweicloud.com/）。
客户端ID	通过该脚手架工具登录AstroZero开发环境时所需的客户端ID，获取方法参考3.b。
客户端密钥	通过该脚手架工具登录AstroZero开发环境时所需的客户端密钥，获取方法参考3.b。
上网代理	如果您的网络环境存在限制，需要使用代理服务器访问配置的AstroZero开发环境，则需要设置。
代理服务器地址	代理服务器的地址。开启上网代理后，该参数才会显示。
代理服务器端口	代理服务器的端口。开启上网代理后，该参数才会显示。
代理认证用户名	使用代理服务器时，代理认证的用户名。开启上网代理后，该参数才会显示。
代理认证密码	使用代理服务器时，代理认证的密码。开启上网代理后，该参数才会显示。

若在应用设置过程中出现图9所示错误，建议优先排查以下两条内容：

确定您的网络环境访问AstroZero环境时，是否需要设置上网代理。
申请OAuth认证记录时，选取的用户是否具有管理员权限（System Administrator Profile）、选取的授权类型是否为“客户端模式”。

图9 错误提示信息

新建组件。

在“组件管理”页面，单击“+ 新建组件”。
在“新建组件”页面，配置新组件参数信息，单击“创建新组件”。
图10 新建组件
- 组件类型：组件的类型，支持如下三种类型。
  - 高级页面组件：表示生成的组件工程可打包为用于高级页面开发的高级组件资产。创建的该类型组件会保存在本地应用工程目录下的“packages\advancedPageAssets”目录中。
  - 标准页面组件：表示生成的组件工程可打包为用于标准页面开发的组件资产。创建的该类型组件会保存在本地应用工程目录下的“packages\standardPageAssets”目录中。
  - vue高级页面组件：用于开发vue单文件组件，可打包成传统的组件包，用于开发高级页面（基于此类型开发的组件不同于高级页面组件和标准页面组件，不可直接用于AstroZero平台中）。创建的该类型组件，会保存在应用工程目录下的“packages\advancedPageAssets”中。
  - 卡片/卡片模板：用于开发卡片组件。
- 组件名称：该组件名称。
- 组件描述：组件的描述信息。
- 开发者：开发者信息。
开发高级组件（即应用于高级页面中的组件）时，组件类型应选择“高级页面组件”。

成功创建组件后，组件管理页面显示如下图所示。

图11 高级页面组件列表

表3 组件列表中功能按钮说明
按钮	名称	功能
	组件编辑	用于打开“组件编辑”页面，通过在线编辑器开发组件。
	打开本地编辑器	用于打开本地编辑器（支持Atom、Brackets、Visual Studio Code、IDEA、Notepad++、PyCharm、PhpStorm、RubyMine、Sublime Text、WebStorm等编辑器），在本地编辑器中开发组件。
	启动调试	用于启动调试，弹出页面提示“调试地址复制成功，组件Widget1的调试地址:https://localhost:8001/widget”。
	预览	用于预览组件图形界面效果，单击后浏览器弹出新的标签页，展示组件的DOM结构，其效果与高级页面发布后预览效果一致。组件DOM结构更改后，此页面会动态更新。
	组件设置	用于配置组件依赖的Library资源。
	编译	可编译组件，编译成功后会提示组件资产包的路径。
	发布	可将本地的该组件资产上传到AstroZero环境的组件库中。发布后，在对应开发环境的组件库中可以查看发布的组件。

在应用的“packages > advancedPageAssets”目录中，可查看到新建的组件“newWidget”，其目录结构如下图所示：

图12 组件目录结构

表4 组件目录说明
目录/文件	功能
dist	单击功能按钮中的“编译”按钮才会生成此目录，用于存放编译打包后的组件资产包。
preview	单击功能按钮中的“预览”按钮才会生成此目录，其内容为组件预览页面的代码。
widget	组件的源码包，在此目录中进行组件的开发，其中各文件的详细说明请参考在线开发高级组件。
package.json	应用工程中，当前组件工程包的元数据文件。

组件的预览与发布。
成功新建组件后，可以先试用下组件的预览与发布功能。
1. 预览。
  单击功能按钮中的“预览”按钮，预览效果。
  图13 组件预览示例
  
  在弹出的预览页面显示的“the dom of the widget”，是新建组件中DOM结构所包含的元素，其代码如下图所示：
2. 发布。
  单击功能按钮中的“发布”，在弹窗中填写组件分类等信息。确定发布后，可以在AstroZero开发环境创建的高级页面中，使用刚发布的组件。
  图14 组件发布示例
  在组件发布过程中，选取的“分类”与“领域”即是该组件在AstroZero环境中的分类与领域，在开发环境中要到相应的分类与领域中的自定义组件中查看及使用。
  
  建议在开发组件DOM结构时，使用组件的预览功能，预览功能可以动态更新组件DOM的变化。
  
  若在组件开发过程中，涉及事件-动作、桥接器等功能，建议您参考6，使用组件调试功能。
调试组件。
在本地开发组件后，频繁的打包组件资产包上传至AstroZero环境再查看页面显示效果，是一件效率极低的事情。通过如下配置，可打通本地开发环境与AstroZero开发环境，实现实时在线调测组件。

在进行组件调试前，需要将待调试的组件发布到AstroZero开发环境组件库中，并将其拖拽到高级页面中。若您还未执行相关操作，请参考5，并执行相应操作。
1. 在脚手架工具“组件管理”页面中，单击待调试组件所在行的“调试”按钮（例如本例中的“newWidget”），启动该组件的调试功能，系统会弹出“调试地址复制成功”提示框，说明您已成功启动组件调试并已复制调试地址。
  弹出提示框如下图所示：
2. 在成功获取组件调试地址后，需要在AstroZero开发工作台设置该组件的本地调试能力。
  在经典版应用设计器的左侧菜单栏下方，选择“ 页面设置”。在页面设置中选择“插件”页签，单击“本地调试设置”，操作步骤如图15所示。在大屏页面调试组件，可在大屏项目开发页面单击右上角齿轮图标，打开项目设置页面。选择“组件”页签，单击“本地调试设置”。
  图15 本地调试设置
  
  在大屏页面调试组件时，可在大屏项目开发页面单击右上角齿轮图标，打开项目设置页面。选择“组件”页签，单击“本地调试设置”。
3. 在弹出的“本地调试设置”弹窗中，配置该组件的“本地资源访问根路径”，此路径即为在6.a启动组件调试后复制的调试路径，在输入框中粘贴后单击“确认”。
  配置后，在预览使用该组件的高级页面后，会读取您本地资产工程文件夹下的组件包配置数据。
  图16 配置调试地址
  配置成功后，在预览包含该组件的高级页面时，会读取您本地资产工程文件夹下的组件包配置数据。
  
  在“本地调试设置”弹窗中，只会展现通过脚手架工具发布且已拖入高级页面的组件。
4. 在使用该组件的高级页面中，依次单击发布、预览，可查看该组件效果。
5. 高级页面发布预览后，就可以实现在本地资产工程中修改组件的代码进行调试。
  在脚手架工具“组件管理”页面，单击该组件所在行的组件编辑按钮，可打开“组件编辑”页面开发组件（或者单击打开本地编辑器按钮，在本地编辑器开发组件）。然后在AstroZero开发环境中刷新后预览新状态，进行调试开发。
  图17 组件本地调试示例
6. 组件调试完成后，在经典版应用设计器的左侧菜单栏下方，选择“ 页面设置”。在“插件”页签，单击“本地调试设置”，在“本地调试设置”页面选中该组件单击“清空本地资源访问根路径”，就会读取对应版本组件库中的配置数据，手动关闭调试功能。也可设置本地路径有效期，例如设置2，表示2天后系统自动清空所有的本地资源访问根路径，关闭调试功能。
  图18 单击“本地调试设置”
  
  图19 关闭本地调试功能
  
  在大屏页面调试组件时，可在大屏项目开发页面单击右上角齿轮图标，打开项目设置页面。选择“组件”页签，单击“本地调试设置”。在“本地调试设置”页面选中该组件单击“清空本地资源访问根路径”，就会读取对应版本组件库中的配置数据，手动关闭调试功能。
7. 至此，已完成本地组件的开发、调试工作，可以将其发布到AstroZero环境中正式使用。在脚手架工具“组件管理”页面单击该组件所在行的发布按钮，可将本地的该组件资产上传到AstroZero环境的组件库中。
  如果组件库中已有该组件包，会进行组件包的升级更新，升级更新后的组件需要在开发工作台左侧菜单栏下方选择“页面设置”，选择“插件”页签，在该组件所在行的操作列单击，更新站点内该组件。
  
  图20 发布升级组件示例
  
  在大屏页面调试组件时，可在大屏项目开发页面单击右上角齿轮图标，打开项目设置页面。选择“组件”页签，单击“检查更新”。在该组件所在行的操作列单击，更新站点内该组。
下载组件。
若您需要从AstroZero开发环境中下载自定义高级组件，请参考该步骤。以下载场景描述中介绍如何开发第三方库过程中开发的自定义组件（widget_demo_mintui）为例，展示如何通过Scaffolding脚手架工具下载自定义组件。

在“组件管理”页面，单击“下载组件”按钮，在弹出的“下载组件”页面选择要下载的组件，单击“确定”按钮即可将该组件下载到本地。

图21 下载自定义组件示例

上图预览页面中展现的组件并非该组件的正常视图效果，原因是该组件设置中缺少global_VueI18n库。在8中将介绍如何通过组件设置新增组件的库资源。

当前Scaffolding脚手架工具仅支持下载自定义组件，暂不支持下载AstroZero平台预置组件。
组件设置，新增库资源。
库是组件正常运行的依赖，在组件开发过程中可以通过Scaffolding脚手架工具配置本地资产工程中组件的依赖库。在“组件管理”页面，单击需新增库资源组件所在行的“组件设置”按钮，在弹出页面中单击“新增资源”按钮，选择所需资源库确定即可。

图22 组件设置-新增库资源示例

增加global_VueI18n资源库后，可见上图中预览页面组件已正常展示。

异常处理

如果在命令行窗口执行命令“magno”，提示“'magno' 不是内部或外部命令也不是可运行的程序或批处理文件”。
1. 在命令行窗口执行命令“yarn global bin”，查看用yarn安装的全局命令的目录，切换到该目录。
2. 在上一步切换后的目录下搜索“magno.cmd”文件，确认该文件所在目录。
3. 将“magno.cmd”文件所在目录添加到电脑环境变量的“path”变量中。
  在“计算机（win7）/此电脑（win10） > 属性”的高级系统设置中，单击“环境变量”，修改“path”变量，在值中添加文件“magno.cmd”所在目录。
4. 然后重新打开一个命令行窗口执行“magno”，检查命令结果。
如果在命令行窗口执行“magno ui”，提示“Windows 找不到文件'chrome.exe'。请确定文件名是否正确后，再试一次。”。
在本地桌面鼠标右键单击“Google Chrome”选择“属性”，检查起始位置中路径是否正确。如图23所示，“起始位置”设置的为管路员身份下的路径，而安装Scaffolding是在本地用户下安装的，需要修改“起始位置”为本地用户下“chrome.exe”所在的路径。
图23 Google Chrome“属性”页面
如果使用Mac终端安装该脚手架工具，安装后，在cmd命令窗口下执行“magno ui”命令，正常情况会显示打开操作界面的URL地址，但是提示“magno: command not found”或者“permission denied: magno”。可能是用户没有执行权限导致的。需要给用户添加执行权限，处理步骤如下：
1. 在命令行窗口执行命令“yarn global bin”，查看用yarn安装的全局命令的目录，切换到该目录。
2. 在上一步切换后的目录下执行“chmod u+x magno”，给用户添加执行权限。
3. 再执行“magno ui”命令，显示如下。
```
Starting GUI...
Ready on http://localhost:8080
```
4. 在Mac端打开新的浏览器页面，在地址栏输入上一步显示的URL。会打开Magno项目管理器操作界面。
如果在命令行窗口执行“magno”，提示类似如图24所示错误，处理步骤如下：
图24 执行结果
1. 在命令行窗口执行命令“where magno”，查看magno命令的安装位置。
2. 切换到该magno命令的安装所在目录，用编辑器打开“magno.cmd”文件，删除倒数第二行的“%~dp0\”。
  “magno.cmd”文件中删除如下加粗内容：
```
@IF EXIST "%~dp0\node.exe" (
  "%~dp0\node.exe"  "%~dp0\C:\Users\m00361589\AppData\Local\Yarn\Data\link\magno\bin\magno.js" %*
) ELSE (
  @SETLOCAL
  @SET PATHEXT=%PATHEXT:;.JS;=;%
  node "%~dp0\C:\Users\m00361589\AppData\Local\Yarn\Data\link\magno\bin\magno.js" %*
)
```
3. 然后重新打开一个命令行窗口执行“magno”，检查命令结果。

如果在命令行窗口执行“magno ui”命令报错“spawn cmd ENOENT”时，请检查环境变量是否正确配置，例如报错用户没有配置环境变量“C:\Windows\System32”（请查找“System32”所在路径后再配置），配置后，再次执行命令无报错。
如果在命令行窗口执行“magno ui”命令打开图形操作界面，创建新应用时报错“failed to create app, TypeError: pinyin(...).flat is not a function”，如下图所示。
处理步骤如下：
1. 请在命令行窗口执行“node -v”，检查Node.js版本，要求12.16.1~14.18.2版本之间。
2. 获取12.16.1~14.18.2版本之间的Node.js安装包重新安装。
3. 安装后重新打开一个命令行窗口执行“magno ui”命令，打开图形操作界面，创建新应用。
如果通过magno-ui，打开本地高级组件启用调试后获取的本地地址，在浏览器中进行调试时调试不成功。
处理步骤为：单击“高级”后，单击“继续前往”。

图25 单击高级

图26 单击继续前往