更新时间:2022-04-26 GMT+08:00
分享

使用Scaffolding本地开发高级组件

背景信息

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

本章节主要内容为介绍Scaffolding脚手架工具的安装流程及基本使用方法。

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

安装Scaffolding

  1. 在本地依次安装12.16.1~14.18.2版本之间的Node.js、yarn以及2.7.6版本的python,具体安装过程及环境变量的设置可参考相应官网。

    • 如果是通过npm安装yarn,yarn的环境变量不会自动配置,需要在cmd命令行窗口执行“yarn global bin”,将命令执行结果显示的目录配置到电脑环境变量的“path”变量中。
    • 在“计算机(win7)/此电脑(win10) > 属性”的高级系统设置中,单击“环境变量”,修改系统变量中的“path”变量,添加命令执行结果显示的目录。

  2. 单击下载链接将工具压缩包“assets_starter.zip”下载到本地,进行解压,解压后目录结构如下图所示。

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

    【信息】如果之前安装过Scaffolding脚手架,新工具解压后的目录可以覆盖原目录。

  3. 打开cmd命令窗口,进入解压后的assets_starter文件夹。
  4. (由于工具升级过,如果之前安装过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”。

  5. 使用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

  6. 在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"”,这是由于资源地址请求超时造成的,更换一下请求地址即可。可参考5配置镜像地址。

  7. 为使用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.

  8. 执行如下加粗字体命令,使用yarn自身的workspace能力来管理多个package的依赖。

    yarn config set workspaces-experimental true

    显示如下,表示执行成功。

    success Set "workspaces-experimental" to "true".
    Done in 0.07s.

  9. 可选)若有新的工具压缩包需要升级,则直接使用新的包“assets_starter.zip”,重新解压覆盖本地包,执行“yarn run bootstrap”命令重新安装Scaffolding。

