mtl-cli详细介绍

创建工程

mtl 根据模板脚手架创建一个工程

mtl create [appname]

appname 是工程名称

此参数是必填项。参数不能是特殊字符，长度不要超过64。例如mtl-demo、mtl@……%demo 这样的工程命名都是不对的；
本地已创建的工程不能同名再创建，造成本地目录同名；
如果工程创建成功后，请务必先进入到工程跟目录下，例如 cd “创建的工程名”

命令交互中，选择需要的样版工程:

一个react工程，react工程下又有mtl-react-empty工程模版供用户选择使用。
一个html工程，html工程下又有mtl-empty和mtl-demo两个工程模版供用户选择使用。

注意

一：
如果 mac 在创建工程结束的时候报错“Error: EACCES: permission denied” ，这个可能是 安装 express 没有权限导致 。
解决方法 ：
1）、进入到你创建的**工程目录** 下 ，执行：sudo npm --save install express ，等待安装包执行完成后就可以了。
2）、修改你的workspace 目录操作权限，指令： sudo chmod -R 777 workspace 的文件夹目录。
二：
如果在win上同样出现权限的报错，请查询win修改权限相关的操作。
三：
如果在win上出现“no such file or directory...” ,说明git clone 失败，请查询
git的环境变量是否已经配置好。
四：
如果创建的是react工程 ，在创建完成后 ，进入到工程根目录下，一定要执行npm install  命令 ，下载react 工程需要的依赖包。
五：
MTL创建的react空工程，也是react官方提供的标准空工程，完全继承了react官方提供的属性 ，详细的功能描述可以登录react官方文档学习，
官网地址：https://reactjs.org 。

工程配置文件

project.json文件是工程配置文件，工程的信息以及各个端需要的重要数据都会集中在此文件中。

[用户可以通过命令行更新或者手工配置]

{

    "config": {

        "appName": "ttttt",

        "packageName": "com.yonyou.ttttt",

        "bundleID": "com.yonyou.uap.mobile5",

        "projectName": "ttttt",

        "versionName": "1.0.0",

        "versionCode": "100",

        "versionBuild": "1.0.0",

        "startPage": "welcome/index.html",

        "reinforcement": "false",

        "sandbox": "false",

        "targetDevice": "handset",

        "statusBarTheme": "summer.Animations.NoTitleBar.FullScreen",

        "windowSoftInputMode": "adjustPan",

        "errorUrl": "",

        "urlScheme": "iosMtlScheme",

        "queriesSchemes": "",

        "androidScheme": "",

        "androidMinSdkVersion": "19",

        "isLibraryCompilation": "false",

        "ddAppCode": "dingnlb2wikil7pldytf",

        "wxAppCode": "dingnlb2wikil7pldytf",

        "mtlPlugins": [

            {

                "name": "mtl-plugin-faceverify",

                "type": "cordova",

                "parameters": [

                    "LICENSEID_IOS=renliantest-face-ios",

                    "LICENSEID_ANDROID=mtl-android-face-android",

                    "BASE_URL=http://172.20.14.154:80",

                    "PUB_KEY=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCJwnm0t5GdNp/Q7fEM+jGMoxK/1S0r0KaMF2vsX2cXRRkb7fGo/uXhtbrDqjzvoqF954idr3vRRJ8jIC7BNxbhSoETIpxqr78Yup5rF6HlA8mEOZWavPNQ6Y1zz+uRS7QV2GrMEy2D/Wdrru6TWFVfhiKM2RvavrdncinYCSmxqQIDAQAB"

                ]

            },

            {

                "name": "mtl-plugin-bdlocation",

                "type": "cordova",

                "parameters": [

                    "BDMAP_KEY_ANDROID=hvontoOPpe0YWDgGVrtLHel8mSm6ibhG"

                ]

            },

            {

                "name": "mtl-plugin-terminal",

                "type": "cordova"

            },

            {

                "name": "mtl-plugin-umeng",

                "type": "cordova",

                "parameters": [

                    "WEXIN-APPKEY=wxe1406439b46007d4",

                    "WEXIN-SECRET=2096cf6c6fa5149c20ddd970ea302048",

                    "DING-APPKEY=dingoaokqduou0l8poumhz",

                    "UMENG-APPKEY=5cb5b38e570df31281000824"

                ]

            },

            {

                "name": "mtl-plugin-vui",

                "type": "cordova",

                "parameters": [

                    "APPID=11152975",

                    "APIKEY=AtWb2xKCTZqnCOnYIovoXaqF",

                    "SECRETKEY=iBzBh459NnqViqaLQUvNF88xi2dqj0U1"

                ]

            },

            {

                "name": "mtl-plugin-alinotification",

                "type": "cordova",

                "parameters": [

                    "APPKEY=27849543",

                    "APPSECRET=982cb690e885c242ff1db939143fa97e",

                    "CHANNELID_ANDROID=10011"

                ]

            }

        ],

        "gitUrl": "https://gogs.yonyoucloud.com/caiyi/mtl.git",

        "technologyStack": "tradition",

        "setStatusBar": {

            "showStatusBar": true,

            "isScreenEdge": false,

            "color": "",

            "isStatusBarDefault": true

        },

        "serviceUrl": {

            "uploadUrl": "https://mdoctor.yonyoucloud.com/mtldebugger/mtl/file/uploadToOSS",

            "downloadUrl": "https://mdoctor.yonyoucloud.com/mtldebugger/mtl/stream/download"

        }

    }

}

