Documentation for dist/ai.js

HTMLElement.Events

HTMLElement.prototype

Public

Utils

_HTMLElement.Events

Methods

Properties

“HTMLElement.Events” Methods

dataChange()

# Ⓢ

事件 : 标签数据(data)变更触发

Returns

  • value ( any ): 属性新值
  • [oldValue] ( any ): 属性旧值

Example

// HTML:
<hello-world id="hello-world" text="hello"></hello-world>

// JS:
var helloWorld = document.getElementById('hello-world');

// 注册事件方法:
helloWorld.on('dataChange',function(ev,changes){
    console.log(changes);
});

// 改变 "hello-text" 属性:
helloWorld['hello-text'] = 'world';

// 输出结果为:
{
    'hello-text' : {
        mode: "change",
        value: "world", 
        oldValue: "hello"
    }
}

find()

# Ⓢ

事件 : 元素被第一次找到时候触发
(生命周期处于init事件前，但是已经合并完成默认数据、准备好了非依赖数据、以及注册好元素基本的Setter/Getter)

Returns

  • . ( object ): 事件返回对象集合
  • .dom ( dom ): 自定义标签dom

Example

var helloWorld = document.getElementById('hello-world');

// 注册事件方法:
helloWorld.on('find',function(){
    helloWorld['require'] = 'world';
});

// helloWorld.require 返回 world

init()

# Ⓢ

事件 : 初始化完成触发

Returns

  • dom ( dom ): dom

Example

// HTML:
<hello-world id="hello-world" text="hello"></hello-world>

// JS:
var helloWorld = document.getElementById('hello-world');

// 注册事件方法:
helloWorld.on('init',function(ev,args){
    console.log(args);
});

remove()

# Ⓢ

事件 : 标签被移除前触发
（同时清理此DOM的attributesChange、styleReady事件）

Returns

  • . ( object ): 事件返回对象集合
  • .dom ( dom ): 自定义标签dom
  • .o ( object ): 自定义标签实例

Example

var helloWorld = document.getElementById('hello-world');

// 注册事件方法:
helloWorld.on('remove', function (e,o) {
    // 移除时候触发
    console.log('[侦测到标签被移除]', o.dom.tagName, o.dom.attributes);
});

show()

# Ⓢ

事件 : 标签显示时触发
（配合styleReady使用可参照showStyleReady语法糖）

Returns

  • dom ( dom ): dom

Example

// HTML:
<hello-world></hello-world>

// JS:
var helloWorld = document.getElementById('hello-world');

// 注册事件方法:
helloWorld.on('show',function(ev,args){
    console.log(args);
});

styleReady

# Ⓢ

事件 : 标签样式加载完成触发
（配合styleReady使用可参照showStyleReady语法糖）

Example

// 需要在自定义标签控件CSS中加入以下片段用于触发，通常直接使用 `showStyleReady` 组合函数来控制显示及得到回调:
// tag-name[style-ready-trigger]{animation-duration:1ms;-webkit-animation-duration:1ms;animation-name:style-ready-trigger;-webkit-animation-name:style-ready-trigger;}
// (之所以要加入style-ready-trigger属性是因为不能够直接复写标签的动画标识，否则_tiggerTagInsert会因为样式动画名称被改写而失效。)

var helloWorld = document.getElementById('hello-world');

// 注册事件方法:
helloWorld.on('styleReady', function () {
    // 样式加载完成后触发
});

“HTMLElement.prototype” Methods

addEventListener(event, listener, capture)

# Ⓢ

为原生DOM元素扩展绑定事件方法
为了兼容主流框架写法，listener 回调函数额外开放第二个参数为回传参数

Aliases

on

Arguments

  • event ( string ): 事件名称
  • listener ( function ): 监听函数
  • capture ( boolean ): 事件捕捉模式

Example

dom.addEventListener('init',function(e,args){
    console.info(e,args);
});

// 正常的获取trigger的回调参数推荐使用e.detail，如果需要使zepto等框架的on方法可以通过第二个参数正常获取回调参数，则可参考如下代码做兼容：
handler.proxy = function(e){
  e = compatible(e)
  if (e.isImmediatePropagationStopped()) return
  e.data = data

  // >> event.detail / e.detail compatibly
  if(e._args == undefined && e.detail != undefined){
    e._args = e.detail;
  }
  // << event.detail / e.detail compatibly

  var result = callback.apply(element, e._args == undefined ? [e] : [e].concat(e._args))
  if (result === false) e.preventDefault(), e.stopPropagation()
  return result
}