Scaffolding图形界面操作方式

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

  1. 启动Scaffolding脚手架。

    在cmd命令窗口任意目录下执行“magno ui”命令,会在浏览器中自动打开图形操作界面,如下图所示。
    图2 Scaffolding图形操作界面首页

    【信息】图中区域1所示为项目管理栏,可以新建或导入本地资产工程;区域2所示为已有资产工程列表,首次使用Scaffolding脚手架工具此列表为空。

    若未能正常启动脚手架工具请参考异常处理

  2. 创建新应用(新应用即新资产工程):

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

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

    3. 单击“确认创建”按钮,完成应用创建。
      • 应用创建成功后,会在脚手架图形界面首页应用列表中出现新建的应用,如下图所示。
        图4 应用创建完成
      • 新建的应用目录结构如下图所示
        图5 应用工程目录

        说明如下表所示。

        表1 目录说明

        目录

        功能

        demos

        预置的组件示例。

        packages

        用来存放创建的组件工程,每个组件都是一个package工程。

        READMD.md

        帮助文档,包含应用工程的初始化以及创建、预览、上传、及下载组件的命令行,您可以参考此文档通过命令行方式执行组件开发相关操作。

    【信息】您也可单击“导入”,导入已有应用工程包。

  3. 应用设置。

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

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

      【信息】OAuth认证过程中新建认证密钥时授权类型需选择“客户端模式”,用户建议选择具有管理员权限(System Administrator Profile)的用户。

      OAuth认证相关详细信息请参考认证鉴权

    3. 单击组件管理页面中的“设置”按钮,弹出“应用设置”弹窗(如下图所示),配置开发环境信息(参数说明见表2),单击“确定”按钮;
      图8 应用设置页面
      表2 应用设置参数说明

      参数

      说明

      AppCube环境地址

      AppCube开发环境地址(例如:https://appcube.cn-north-4.huaweicloud.com/)。

      客户端ID

      通过该脚手架工具登录AppCube开发环境时所需的客户端ID,获取方法参考3.b

      客户端密钥

      通过该脚手架工具登录AppCube开发环境时所需的客户端密钥,获取方法参考3.b

      上网代理

      非必选,如果您的网络环境存在限制,需要使用代理服务器访问配置的AppCube开发环境,则需要设置。

      代理服务器地址

      开启上网代理后,该参数才会显示。表示代理服务器的地址。

      代理服务器端口

      开启上网代理后,该参数才会显示。表示代理服务器的端口。

      代理认证用户名

      开启上网代理后,该参数才会显示。表示使用代理服务器时,代理认证的用户名。

      代理认证密码

      开启上网代理后,该参数才会显示。表示使用代理服务器时,代理认证的密码。

      【信息】若在应用设置过程中出现下图所示错误,优先建议排查以下两条内容:

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

  4. 新建组件。

    1. 在“组件管理”页面单击“+ 新建组件”按钮,在“新建组件”页面配置新组件参数信息,单击“创建新组件”按钮。
      图9 新建组件
      表3 “新建组件”页面参数说明

      参数

      说明

      组件类型

      组件类型,系统目前支持三种类型。
      • 高级页面组件:表示生成的组件工程可打包为用于高级页面开发的高级组件资产。创建的该类型组件会保存在本地应用工程目录下的“packages\advancedPageAssets”目录中。
      • 标准页面组件:表示生成的组件工程可打包为用于标准页面开发的组件资产。创建的该类型组件会保存在本地应用工程目录下的“packages\standardPageAssets”目录中。
      • vue高级页面组件:用于开发vue单文件组件,可打包成传统的组件包,用于开发高级页面(基于此类型开发的组件不同于高级页面组件和标准页面组件,不可直接用于AppCube平台中)。创建的该类型组件会保存在应用工程目录下的“packages\advancedPageAssets”目录中。
      • 卡片/卡片模板:用于开发卡片组件,卡片的介绍请参见开发卡片组件

      组件名称

      该组件名称。

      组件描述

      组件的描述信息,可选。

      开发者

      开发者信息,可选。

      【信息】开发高级组件(即应用于高级页面中的组件)时,组件类型应选择“高级页面组件”。

    2. 成功创建组件后,组件管理页面显示如下图所示。
      图10 高级页面组件列表
      组件列表中功能按钮说明见下表。
      表4 组件列表中功能按钮说明

      按钮

      名称

      功能

      组件编辑

      用于打开“组件编辑”页面,通过在线编辑器开发组件。

      打开本地编辑器

      用于打开本地编辑器(支持Atom、Brackets、Visual Studio Code、IDEA、Notepad++、PyCharm、PhpStorm、RubyMineSublime Text、WebStorm等编辑器),在本地编辑器中开发组件。

      启动调试

      用于启动调试,弹出页面提示“调试地址复制成功,组件Widget1的调试地址:https://localhost:8001/widget”。

      预览

      用于预览组件图形界面效果,单击后浏览器弹出新的标签页,展示组件的DOM结构,其效果与高级页面发布后预览效果一致。组件DOM结构更改后,此页面会动态更新。

      组件设置

      用于配置组件依赖的Library资源。

      编译

      编译组件,编译成功后会提示组件资产包的路径。

      发布

      可将本地的该组件资产上传到AppCube环境的组件库中。发布后,在对应开发环境的组件库中可以查看发布的组件。

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

      图11 组件目录结构

      组件目录说明如下表所示:

      表5 组件目录说明

      目录/文件

      功能

      dist

      单击功能按钮中的“编译”按钮才会生成此目录,用于存放编译打包后的组件资产包。

      preview

      单击功能按钮中的“预览”按钮才会生成此目录,其内容为组件预览页面的代码。

      widget

      组件的源码包,在此目录中进行组件的开发,其中各文件的详细说明请参考在线开发高级组件

      package.json

      应用工程中当前组件工程包的元数据文件。

  5. 组件的预览与发布:

    成功新建组件后,可以先试用下组件的预览与发布功能。

    1. 预览:单击功能按钮中的“预览”按钮,其效果如下图所示:
      图12 组件预览示例

      【信息】在弹出的预览页面显示的“the dom of the widget”是新建组件中DOM结构所包含的元素,其代码如下图所示:

    2. 发布:单击功能按钮中的“发布”按钮,在弹窗中填写组件分类等信息,确定发布后可以在AppCube开发环境创建的高级页面中使用刚发布的组件,其操作步骤如下图所示:
      图13 组件发布示例

      【信息】在组件发布过程中选取的“分类”与“领域”即是该组件在AppCube环境中的分类与领域,在开发环境中要到相应的分类与领域中的自定义组件中查看及使用。

      【信息】建议您在开发组件DOM结构时使用组件的预览功能,预览功能可以动态更新组件DOM的变化。

      【信息】若在组件开发过程中涉及事件-动作、桥接器等功能,建议您参考步骤6,使用组件调试功能。

  6. 调试组件。

    在本地开发组件后,频繁的打包组件资产包上传至AppCube环境再查看页面显示效果,是一件效率极低的事情。通过如下配置,可打通本地开发环境与AppCube开发环境,实现实时在线调测组件。

    【信息】在进行组件调试前,需要将待调试的组件发布到AppCube开发环境组件库中,并将其拖拽到高级页面中,若您还未执行相关操作,请参考步骤5,并执行相应操作。

    1. 在脚手架工具“组件管理”页面中单击待调试组件所在行的“调试”按钮(例如本例中的“newWidget”),启动该组件的调试功能,系统会弹出“调试地址复制成功”提示框,说明您已成功启动组件调试并已复制调试地址。

      弹出提示框如下图所示:

    2. 在成功获取组件调试地址后,需要在AppCube开发工作台设置该组件的本地调试能力。在开发工作台左侧菜单栏下方选择“ 页面设置”,在页面设置页选择“插件”页签,单击“本地调试设置”,操作步骤如图14所示。在大屏页面调试组件,可在大屏项目开发页面单击右上角齿轮图标,打开项目设置页面。选择“组件”页签,单击“本地调试设置”。
      图14 本地调试设置

      【信息】当在大屏页面调试组件时,可在大屏项目开发页面单击右上角齿轮图标,打开项目设置页面。选择“组件”页签,单击“本地调试设置”。

    3. 在弹出的“本地调试设置”弹窗中配置该组件的“本地资源访问根路径”,此路径即为在6.a启动组件调试后复制的调试路径,在输入框中粘贴后单击“确认”。
      配置后,在预览该App中使用该组件的高级页面后,会读取您本地资产工程文件夹下的组件包配置数据。
      图15 配置调试地址

      【信息】配置成功后,在预览包含该组件的高级页面时,会读取您本地资产工程文件夹下的组件包配置数据。

      【信息】在“本地调试设置”弹窗中只会展现通过脚手架工具发布且已拖入高级页面的组件。

    4. 开发工作台使用该组件的高级页面中依次单击发布、预览按钮,可查看该组件效果。
    5. 高级页面发布预览后,就可以实现在本地资产工程中修改组件的代码进行调试。在脚手架工具“组件管理”页面单击该组件所在行的组件编辑按钮,可打开“组件编辑”页面开发组件(或者单击打开本地编辑器按钮,在本地编辑器开发组件)。然后在AppCube开发环境中刷新后预览新状态,进行调试开发,示例如下图所示:
      图16 组件本地调试示例
    6. 组件调试完成后,在开发工作台左侧菜单栏下方选择“ 页面设置”,选择“插件”页签,单击“本地调试设置”,在“本地调试设置”页面选中该组件单击“清空本地资源访问根路径”,就会读取对应版本组件库中的配置数据,手动关闭调试功能。也可设置本地路径有效期,例如设置2,表示2天后系统自动清空所有的本地资源访问根路径,关闭调试功能。
      图17 单击“本地调试设置”
      图18 关闭本地调试功能

      【信息】当在大屏页面调试组件时,可在大屏项目开发页面单击右上角齿轮图标,打开项目设置页面。选择“组件”页签,单击“本地调试设置”。在“本地调试设置”页面选中该组件单击“清空本地资源访问根路径”,就会读取对应版本组件库中的配置数据,手动关闭调试功能。

    7. 至此,已完成本地组件的开发、调试工作,可以将其发布到AppCube环境中正式使用。在脚手架工具“组件管理”页面单击该组件所在行的发布按钮,可将本地的该组件资产上传到AppCube环境的组件库中。

      如果组件库中已有该组件包,会进行组件包的升级更新,升级更新后的组件需要在开发工作台左侧菜单栏下方选择“页面设置”,选择“插件”页签,在该组件所在行的操作列单击,更新站点内该组件。操作实例如下图所示:

      图19 发布升级组件示例

      【信息】当在大屏页面调试组件时,可在大屏项目开发页面单击右上角齿轮图标,打开项目设置页面。选择“组件”页签,单击“检查更新”。在该组件所在行的操作列单击,更新站点内该组。

  7. 下载组件。

    若您需要从AppCube开发环境中下载自定义高级组件,请参考该步骤。以下载场景描述中介绍如何开发第三方库过程中开发的自定义组件(widget_demo_mintui)为例,展示如何通过Scaffolding脚手架工具下载自定义组件。操作方法如下图所示:

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

    图20 下载自定义组件示例

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

    【信息】当前Scaffolding脚手架工具仅支持下载自定义组件,暂不支持下载AppCube平台预置组件。

  8. 组件设置,新增库资源。

    库是组件正常运行的依赖,在组件开发过程中可以通过Scaffolding脚手架工具配置本地资产工程中组件的依赖库。在“组件管理”页面,单击需新增库资源组件所在行的“组件设置”按钮,在弹出页面中单击“新增资源”按钮,选择所需资源库确定即可。操作示例如下图所示:

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

    【信息】增加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”选择“属性”,检查起始位置中路径是否正确。如图22所示,“起始位置”设置的为管路员身份下的路径,而安装Scaffolding是在本地用户下安装的,需要修改“起始位置”为本地用户下“chrome.exe”所在的路径。
    图22 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”,提示类似如图23所示错误,处理步骤如下:
    图23 执行结果
    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”命令,打开图形操作界面,创建新应用。
分享:

    相关文档

    相关产品

关闭导读