简单介绍几个重要参数：

appName ：用户应用名称，一般在android ，iOS 构建打包后会生成的包名称。
packageName ： android的包ID 。
bundleID ： iOS 的bundleID 。
projectName ：创建工程的名称，一般与appName同名皆可以。
version**** ：这个设置的android ，iOS 构建包的版本号，对于其他平台版本设置不涉及。
startPage ：这个是工程的首页地址，是很重要的参数！用户创建的工程无论调试、预览、构建都要关注这个参数，因为这是工程的入口。startPage 还关系到纯线上APP或者本地web APP 。如果开发者配置 “http” 开头的url ，则是线上APP ，其他的是本地web APP 。
reinforcement ： android的加固功能，暂时不支持。
****Schemes ： android和iOS的schemes配置。
androidMinSdkVersion ： android支持的最小版本。
ddAppCode ：钉钉小程序创建时钉钉第三方分配的AppKey 。
wxAppCode ：微信小程序创建时微信第三方分配的AppID 。
windowSoftInputMode 值为 adjustPan | adjustResize 。adjustPan时不挤压布局，值为adjustResize时挤压布局，默认为adjustPan
mtlPlugins ：配置调用原生能力的插件列表。
technologyStack ：这个是工程技术栈标识，要支持传统html、react 、以及VUE等等框架。现在支持传统html，以及react。

setStatusBar ：设置状态栏颜色（可为空)，参数如下: (iOS 13 更改状态栏颜色不支持)

  showStatusBar：是否显示状态栏；
  isScreenEdge：是否从屏幕顶端开始，还是从状态栏下面开始；
  color：状态栏背景颜色；
  isStatusBarDefault：状态栏颜色是否是默认颜色(黑色)，否是白色

  1、为空默认值：showStatusBar : YES, isScreenEdge : NO, color: 透明, isStatusBarDefault : YES;
  2、showStatusBar为NO时，隐藏状态栏时 isScreenEdge默认为YES;
  3、color #000000 为16进制值

serviceUrl ：配置上传、下载地址

  uploadUrl：上传地址
  downloadUrl：下载地址

设置android包名

mtl  set-packageName

设置iOS bundleID

mtl  set-bundleID

设置首页

mtl  set-startPage

以上三个设置项都是通过命令行更新project.json 文件。

设置应用图标和启动图

app/css/themes/default/app/android、ios 文件夹下更改android、ios的图标和启动图。遵循android、ios原生配置图标和启动图配置方式。

ios:

图标-icon文件夹

包含Contents.json文件和图片资源

Contents.json 配置图片
{
    "images" : [
        {
            "idiom" : "iphone",             // ipad、ios-marketing
            "size" : "20x20",               //40x40 图标大小
            "filename" : "iphone20@2x.png", //@3x.png  图片名称
            "scale" : "2x"                  // 3x
        },
        {...}
    ],
    "info" : {
        "version" : 1,
        "author" : "xcode"
    }
}

启动图-launch文件夹

包含Contents.json文件和图片资源

Contents.json 配置图片
{
    "images" : [
        {
            "orientation" : "portrait",                 // landscape
            "idiom" : "iphone",                         // ipad
            "extent" : "full-screen", 
            "filename" : "iphone-portrait-736h@3x.png", // 图片名称
            "minimum-system-version" : "8.0",           // 支持系统版本最小值
            "subtype" : "736h",                         // 适配类型
            "scale" : "3x"                              //2x
        },
        {...}
    ],
    "info" : {
        "version" : 1,
        "author" : "xcode"
    }
}

andriod

app.png 应用图标(名称固定)
launch.png 启动图 (名称固定)

创建页面

mtl  add-page [pagename]

pagename

此参数是必填项，pagename 不能是特殊字符和汉字，长度不能超过64个字符；
用户根据这个名称，替换模板页面中的模板变量，进行填槽，形成想要的页面。
如果提示The current path is not MTL-Project，需要cd [appname]工程目录下，执行mtl add-page [pagename]即可。

命令交互中，选择需要的页面模板

empty:标准空页面 <--默认
list:标准列表页面
login:标准登录页面

添加插件引用原生功能

mtl  add-plugin

现在拥有的插件，持续开发中：

mtl-plugin-faceverify 人脸识别插件说明
mtl-plugin-bdlocation 定位插件说明
mtl-plugin-terminal 多端控制插件说明
mtl-plugin-umeng 三方友盟插件说明
mtl-plugin-vui 语音交互插件说明
mtl-plugin-alinotification 阿里推送（备注不能同时启用两个推送）插件说明