default(defines)

# Ⓢ

在DOM上定义默认数据，不具有覆写权限

Arguments

  • defines ( object ): 属性键值对

Example

<xxx id="test" foo="0"></xxx>

// 定义默认数据
var data = document.getElementById('target').default({
    foo:1,
    bar:2
});

// 输出结果为
data : { foo : 0, bar : 2 }

gets(keys)

# Ⓢ

在DOM上批量获取数据

Arguments

  • keys ( string/array ): 数据名

Example

<xxx id="test" foo="1" bar="2"></xxx>

// 单个获取
var data = document.getElementById('target').gets('foo');

// 输出结果为
data : { foo : '1' }

// 强制定义模式
var data = document.getElementById('target').gets(['foo','bar']);

// 输出结果为
data : { foo : '1', bar : '2' }

observer(name, callback)

# Ⓢ

扩展DOM侦测指定数据方法

Arguments

  • name ( string ): 数据名
  • callback ( function ): 侦测回调

Example

<xxx id="test" foo="1" bar="2"></xxx>

var target = document.getElementById('target');
target.observer('foo',function(change){
    console.log(change);
});

target['foo'] = 2;

register(aiTags)

# Ⓢ

在某个元素中注册AI标签(如document.body)

Arguments

  • aiTags ( object ): 标签映射存储对象

Returns

  • return ( dom ): 当前操作注册的元素

Example

var scope1 = document.getElementById('scope-1');
scope1.register({
    'hello-world': {
        js: 'examples/tags/hello-world.js'
    }
});

var scope2 = document.getElementById('scope-2').register({
    'hello-world': {
        js: 'examples/tags/in-hello-world.js'
    }
});

removeEventListener

# Ⓢ

为原生DOM元素扩展移除绑定事件方法

Aliases

off

Example

dom.removeEventListener('init',function(e){
    console.info(e);
});

sets(defines)

# Ⓢ

在DOM上批量定义数据，具有覆写权限

Arguments

  • defines ( object ): 属性键值对

Example

<xxx id="test" foo="0"></xxx>

// 批量定义
var data = document.getElementById('target').sets({
    foo:1,
    bar:2
});

// 输出结果为
data : { foo : 1, bar : 2 }

show

# Ⓢ

为原生DOM元素扩展显示方法

Example

dom.show();
// 或者
dom.show(function(){
   console.info('显示出来了');
});

showStyleReady

# Ⓢ

为原生DOM元素扩展等待样式通知的显示方法

Example

dom.showStyleReady();

// 或者
dom.showStyleReady(function(){
   console.info('样式告诉我准备OK了，我能显示出来了');
});

trigger

# Ⓢ

为原生DOM元素扩展触发事件方法

Example

dom.trigger('init',{
    data : {
        text : 'hello'
    }
});

unRegister(aiTags)

# Ⓢ

在某个元素中注销AI标签(如document.body)

Arguments

  • aiTags ( string/array ): 标签名

Returns

  • return ( object ): 最新的标签映射表

Example

document.body.unRegister('hello-world');
document.body.unRegister(['hello-world','world-hello']);

“Public” Methods

radio(name, data)

# Ⓢ

广播获取到的数据

Arguments

  • name ( String ): 数据名称
  • data ( Json|String|Boolean|Array ): 数据对象

Example

HTML:
<hello-world require-data="::flag-value">...wait init...</hello-world>

JS:
require(['ai'], function (AI) {
    AI.radio('::flag-value', {
        data : {
            foo : 'bar'
        }
    });
});

register(aiTags)

# Ⓢ

(在document.body内部)注册AI标签

Arguments

  • aiTags ( object ): 标签映射对象

Returns

  • return ( object ): 返回的映射容器内容

Example

require(['ai'], function (AI) {
    AI.register({
        'hello-world': {
            js: './tags/hello-world.js'
        }
    }); 
});

unRegister(aiTags)

# Ⓢ

(在document.body内部)注销AI标签

Arguments

  • aiTags ( string/array ): 标签名

Returns

  • return ( object ): 最新的标签映射表

Example

require(['ai'], function (AI) {
    AI.unRegister('hello-world');
});

“Utils” Methods

_trueFalseToBoolean(obj)

# Ⓢ

True / False 转换为布尔 (仅限第一层，帮助属性值转换)

Arguments

  • obj ( string|boolean ): 转换目标

Returns

  • return ( boolean ): 返回布尔值

“_HTMLElement.Events” Methods

attributesChange()

# Ⓢ

