Weex Eros快速入门

概述

随着Weex跨平台技术的持续火热,一时间涌现出了一大批基于Weex的开源解决方案,Weex Eros就是这么一个面向前端Vue的开源APP解决方案。
目前,如果直接使用Weex框架开发应用会存在很多痛点,诸如初始化启动的环境问题、项目工程化问题、版本升级与版本兼容问题和不支持增量更新等,而Weex Eros等开源解决方案能对上述问题进行有效的解决。
Weex Eros的定位不是组件库,而是基于Weex封装的面向前端Vue的一整套APP开源解决方案,它关心的是整个APP项目。在Weex的强大支持下,用一份Vue代码即可编译出iOS、Android两端原生的app,并且通过Weex Eros内置的热更新逻辑和开源的服务器逻辑,开发的APP还具有热更新能力。

快速入门

工欲善其事,必先利其器。使用Weex Eros开发移动应用需要具备以下软件环境。

  • Android 4.1 (API 16)
  • iOS 8.0+
  • WebKit 534.30+

环境搭建

除了安装一些必须的软件(如Node、Git等)之外,Weex Eros还依赖于脚手架eros-cli。全局安装命令如下:

npm i eros-cli -g

如果是在国内,还可以使用cnpm进行安装,或者直接修改下载的镜像地址,例如淘宝的镜像源。

cnpm i eros-cli -g        
//或者使用淘宝镜像安装
npm i -g cnpm --registry=https://registry.npm.taobao.org

同时,为了方便对Weex Eros程序进行断点调试,建议开发者安装Weex官方提供的脚手架命令行工具weex-toolkit。

cnpm i -g weex-toolkit

除此之外,为了能够正常的运行Android、iOS应用程序,因此还需要安装原生Android和iOS相关的运行环境。特别的,对于iOS来说,还需要安装诸如ruby、rubygems和cocoapods等工具软件。

工程创建

和使用weex cli创建工程类似,借助eros-cli脚手架工具可以很方便的创建Weex工程。例如:

eros init <工程名> <版本号> <模板> 

使用eros init方式创建工程时,init后面依次跟的是项目名称、版本号、模板类型和安卓包名,除了项目名称外,其他都不是必须的。需要说明的是,同一个Android手机上不能出现2个包名相同的应用,所以命名时请注意区分。

Weex Eros快速入门_第1张图片
然后进入工程目录,执行cnpm i安装node_modules依赖包,等待依赖包安装完成,打开模板工程目录结构。

├── config                  
│   ├── eros.dev.js            //脚手架相关配置
│   └── eros.native.js         //客户端相关配置
├── dist                    //静态资源生成目录
├── node_modules          //依赖
├── scripts                 //自动化脚本
├── platforms              //平台基础代码
│   ├── android
│   └── ios
├── src                     //开发路径
│    ├── assets             //静态资源路径 一般存放图片
│    ├── iconfont           //静态资源路径 一般存放 iconfont
│    ├── js                 // js bundle 开发路径
│    └── mock               //本地请求 mock 地址
├── CHANGELOG.md          //版本升级变动
└── package.json             //npm项目及依赖说明

运行项目

使用eros init方式创建的项目,模板会默认生成Android、iOS原生工程结构。启动客户端之前,需要先使用eros dev指令启动服务端服务,启动过程中如出现任何的报错,请先按照错误提示解决报错问题。
运行iOS项目前,需要cd到iOS工程目录的platforms/ios/WeexEros中执行pod update命令来拉取iOS工程的依赖包。

pod update

命令执行完毕后,使用Xcode打开工程目录下WeexEros.xcworkspace文件即可打开iOS工程。

Weex Eros快速入门_第2张图片

需要说明的是,最新版本的Xcode在导入iOS工程时会报错,如library not found for -lstdc++.6.0.9,请根据实际情况解决这些错误。然后,在Xcode中选择相应的模拟器,点击运行按钮即可启动iOS工程,运行效果如图8-4所示。
对于Android环境来说,使用Android Studio依次选择【File】→【New】→【Import Project】,找到eros工程目录,然后依次选择【platforms】→【android】→【WeexFrameworkWrapper】,点击【ok】按钮即可导入Android工程,如图8-3所示。

Weex Eros快速入门_第3张图片

接下来,打开WeexFrameworkWrapper工程并执行工程下的install.sh脚步来安装Android工程所需要的依赖包nexus和wxframework。待Android工程构建完成,点击Android Studio工具栏上的【Run】按钮即可运行项目,运行效果如图8-4所示。