用户进入查看列表。
“回车” 确认保存到project.json 文件中

调试

mtl debug [ iOS | Android | WX | DD]

android 调试

android 平台需要配置好 android开发环境，至少adb工具。安装android 模拟器，例如网易模拟器 nunu ，确保adb 连接通，可以使用命令：adb connect 127.0.0.1:7555 （win），adb connect 127.0.0.1:5555 （mac）。如果debug过一次了没有成功，可以把工程根目录下的output/android/debug 目录删除，重新执行命令行debug 。如果报错 error: more than one device and emulator ，可以用adb devices 命令看看是不是存在多个。发现还真是多个设备，那就需要为ADB命令指定设备的序列号了， adb -s “emulator-5554” shell 也就是给命令加上-s的参数就可以了；

iOS 调试

iOS 需要搭建好xcode 开发环境；

微信小程序调试

微信小程序需要安装微信小程序工具：到微信公众平台去下载，下载地址：https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html。命令行进行mtl debug wx 后，用微信小程序工具导入当前工程目录./output/wx/debug/proj ，这样就可以在微信小程序工具下看到修改app目录下工程源码的调试效果。

钉钉小程序调试

钉钉小程序需要安装蚂蚁金服开放平台小程序工具，下载地址：https://docs.alipay.com/mini/ide/download。命令行进行mtl debug DD 后，用钉钉小程序工具导入当前工程目录./output/dd/debug/proj ，这样就可以在钉钉小程序工具下看到修改app目录下工程源码的调试效果。

debug 调试host配置和功能说明：

(仅调试微信需要)配置pc的host 文件如下：添加“ 127.0.0.1 mobile.yyuap.com ” ；
修改文件热更新，如果在项目工程下，修改了app目录下的工程源码都会自动更新到output平台目录下的工程目录，需要在 android ，iOS ，wx小程序工具，钉钉小程序工具里刷新就可以看到修改的效果。
友情提示，终端命令行在调试状态下，一直处于工程的监听中，请不要中断当前的状态，直到想要终止调试，进行其他操作。

预览

mtl preview [ iOS | Android | WX | DD |Upesn]

android预览说明：

命令行执行预览android功能，需要用真机预先安装"预览apk" ，在真机安装后，打开预览APP的扫码功能，扫码识别后，就可以验证项目开发的真机预览功能。

iOS 预览说明：

命令行执行预览iOS功能，需要用真机预先安装"预览IPA" ，在真机安装后，打开预览APP的扫码功能，扫码识别后，就可以验证项目开发的真机预览功能。

微信小程序预览说明：

命令行执行预览微信小程序功能，需要用真机的微信APP，用微信的扫码功能，扫码识别后，就可以验证项目开发的真机预览功能。

友空间预览说明：

命令行执行预览Upesn功能，需要用真机的友空间APP，用友空间的扫码功能，扫码识别后，就可以验证项目开发功能的真机预览功能。

预览功能说明：

预览命令行执行后，会在pc开发设备形成二维码；
修改文件热更新，如果在项目工程下，修改了app目录下的工程源码都会自动更新到后台预览服务中，需要在 android ，iOS ，微信，钉钉，友空间里刷新就可以看到更新的效果。
友情提示，终端命令行在预览状态下，一直处于工程的监听中，请不要中断当前的状态，直到想要终止预览，进行其他操作。

构建

后续构建功能文档由友空间提供。

FAQ

一、mtl-cli不能安装？

答：
 权限不够导致， 请配置相应权限。

二、mtl-cli创建工程不成功？

答：
 如果 mac 在创建工程结束的时候报错“Error: EACCES: permission denied” ，这个可能是 安装 express 没有权限导致 。
解决方法 ：
1）、进入到你创建的**工程目录** 下 ，给当前用户权限。

2）、如果在win上同样出现权限的报错，请查询win修改权限相关的操作。
3）、如果在win系统上，出现工程无法下载，git 命令不识别 ，需要检查一下git 是否安装成功 ，mtl命令行工具是依赖git工具的 。如果git已经安装了 ，
请检查一下 命令的环境变量是否全局，在当前workspace目录下是否能够执行git 指令。也可以用另一种方法 ，在workspace目录下右击鼠标，
选择git bash here 命令，打开命令终端 ，然后在命令终端中执行创建工程的操作。

三、为什么启动页不能替换？

答：
 1、对修改project.json文件的startPage项没有保存成功。
 2、修改的目录以及文件名称与实际工程的目录和文件名称不一致。

四、Cannot find module 'express'

答：
 1、有时候新建工程首次调试会报以上提示错误，是因为express包没装上。
 2、可以通过手动输入 npm install express，安装express再次调试即可。

创建工程
工程配置文件
设置应用图标和启动图
创建页面
添加插件引用原生功能
调试
预览
构建
运行
git账号配置
设置环境变量
FAQ