Skip to content

API

Jump to bottom
TANG edited this page Dec 14, 2016 · 11 revisions

完整 API

1. Module 基础模块实例方法

系统模块基础类，实现所有模块的通用方法

create(name, Class, config) 同步创建子模块实例

  • 参数说明：

     {String}   name   <必选> [子模块名称]
 {Function} Class  <必选> [用于创建子模块实例的类（生成函数），通常是继承于 sugar.Component 的类]
 {Object}   config <可选> [子模块的配置参数]

  • 返回值：创建成功后的子模块实例

  • 用法示例：

     // sugar.Component 为视图组件基础模块的类，继承于 sugar.Module ，用于定义视图组件

 var Page = sugar.Component.extend({
 	// 定义视图组件
 });
 // 或者采用引入方式：var Page = require('/path/to/page');

 sugar.core.create('page', Page, {
 	// 模块配置参数
 });

getParent() 获取当前模块实例的父模块实例（创建者）

  • 参数说明：不需要参数

  • 返回值：父模块实例或 null，null 表示该模块是由 sugar.core 实例创建的顶层模块

  • 用法示例：

     // 定义 header 视图组件
 var Header = sugar.Component.extend({
 	// afterRender 为每个视图组件创建完毕后默认调用的方法
 	afterRender: function () {
 		var parent = this.getParent(); // => Page实例
 	}
 });

 // 定义页面视图组件
 var Page = sugar.Component.extend({
 	afterRender: function () {
 		// 创建头部模块
 		this.create('header', Header, {
 			// 创建header模块的配置参数
 		});

 		var parent = this.getParent(); // => sugar.core实例
 	}
 });

 var main = sugar.core.create('page', Page, {
 	// 模块配置参数
 });
 var parent = main.getParent(); // => null

getChild(name) 获取当前模块实例的指定子模块实例

  • 参数说明：

     {String} name <必选> [子模块的名称]

  • 返回值：子模块实例，不存在则返回null

  • 用法示例：

     // 定义 header 视图组件
 var Header = sugar.Component.extend({/* 定义视图组件…… */});

 // 定义页面视图组件
 var Page = sugar.Component.extend({
 	afterRender: function () {
 		// 创建头部模块
 		this.create('header', Header, {
 			// 创建header模块的配置参数
 		});

 		var head = this.getChild('header'); // => header模块实例
 	}
 });

getChilds(returnArray) 获取当前模块实例的所有子模块实例

  • 参数说明：

     {Boolean} returnArray <可选> [返回的子模块集合是否是数组的形式，否则为映射对象形式]

  • 返回值：子模块集合

  • 用法示例：

     // 定义 header 视图组件
 var Header = sugar.Component.extend({/* …… */});

 // 定义 footer 视图组件
 var Footer = sugar.Component.extend({/* …… */});

 // 定义 sidebar 视图组件
 var Sidebar = sugar.Component.extend({/* …… */});

 // 定义页面模块类
 var Page = sugar.Component.extend({
 	afterRender: function () {
 		// 创建三个子模块
 		this.create('header', Header);
 		this.create('footer', Footer);
 		this.create('sidebar', Sidebar);

 		var chids = this.getChilds();
 		/*  {
 				'header' : Object
 				'footer' : Object
 				'sidebar': Object
 			}
 		 */

 		var chids = this.getChilds(true);
 		// [header, footer, sidebar]
 	}
 });

fire(name, param, callback) 模块通信：冒泡方式发送消息

  • 参数说明：

     {String}   name     <必选> [消息名称]
 {Mix}      param    <可选> [消息参数（内容）]
 {Function} callback <可选> [消息被接受者接收完毕后的回调函数]

  • 返回值：无

  • 用法示例：

     // 定义导航视图组件
 var Nav = sugar.Component.extend({
 	afterRender: function () {
 		// 向父模块发送消息，将会冒泡到每一层父模块
 		this.fire('navCreated', 123);
 	}
 });

 // 定义 Header 视图组件
 var Header = sugar.Component.extend({
 	afterRender: function () {
 		// 创建导航
 		this.create('nav', Nav);
 	},
 	// 默认接收消息方法用on + 消息名首字母大写，以区分其他类型的方法
 	// Header 是 Nav 的父模块，能接收到 navCreated 消息
 	onNavCreated: function (msg) {
 		// ev.param => 123
 		// return false // 假如在这里返回false，则不会将消息冒泡到Header的父模块Page中
 	}
 });

 // 定义 Page 模块
 var Page = sugar.Component.extend({
 	afterRender: function () {
 		// 创建头部模块
 		this.create('header', Header);
 	},
 	// Page 是 Header 的父模块，也能接收到 navCreated 消息
 	onNavCreated: function (msg) {
 		// ev.param => 123
 		// 假如没有任何一层的消息return false，此消息还会将继续冒泡到Page的父模块，直到模块树的根
 	}
 });

 // 以上，消息的传递顺序为子模块->父模块：Nav -> Header -> Page