Weex Eros快速入门_第4张图片
本地开发的时候,可以运行脚手架eros dev指令来启动本地服务,脚手架eros-cli会通过读取配置文件在特定端口启动服务,而客户端访问的就是工程目录下dist文件通过webpack打包生成的JS Bundle文件。
而生产环境客户端运行的版本一般都会内置一个JS Bundle文件,这样即使断网也不会出现页面空白的情况,而是读取本地内置包的内置数据。
Weex eros内置了拦截器开关,拦截器的主要作用就是控制加载js文件的方式。当拦截器处于打开状态时,会从当前工程内置的资源中加载js资源文件,否则从开发服务器上加载js资源文件。可以通过Interceptor开关来配置访问的是服务器开发包还是内置包,如图8-5所示。

Weex Eros快速入门_第5张图片

Hello eros

新建一个Eros项目时,系统默认是开启Interceptor拦截器的,如果关闭调试中的拦截器,再让app访问服务包将会出现白屏。为了更好的理解Eros的加载流程,下面通过一个Hello Eros实例来说明。
首先,关闭调试拦截器,然后使用WebStrom打开Eros工程,并在pages目录下新建一个Hello.vue文件。




修改eros.dev.js配置文件中的exports,如果不需要可以把eros-demo中对应的路径都删掉,只配置需要的文件入口。

"exports": [
    "js/config/index.js",
    "js/mediator/index.vue",
    "js/pages/Hello.vue"        //导出Hello.vue
],

需要注意的是,eros.dev.js文件中的appBoard、mediator和eros.native.js是一一对应的,如果两边修改没有对应上会导致报错,建议不要随便变动。
要改变eros工程的首页,需要修改eros.native.js文件中的page.homePage路径。

"page": {
    "homePage": "/pages/Hello.js",
}

断开eros dev服务并重启服务,然后重新运行app即可看到示例效果,如图8-6所示。

Weex Eros快速入门_第6张图片

很多时候,app会默认使用本地内置的JS bundle而不是从服务端下载。为了将编写好的代码打包成JS bundle,需要使用eros pack指令。

eros pack

eros pack打包指令提供了eros pack ios、eros pack android、eros pack all三个指令来为不同的平台进行打包操作,如图8-7所示。

Weex Eros快速入门_第7张图片

然后,将打好的JS bundle包内置到Android的assets或iOS的工程目录下即可。然后,关闭调试拦截器,本地运行的即是内置的bundle包。

工程配置

在eros项目中,整个项目只有两个配置文件,都放在项目的config文件夹下,分别是eros.native.js和eros.dev.js。其中,eros.native.js表示客户端需要读取的配置信息,eros.dev.js表示开发环境需要读取的配置信息,该配置文件主要用来配置开发、调试、语法检测、mock、生成增量包和全量包等功能。
eros.native.js文件表示客户端需要读取的配置信息,eros.native.js文件的每次变动,都需要重新执行命令eros dev并重新运行app。例如:

{
    appName: "eros-demo",                  //工程名称
    appBoard: "/config/index.js",
    androidIsListenHomeBack: "true",          //监听Android物理返回键
    customBundleUpdate: 'true',              //配置更新jsbundle逻辑
    version: {
        android: "1.0.0",                    //Android版本号
        iOS: "1.0.0"                        //iOS版本号
    },
    page: {
        homePage: "/pages/eros-demos/index.js",     //主页地址
        mediatorPage: "/mediator/index.js",          //中介页面地址
        navBarColor: "#3385ff",
        navItemColor:"#ffffff"
    },
    url: {
        image: "https://app.weex-eros.com/xxx/xxx",       //图片上传路径
        bundleUpdate: "http://localhosts:3001/app/check"  //jsBundle更新接口
    },
    zipFolder: {
        server: "home/app",                         //增量发布差分包地址
        iOS: "/ios/WeexEros/WeexEros",               //iOS本地包地址
        android: "/android/WeexFrameworkWrapper/app/src/main/assets"
    },
    getui: {
        enabled: "false",                      //是否开启个推服务
        appId: "",
        appKey: "",
        appSecret: ""
    },
    tabBar: {
        color: '#777777',
        selectedColor: '#00b4cb',
        backgroundColor: '#fafafa',
        borderColor: '#dfe1eb',
        list: [{
                pagePath: '/pages/demo/router/tabbarItem1.js',
                text: '首页',
                icon: 'bmlocal://assets/[email protected]',
                selectedIcon: 'bmlocal://assets/[email protected]',
                navShow: 'true',
                navTitle: "首页"
            },
           //省略其他配置
        ]
    }
}