事件 : 标签属性变更触发
(此为私有事件，不建议监听，请使用change)

Returns

  • . ( object ): 事件返回对象集合
  • .attributeName ( object ): 以标签属性名为Key的对象
  • .attributeName.mode ( string ): 属性变更类型 : 'add'|'change'|'delete'|'radio' (增加|改变|删除|radio数据)
  • [.attributeName.oldValue] ( string ): 属性旧值
  • [.attributeName.newValue] ( string ): 属性新值

Example

var helloWorld = document.getElementById('hello-world');

// 注册事件方法:
helloWorld.on('attributesChange', function (e, data) {
    console.info(data);
});

// 改变class属性:
helloWorld.class = 'hello-new-world';

// 输出结果为:
{
    'class' : {
        mode: "change",
        newValue: "hello-new-world",
        oldValue: "hello-world"
    }
}

// [!] 注意: 为了节省资源，如果不需要侦听属性变更请使用removeListener或off将其移除。

helloWorld.off('attributesChange');

Methods

_defineGetterAndSetter(name)

# Ⓢ

设置标签参数的 Getter / Setter thanks: http://robertnyman.com/javascript/javascript-getters-setters.html

Arguments

  • name ( string|boolean ): 参数名称

_loadJsAndInit(js, dom)

# Ⓢ

加载JS并使用模块加载器初始化。

Arguments

  • js ( string ): 组件 js 文件
  • dom ( dom ): 挂载节点(标签)

_setCssObserver(args, args.key, args.callback, [args.selectors])

# Ⓢ

[核心实现] 设置 CSS Observer 侦听机制

Arguments

  • args ( string ): 入参对象
  • args.key ( string ): CSS Keyframes 样式名称
  • args.callback ( function ): 侦测回调
  • [args.selectors] ( string ): 作用的选择器，如果填写将自动生成触发响应的CSS并插入到头部，适用于前置样式后置标签。

Example

// 无论有无selectors，以下JS都将生成以下CSS片段并插入头部 :
//      @keyframes style-ready-trigger {from{opacity:0;}to{opacity:0;}}
//      @-webkit-keyframes style-ready-trigger {from{opacity:0;}to{opacity:0;}}

// 当以下样式开始对某个标签生效的时候，即会开始触发你绑定的callback方法，并能够在其中获取到当前正在作用的DOM。
//      tag-name{
//          animation-duration:1ms;
//          -webkit-animation-duration:1ms;
//          animation-name:style-ready-trigger;
//          -webkit-animation-name:style-ready-trigger;
//      }
//（适用于标签节点已存在于HTML，手动作用样式于标签，如在标签对应的CSS样式文件中携带该CSS，这里用于侦测styleReady的实现）

// 这里因为有传导 selectors 参数,所以额外将以下CSS也自动插入头部。
// hello-world,in-hello-world{animation-duration:1ms;-webkit-animation-duration:1ms;animation-name:style-ready;-webkit-animation-name:style-ready;}
//（适用于标签节点不存在于HTML，预先准备好样式等待标签进入自动触发回调，这里用于侦测tagInsert - auto init的实现）

_setCssObserver({
    key : 'style-ready-trigger',
    callback : function(args){
        // 获取作用标签DOM
        var dom = args.target;
        // 触发自定义事件
        dom.trigger('__your_custom_event');
    },
    selectors : 'hello-world,in-hello-world'
});


// 检查兼容性:
//    http://caniuse.com/#feat=css-animation

// 感谢:
//    http://davidwalsh.name/detect-node-insertion
//    http://jsperf.com/css-nodeinserted-vs-mutation-nodeinserted
//    http://pymaster.logdown.com/post/230263-simple-and-crude-detecting-elements-for-establishing

_tiggerStyleReady(args.event)

# Ⓢ

触发样式准备完成的回调

Arguments

  • args.event ( evnet ): DOMInsert插入标签回调传递的evnet对象

_tiggerTagInsert(args)

# Ⓢ

触发标签插入的回调

Arguments

  • args ( object ): 回调参数
  • args.target ( object ): 目标DOM

Properties

_asyncData

# Ⓢ

(Object): 异步依赖数据存储

Example

{
   '::key1' : { flag : true },
   '::key2' : 'foo'
}

_loader

# Ⓢ

(string): 模块加载器类型

Example

'seajs' | 'requirejs'

_requireDataDomMap

# Ⓢ

(Object): 依赖数据与DOM的关联储存

Example

{
   '::key1' : [ tagDom1, tagDom2, tagDom3 ],
   '::key2' : [...]
}