broadcast(name, param, callback) 模块通信：向下广播方式发送消息

  • 参数说明：

     {String}   name     <必选> [消息名称]
 {Mix}      param    <可选> [消息参数（内容）]
 {Function} callback <可选> [消息被接受者接收完毕后的回调函数]

  • 返回值：无

  • 用法示例：

     // 定义导航视图组件
 var Nav = sugar.Component.extend({
 	// Nav 是 Header 的子模块，能接收到 pageReady 消息
 	onPageReady: function (msg) {
 		// ev.param => 456
 	}
 });

 // 定义 LOGO 视图组件
 var LOGO = sugar.Component.extend({
 	// LOGO 是 Header 的子模块，能接收到 pageReady 消息
 	onPageReady: function (msg) {
 		// ev.param => 456
 	}
 });

 // 定义 Header 子模块
 var Header = sugar.Component.extend({
 	afterRender: function () {
 		// 创建导航
 		this.create('nav', Nav);
 		// 创建 LOGO
 		this.create('logo', LOGO);
 	},
 	// Header 是 Page 的子模块，能接收到 pageReady 消息
 	onPageReady: function (msg) {
 		// ev.param => 456
 		// return false // 假如在这里返回false，则不会将消息继续广播到Header的子模块Nav和LOGO中
 	}
 });

 // 定义 Page 模块
 var Page = sugar.Component.extend({
 	afterRender: function () {
 		// 创建头部模块
 		this.create('header', Header);

 		// 向所有子模块发送广播消息
 		this.broadcast('pageReady', 456);
 	}
 });

 // 以上，消息的传递顺序为父模块->子模块：Page -> Header -> Nav、LOGO

notify(receiver, name, param, callback) 模块通信：向指定的模块发送消息

  • 参数说明：

     {String}   receiver <必选> [接受消息的模块实例名称，有层级时以.分隔并且要求完整层级]
 {String}   name     <必选> [消息名称]
 {Mix}      param    <可选> [消息参数（内容）]
 {Function} callback <可选> [消息被接受者接收完毕后的回调函数]

  • 返回值：无

  • 特殊说明：fire 和 broadcast 方式要求通信的模块之间存在父子关系，而 notify 方式可以用于任何两个模块之间的通信。

  • 用法示例：

     var PageA = sugar.Component.extend({
 	afterRender: function () {
 		this.notify('page_b', 'helloFromA', 'Are you ok?');
 	}
 });

 var PageB = sugar.Component.extend({
 	onHelloFromA: function (msg) {
 		// ev.param => 'Are you ok?'
 	}
 });

 sugar.core.create('page_b', PageB);

destroy(notify) 模块销毁

  • 参数说明：

     {Boolean} notify <可选> [为 true 时，销毁后会向父模块发送 subDestroyed 消息]

  • 返回值：无

  • 特殊说明：模块在 destroy 在之前会调用当前模块的 beforeDestroy 方法，销毁后会调用 afterDestroy 方法

  • 用法示例：

     var Page = sugar.Component.extend({/* …… */});

 var page = sugar.core.create('page', Page);

 page.destroy(); // page => null

2. core 实例方法

core 是由 sugar 中的核心实例（继承于 Module 类，是一个只有组件系统而没有视图的顶级模块实例），拥有 Module 所有的方法，另外自身拓展了两个方法：

get(name) 获取顶层模块实例

  • 参数说明：

     {String} name <必选> [子模块的名称]

  • 返回值：由 sugar.core 创建的顶层模块实例，不存在或已销毁则返回 null

  • 特殊说明：该方法只是实现用 sugar.core.get(name) 来代替 sugar.core.getChild(name) 而已，两者相同

globalCast(name, param) 模块通信：全局广播消息

  • 参数说明：

     {String} name  <必选> [消息名称]
 {Mix}    param <可选> [消息参数（内容）]

  • 返回值：无

  • 用法示例：

     var user = 'Kobe';
 // 全局广播 userLogin，将触发系统模块树中所有的模块实例的 onUserLogin 方法
 sugar.core.globalCast('userLogin', user);

3. Component 视图组件实例方法

Component 类继承于 Module 类，所以 Component 的实例也有基础模块所有的方法。为了完善视图操作和实现自动渲染流程，自身拓展了一些方法和属性

