一文带你快速掌握如何读懂 YonBuilder移动开发的项目源码

本文将通过四大步的简单讲述，让新手开发者朋友们快速掌握阅读YonBuilder移动开发项目源码的技巧方法。

1.读懂代码的第一步，了解项目的整体文件结构

在这里插入图片描述

CSS: 存放css样式的文件；
feature：猜测是用来存放特征文件的，实际开发中没看到真实使用案例，通常不需要，删除即可。
html：核心文件夹，存放项目各个页面对应的html文件
icon：存放项目的icon图标，仅对本地测试包有效，可删除
image：图片资源文件夹
launch：存放项目的启动图图片资源，仅对本地测试包有效，可删除
res：存放非图片资源的文件夹
script：存放通用的js文件，包括一些封装有通用逻辑的js文件，或引用的第三方js框架文件等
wgt：用来存放widget子包，根据项目实际需要使用，一般不用，可删除
config.xml: 项目的配置文件, 存放关于项目配置的相关信息数据，如入口文件，appid等
index.html: 默认的整个app项目的入口文件，当app启动后，会首先读取运行该文件。（可以在config.xml中重新修改设置程序的入口文件）

PS: 上面的截图是通常在创建一个新的项目时，系统会自动帮你创建好的项目文件结构，对于一个新的项目，处于简化项目代码的需要，建议可将其中的feature、icon、launch 、wgt 均可删除掉，不影响正常的代码逻辑。

上面介绍的这些，属于一个项目的核心文件机构，有兴趣的小伙伴，可点击Widget包结构说明了解更多

2.读懂代码的第二步，找到程序的入口文件

通常一个项目的入口文件是根目录下的index.html文件，这个文件是创建应用时，系统默认的。但是这个入口配置是可以在config.xml中修改的，所以如果我们要查看一个项目，首先需要打开应用根目录下的 config.xml 文件，查看一下这个项目的入口文件位置。

在YonStudio开发工具下，config.xml被可视化了，它的入门文件位置见下截图

在这里插入图片描述

我们也可以点击上面截图中导航条右侧的源文件文字，去查看真正的config.xml页面源码

在这里插入图片描述

PS: 当我们再github或者gitee等开源仓库下载一个YonBuilder移动开发项目代码时，如果我们想要运行体验一下代码，那么就需要在config.xml中，将appid的值，修改成我们账户下自己的一个应用项目的appid才行，因为通常我们只能运行和调式自己账户下的应用。特别是如果一些项目引用了一些移动插件，那么我们就需要在云端控制台自己的项目中，同步添加这些移动插件才OK，否则运行就会报错。

有兴趣的小伙伴，可点击config.xml的配置说明在线文档了解更多

3.读懂代码的第三步，了解 HTML文件的编码结构

3.1 html文件编码结构简述

使用YonBuilder移动开发技术，开发出的App项目，其每一个用户可见的页面，必定由一个（=1）win窗口和若干个(≥0)frame窗口组合而成，每一个win或者frame窗口组件，都对应着一个唯一的html页面，所以读懂html文件，是掌握YonBuilder移动开发技术的关键。

一个完整的html文件的基本结构描述如下：


<html>
	<!--head主要包含页面的meta元数据描述-->
	<head>
		<!--页面的meta元数据描述-->
		<meta></meta>
		<!--页面的标题，在移动端没有意义-->
		<title><title>
		<!--页面的资源引用，主要用于引用第三方的css样式文件（支持本地和远程）-->
		<link><link>
		<!--页面内dom引用的class样式-->
		<style><style>
	<head>
	<!--页面的主要结构部分，存放页面结构与内容的dom标签-->
	<body></body>
	<!--主要存放页面的逻辑代码，也可以通过src属性来引用本地或远程的第三方js框架文件-->
	<script>
		<!--非常重要：整个html的入口函数，html页面在被加载完成之后，引擎就会自动调用该函数执行-->
		apiready = function () {
			<!--整个页面的入口运行函数，核心！重要！-->
		}
	</script>
</html>