如上,是一个典型的eros.native.js文件的配置信息,具体说明如下:

  • appName:表示脚手架自动生成app的名称。
  • version:表示脚手架自动生成的工程版本号,包含iOS和Android两个子版本号,可用于增量发布时的版本判断。
  • androidIsListenHomeBac:用于配置Android平台是否需要监听首页的物理返回键。
  • customBundleUpdate: 用于配置是否自定义更新jsbundle逻辑,默认为true,即不使用更新逻辑。
  • page:用于配置与页面相关的内容,包含navBarColor、navBarColor、mediatorPage和navItemColor等子配置项。其中,homePage表示主页js的相对地址,mediatorPage表示中介者页面的相对地址。
  • url:配置与路径相关的内容,包含jsServer、image和bundleUpdate等子配置项。其中,jsServer用于配置本地js服务路径,image用于配置图片上传的绝对路径,bundleUpdate用于配置jsBundle更新接口。
  • zipFolder:用于配置内置包的存放地址,包含server、iOS和android等子配置项。其中,server表示部署在服务器上做增量发布的差分包地址,iOS表示iOS平台内置包地址,android表示Android平台内置包地址。
  • getui:基于个推的推送服务实现配置,包含enabled、appId、appKey和appSecret子配置项。

除了上面的配置外,eros.native.js文件还有一个比较重要的配置tabBar,此配置选项用于配置原生tabBar的相关内容。如果您的app被设计成多tab的样式,那么tabBar配置将变得非常有用。
同eros.native.js配置文件一样,eros项目的另一个配置文件eros.dev.js也非常重要,此配置文件主要用来让开发者在开发环境,对开发、调试、语法检测、mock、生成增量包和全量包等进行配置。例如:

{
    exports: [                               //暴露的js页面文件
        "js/service/bus.js",
        "js/pages/home/index.js",
        "js/pages/demo/index.js",
        "js/pages/home/tab1/index.js",
        "js/pages/home/tab2/index.js",
    ],
    alias: {                               //文件别名
        "Components": "js/components",
        "Common": "js/common",
        "Config": "js/config",
        "Widget": "js/widget",
        "Pages": "js/pages",
        "Utils": "js/utils"
    },
    eslint: false,                         // eslint检查配置
    server: {                            //服务的路径和端口配置
        "path": "./", 
        "port": 8889 
    },
    diff: {
        "pwd": "/Users/yangmingzhe/Work/opensource/eros-diff-folder",
        "proxy": "https://app.weex-eros.com/source"
    },
    proxy: [{                          //代理配置
        "route": "/test", 
        "target": "127.0.0.1:52077/test" 
    }],
    mockServer: { 
        "port": 52077, 
        "mockDir": "./dist/mock" 
    },
    socketServer: {
        "switch": true,
        "port": 8890
    }
}

如上,是一个典型的eros.native.js文件的配置信息,具体说明如下:

  • exports:暴露出的页面对应的js地址,app中的每个页面本质上都对应一个js文件。
  • alias:文件夹别名,用于更方便快速的访问。
  • eslint:项目编译时是否需要进行eslint检查。
  • server:运行eros dev服务的路径和端口配置,使用默认即可。
  • proxy:代理相关的配置,使用默认即可,此配置会把/test路径对应的请求代理到127.0.0.1:52077/test。
  • mockServer:本地mock数据服务。
  • socketServer:用于配置热更新服务开关和端口。

开发调试

在根目录运行eros dev指令时,脚手架会在工程的根目录下生成dist文件用于存放JS Bundle。
对于本地开发环境来说,eros是默认开启调试功能的。如果要关闭debug功能,可以依次点击【Debug】→【Setting】→【Interceptor】来关闭拦截器,然后点击【Refresh】按钮或者双击屏幕上【Debug】按钮刷新页面,此时就会重新从服务器加载最新的 js文件。
同时,eros还支持热刷新功能,即修改代码保存(快捷键command + s)时页面会自动刷新,可以通过Setting面板的HotRefresh开关按钮来打开热刷新,如图8-8所示。同时,热刷新只有在eros dev服务已经启动,拦截器关闭的情况下才会生效。

Weex Eros快速入门_第8张图片

如果要在真机上进行断点调试,需要重复上面的调试步骤。然后执行命令weex debug,执行完毕后系统会自动唤起Chrome浏览器打开调试主页,并展示出调试的二维码。
在App中点击调试按钮在弹出框中点击调试选项,并使用脚手架工具提供的扫一扫功能扫描调试的二维码,然后选择Debugger即可开始断点调试。

未完待续!!!

附:weex-eros示例

weex-eros入门

你可能感兴趣的:(Weex Eros快速入门)