init(config, parent) 视图组件状态/参数初始化

  • 参数说明：

     {Object} config [视图组件生成实例的配置参数，可以覆盖和拓展 Component 类的参数]
 {Object} parent [父模块实例，没特殊需求基本上用不到]

  • 返回值：无

  • 特殊说明：init 方法的作用是定义整个视图组件的初始状态、配置参数、MVVM 视图层初始化的，不建议在 init 方法里面含有任何业务逻辑的代码（虽然可以有）。init 方法会根据配置参数进行视图布局的渲染，在渲染完成后会调用 cbRender 参数指定的方法（默认为 afterRender ），业务逻辑比如事件绑定、数据加载等建议在 afterRender 中处理

  • 用法示例：

     // 这里的 Page 只是定义一个 Page 类（生成函数），这个 Page 类是继承于 Component 类的
 var Page = sugar.Component.extend({
 	init: function (config) {
 		// Super 方法为调用父类方法，
 		// 这里就是调用 sugar.Component.init
 		this.Super('init', config, {
 			target  : document.body, // 模块插入的目标容器
 			class   : 'page-main',
 			tag     : 'div',
 			view    : 'I am page main',
 			cbRender: 'afterRender'
 		});
 	},
 	afterRender: function () {
 		console.log('视图渲染完成，组件可以做后续处理了！');
 	}
 });

 /*
  *	需要注意的是：当调用模块创建方法时才会生成一个 Page 的实例
  *	定义一个 Page 类，可以生成 N 个 Page 的实例
  */
 var page1 = sugar.core.create('page1', Page);
 // page1 的 DOM 呈现为：<div class="page-main">I am page main</div>

 var page2 = sugar.core.create('page2', Page, {
 	class: 'page2-main',
 	tag  : 'p'
 });
 // page2 的 DOM 呈现为：<p class="page2-main">I am page main</p>

 var page3 = sugar.core.create('page3', Page, {
 	view: 'I am page3'
 });
 // page3 的 DOM 呈现为：<div class="page-main">I am page3</div>

 /*
  *	以上 page1、page2 和 page3 都是由 Page 生成的实例
  *  可以通过配置不同参数使实例输出不同的形态和视图
  *	实例之间功能完全相同并且相互独立互不影响
  */

getConfig(name) 获取模块配置

  • 参数说明：

     {String} name <可选> [获取指定的参数配置，不传则返回整个配置对象]

  • 返回值：参数值或参数对象

  • 用法示例：

     var Page = sugar.Component.extend({
 	init: function (config) {
 		this.Super('init', config, {
 			target: document.body
 			class : 'page-main',
 			tag   : 'b',
 			view  : 'I am a page'
 		});
 	},
 	afterRender: function () {
 		var html = this.getConfig('view');
 		// 'I am a page'

 		var cfg = this.getConfig();
 		// { class: 'page-main', tag: 'b', view: 'I am a page' }
 	}
 });

setConfig(name, value) 设置模块配置

  • 参数说明：

     {String} name  <必选> [需要设置的配置参数名]
 {Mix}    value <必选> [设置的值]

  • 返回值：无返回值

  • 用法示例：

     var Page = sugar.Component.extend({
 	init: function (config) {
 		this.Super(init, config, {
 			target: document.body
 			class : 'page-main',
 			tag   : 'b',
 			view  : 'I am a page'
 		});
 	},
 	afterRender: function () {
 		var html = this.getConfig('view'); // 'I am a page'

 		this.setConfig('view', 'I change my mind');

 		html = this.getConfig('view'); // 'I change my mind'
 	}
 });

query(selector) 获取/查找视图组件的DOM元素

  • 参数说明：

     {String} selector <必选> [元素选择器]

  • 返回值：DOMElement

  • 用法示例：

     var Page = sugar.Component.extend({
 	init: function (config) {
 		this.Super('init', config, {
 			target: document.body
 			class : 'page',
 			tag   : 'p',
 			view  : '<div class="header"><div class="nav"></div></div>'
 		});
 		this.Super('init', arguments);
 	},
 	afterRender: function () {
 		var dom = this.el; // <p class="page">……</p>
 		var nav = this.query('.nav'); // <div class="nav"></div>
 	}
 });

queryAll(selector) 获取/查找视图组件的DOM元素

  • 参数说明：

     {String} selector <必选> [元素选择器]

  • 返回值：NodeList

show() 显示整个组件

组件 display 设为 初始显示状态或者空

hide() 隐藏整个组件

组件 display 设为 none

on(elm, event, callback, capture) 为元素添加绑定事件

（参见 addEventListener 方法）

off(elm, event, callback, capture) 从元素上移除事件绑定

（参见 removeEventListener 方法）

4、ajax 实例方法

sugar.ajax.get(uri, param, callback, context) Ajax GET 请求

  • 参数说明：

     {String}   uri      <必选> [请求地址]
 {Object}   param    <可选> [请求参数]
 {Function} callback <必选> [请求回调]
 {Object}   context  <可选> [回调函数执行上下文]

  • 返回值：当前的 xhr 对象

  • 用法示例：

     var Page = sugar.Component.extend({
 	afterRender: function () {
 		var param = {'page': 1, 'limit': 10};
 		sugar.ajax.get('/article/list.php', param, this.dataBack);

 		// 回调也可写成字符串形式：
 		sugar.ajax.get('/article/list.php', param, 'dataBack', this);
 	},
 	dataBack: function (err, data) {
 		// err 为请求错误或者服务器返回信息错误的对象，data 为请求成功的数据
 	}
 });

sugar.ajax.post(uri, param, callback, context) Ajax POST 请求

（参照 get 请求）

sugar.ajax.load(uri, param, callback, context) 加载静态文本文件

  • 参数说明：（参照 get 请求）

  • 返回值：当前的 xhr 对象

  • 用法示例： （参照 get 请求）

5. util 工具库

var util = sugar.util;

参见 https://github.com/tangbc/sugar/blob/master/src/util.js

上一篇：组件间的消息通信

Download sugar.js   |   Download mvvm.js   |   View source code

sugar

组件系统

MVVM 系统

Clone this wiki locally