由上面我们可以看出，在App开发中使用的html结构与web端开发使用的html结构没有什么不同，其结构是保持一致的，这一特性会更方面擅长Web开发的同学迅速上手YonBuilder移动开发。唯一不同的一点是YonBuilder移动开发特有的apiready函数，下面我们就重点介绍一下这个函数。

3.2 apiready函数

apiready是一个生命周期事件函数，它是单个html文件的入口自运行函数，其特性有点类似window.onload事件，它的运行时机是当引擎加载完成html页面，并在页面内的window对象下挂载api对象成功后，进行调用运行。

整个html加载的运行机制，见下图

在这里插入图片描述

这一运行机制会使得开发者更方便的去阅读相关的项目源码，理解整个页面的编程思路和代码逻辑。
同时，这里也说明一下，apiready函数的重要性，即为什么要特别设计出这一一个函数。

引入apiready函数的最根本原因就是在进行YonBuilder移动开发的时候，我们会根据业务逻辑的需要，频繁的使用到大量的引擎内置的api对象函数方法。

在这里插入图片描述

这些api对象方法是YonBuilder移动开发引擎环境所特有的，在原本的浏览器环境中并不存在，所以需要引擎在加载html页面时，去动态注入api对象后，在相关的程序方法中才可以正常调用，否则就会报错。而apiready函数就是一个显性的生命周期事件，是引擎用来告诉程序，现在api对象已经加载完毕，可以正常调用了。

综上所述，新手开发者朋友们，在你编写项目代码时，如果程序使用了相关的api函数，那么一定要保证这个程序方法是在apiready生命周期事件后再被调用执行，一定不能在apiready函数执行前就运行，否则程序就会异常报错。如果定义的函数体内没有使用到相关的api对象，就不受这个限制。

4.读懂代码的第四步，了解「移动插件」这个特殊存在

在一些项目代码中，我们会看到很多语句编码中使用到了 api.require 这个函数对象，例如

var bMap = api.require('bMap');

这种require对象的方法，就是YonBuilder移动开发在项目代码中引用原生的移动插件的一种调用方法。通过 api.require函数，可以初始化一个移动插件的实例对象，后面就可以通过这个实例对象来调用该移动插件内部已经封装好的api方法，从而快速实现需要的编码功能。

关于「移动插件」，简单来说是YonBuilder移动开发的一种扩展机制，在移动端进行代码开发，有时候我们会遇到一些特殊场景是不适合使用HTML方式去实现的，例如

场景下需要实现的一些功能是移动平台所特有的，原生的HTML环境不具备或者无法实现，比如调用手机相机、通讯录、定位、闹铃、消息通知等；
场景下一些功能比较耗费性能，虽然可以使用原生HTML去实现，但实现后运行的性能和体验不够理想，比如上千条的列表数据（如5000人的通讯录列表），使用html+js方式去实现，滑动页面列表时，就会出现页面的卡顿问题；
场景需要使用一些第三方平台的功能，即需要调用第三方平台移动端封装好的SDK，比如百度（高德）地图的SDK、人脸识别、直播、客服等等功能，他们这些平台封装的都是android或者iOS的原生SDK安装包，在HTML的web环境无法直接调用；

鉴于以上的场景需要，YonBuilder移动开发在引擎层提供了一种机制，就是可以使用引擎提供的一套特定的框架方法，可以将使用android或者iOS原生语言开发的SDK进行封装，封装后的程序可以直接被JavaScript进行调用使用。这个封装好的程序包，就被叫做「移动插件」，或「移动原生插件」。

移动插件需要在云端的应用程序控制台去进行添加，通过「移动打包」进行编译，才可以在具体的项目代码中进行调用。所以我们在遇到使用api.require调用移动插件时，如果想了解具体的插件api功能，就可以访问网站去查看对应的移动插件开发文档，里面有详细的介绍。具体的插件名称就是require括号内的名称，如上面的api.require('bMap'), 其中的单引号包含的 bMap就是具体的插件名称。

未登录情况下在「资源市场」下查看移动插件

在这里插入图片描述