xmlplus

API

提供全面的框架七类接口索引以及描述，如文档中已有详细介绍的，则仅作简要说明，并给出相应的文档链接。

概述

本文档提供全面的与框架相关的接口索引及描述，如 文档 中已有详细介绍的，则仅作简要说明，并给出相应的链接。按照所属对象划分，接口可分为三类，包括全局对象接口、集合对象接口以及个体对象接口。其中全局对象接口也叫全局接口，此类接口由全局对象 xp 或者 xmlplus 引用，其引用方式如下：

xp.api_name([parameters])

或者

xmlplus.api_name([parameters])

集合对象接口也叫集体对象接口，此类接口由集合对象引用。个体对象接口则由个体对象引用，下面是两类接口使用的一个示例。

// 00-01
Example: {
    xml: "<div id='example'>\
            <button>foo</button>\
            <button>bar</button>\
          </div>",
    fun: function (sys, items, opts) {
        sys.example.text();            // text 是个体对象接口
        sys.example.kids().hash();     // hash 是集体对象接口
    }
}

对于每一个函数接口，本文档以如下示例的格式编写，该示例是系统函数 each 的详细描述。

each

each(object,callback)
  • object : Array | Object 要迭代的数组或对象
  • callback : Function 在每个对象上执行的函数
  • Returns : Array | Object 第一个实参

一个通用的迭代器函数，可以用来无缝地迭代数组和对象。其中，对于具有 length 属性的数组和数组类对象（例如函数的 arguments 对象），则通过数字索引（从 0 到长度 length - 1）进行迭代。而其他对象则通过它们的命名属性进行迭代。

// 01-15
xp.each(['a','b','c'], function (index, value) {
    console.log(index, value);
});

xp.each({a:1,b:2,c:3}, function (key, value) {
    console.log(key, value);
});

对于上面的接口描述示例，刚开始是函数名，函数名加粗显示。其次是函数声明，函数声明由函数名以及参数列表构成。参数列表由零个或多个逗号分隔，可选的参数则包含于中括号。然后是参数列表中每一个参数的详细描述。描述的内容包含参数类型和参数的简单解释。参数类型可以是下面给出的任何一个。如果允许多个类型，则需要用竖线 | 分隔开来。

  • String：字符串
  • Number：数值
  • Boolean：布尔型
  • RegExp：正则表达式
  • Object：即 Javascript 中的 Object
  • Integer：整型数
  • Proxy: 代理对象
  • PlainObject：由 {} 或者 new Object 创建
  • Collection：指代集合对象
  • HTMLElement：指代 HTML 元素
  • XMLElement：指代由全局函数 parseXML 解析后返回的数据类型
  • Event：指代事件侦听器的形参类型
  • Message：指代消息侦听器的形参类型
  • ValueObject：指代值对象类型
  • SystemObject：指代系统对象类型
  • AnyType：指代任意的类型

如果函数有返回值，那么还会有一个返回值描述，该描述由 Returns 开始，其后是返回值的类型和解释。之后就到了函数的用法描述，该描述包含了文字和相关的示例源码。另外，请注意示例开头的一个注释 01-15。你可以根据该注释定位到目录 /example/api/01-global/15/，注释中的 01 即章节序，15 就是示例所在目录的名称。



全局

startup

startup(object[,parent][,options])
  • object : XMLElement | SystemObject | String 用于实例化的内容
  • parent : String | HTMLElement 一个 HTML 元素 ID 或者一个 HTML 元素
  • options : PlainObject 为目标组件提供初始输入值的普通对象
  • Returns : SystemObject 实例化出的系统对象

该函数用于实例化一个组件，一般用于应用的初始化。更多内容，请查看 组件的实例化。

// 01-01
xmlplus("xp", function (xp, $_) {
    $_().imports({
        Example: {
            xml: "<h1>hello, world</h1>"
        }
    });
}).ready(function() {
    xp.startup("//xp/Example");
});

create

create(path[,options])
  • path : String 组件的绝对路径
  • options : AnyType 为目标组件提供初始输入值
  • Returns : AnyType 实例化出的组件对象

该函数是一个用于创建轻量的组件对象的函数，它只是简单地调用组件的函数项来返回所需的对象。

// 01-02
xmlplus("xp", function (xp, $_) {
    $_().imports({
        Example: {
            fun: function(sys, items, opts) {
                function sayHello() {
                    console.log(sys, items, "hello");
                }
                return { sayHello: sayHello };
            }
        }
    });
});
xmlplus.create("//xp/Example").sayHello(); // null null hello

注意，用该函数创建的组件对象不会被加入组件树中，也就是说函数项中 sys 以及 items 均为空。用该函数创建的组件对象比用系统函数 append、before 以及 replace 创建的组件对象效率更高，然而功能却有限。

guid

guid()
  • Returns : String 获取到的标识符

获取系统内唯一的全局标识符。该标识符的生成规则如下：刚开始是 a,b,...z，然后是 aa,ab,...az，以此类推。该标识符最先会由系统内部使用，所以你获取到的标识符一般不是从 a 开始。

// 01-03
console.log(xp.guid()); // 一个标识符字符串

ready

ready(callback)
  • callback : Function 在 DOM 准备就绪后执行的函数

该函数用于在 DOM 完全加载时执行指定的函数，该函数仅在浏览器端可见。这里指的 DOM 是广义的 DOM，它包含了我们的自定义组件。请看下面的一个 HTML 文件的 body 中的内容：

<!-- 01-04 -->
<h1>hello, world</h1>
<i:Calendar xmlns:i='//xp'>custom</i:Calendar>
<script>
  xp.ready(function () {
      console.log("DOM is ready.")
  });
</script>

上述的 ready 语句的回调函数开始执行，当且仅当 h1 元素和自定义组件 Calendar 均完成实例化后。

type

type(obj)
  • obj : AnyType

该函数用于确定 JavaScript 内置对象的类型，并返回小写形式的类型名称。该函数源于新近版本的 jQuery，如需更详细的内容请参考 jQuery.type。

// 01-05
console.log(xp.type("undefined")); // "undefined"
console.log(xp.type(true));        // "boolean"
console.log(xp.type(3));           // "number"

isArray

isArray(obj)
  • obj : Object 用于测试是否是数组的对象

该函数用于确定给定对象是否为数组。

// 01-07
console.log(xp.isArray([])); // true
console.log(xp.isArray({})); // false

likeArray

likeArray(obj)
  • obj : Object 用于测试是否是伪数组的对象

该函数用于确定给定对象是否为伪数组。

isWindow

isWindow(obj)
  • obj : PlainObject 用于测试是否是一个窗体的对象

该函数用于确定给定对象是否为窗体。

// 01-06
console.log(xp.isWindow(window)); // true

isFunction

isFunction(obj)
  • obj : Object 用于测试是否是函数的对象

该函数用于确定给定对象是否为函数。

// 01-08
console.log(xp.isFunction(xp));  // true
console.log(xp.isFunction({}));  // false

isNumeric

isNumeric(value)
  • value : AnyType 要检测的值

确定给定参数是否可以看作一个 JavaScript 数值。

// 01-09
console.log(xp.isNumeric(3));   // true
console.log(xp.isNumeric("3")); // true
console.log(xp.isNumeric({}));  // false

isPlainObject

isPlainObject(object)
  • object : AnyType 要检测的值

检查对象是否是普通对象（使用 {} 或 new Object 创建）。

// 01-10
console.log(xp.isPlainObject({}));   // true
console.log(xp.isPlainObject("3"));  // false
console.log(xp.isPlainObject([]));   // false

isEmptyObject

isEmptyObject(object)
  • object : Object 用于被检查是否为空的对象

检查指定对象是否为空（即不包含可枚举的属性）。

// 01-11
console.log(xp.isEmptyObject({}));            // true
console.log(xp.isEmptyObject({key: "key"}));  // false
console.log(xp.isEmptyObject([]));            // true

isSystemObject

isSystemObject(obj)
  • obj : PlainObject 将被检查以查看它是否是一个系统对象

检查对象是否为系统对象。

// 01-12
Example: {
    xml: "<h1 id='example'>hello, world</h1>",
    fun: function (sys, items, opts) {
        console.log(xp.isSystemObject({}));            // false
        console.log(xp.isSystemObject(this));          // true
        console.log(xp.isSystemObject(sys.example));   // true
    }
}

extend

extend([deep,]target[,object1][,objectN])
  • deep : Boolean 如果为 true，则将进行递归合并（也称为深度复制）
  • target : Object 新属性将被添加到的目标对象
  • object1 : Object 包含要合并的属性的第一个对象。
  • objectN : Object 包含要合并的属性的其他对象。

将两个或多个对象的内容合并到第一个对象中。该函数来源于新近版本的 jQuery，如需更详细的内容请参考 jQuery.extend。

// 01-13
var result = xp.extend({key1: "hello"},{key2: "world"});
console.log(result); // {key1: "hello, key2: "world"};

each

each(object,callback)
  • array : Array | Object 要迭代的数组或对象
  • callback : Function 在每个对象上执行的函数

一个通用的迭代器函数，可以用来无缝地迭代对象和数组。其中，对于具有 length 属性的数组和数组类对象（例如函数的 arguments 对象），则通过数字索引（从 0 到长度 length - 1）进行迭代。而其他对象则通过它们的命名属性进行迭代。

// 01-14
xp.each(['a','b','c'], function (index, value) {
    console.log(index, value);
});
xp.each({a:1,b:2,c:3}, function (key, value) {
    console.log(key, value);
});

parseXML

parseXML(data)
  • data : String 一个格式正确的 XML 字符串

此函数将给定的字符串解析为 XML 文档。

// 01-15
var xml = "<title>Title</title>";
var xmlDoc = xp.parseXML(xml);
console.log(xmlDoc.lastChild.nodeName); // title

serialize

serialize(node)
  • node : HTMLElement | XMLElement DOM 节点
  • Returns : String XML 字符串

序列化指定的 DOM 节点，序列化后的结果包含节点的子级。

// 01-16
// <h1 xmlns="http://www.w3.org/1999/xhtml" id="h1">hello,world</h1>
console.log(xp.serialize(document.getElementById("h1")));

hasNamespace

hasNamespace(object)
  • object : String 组件路径，比如 //xp/Index
  • Returns : Boolean 布尔值

判定当前系统是否包含给定的命名空间，如果包含则返回 true，否则返回 false。

// 01-17
console.log(xp.hasNamespace(null));         // false
console.log(xp.hasNamespace("div"));        // false
console.log(xp.hasNamespace("//xp/Index")); // true 或者 false，这取决于实际的应用

hasComponent

hasComponent(object)
  • object : String HTML 标签或者组件路径，比如 div 或 //xp/Index
  • Returns : Boolean | PlainObject 布尔值或者组件的 JSON 描述

判定当前系统中是否包含给定的组件，如果不包含则返回 false；如果是 HTML 标签，则返回 true；否则返回组件的 JSON 描述。

// 01-18
console.log(xp.hasComponent(null));         // false
console.log(xp.hasComponent("div"));        // true
console.log(xp.hasComponent("//xp/Index")); // false 或者一个组件的 JSON 描述，这取决于实际的应用

getElementById

getElementById(id[,isGuid])
  • id : String 对象标识符
  • isGuid : Boolean 是否组件对象标识符
  • Returns : HTMLElement | SystemObject HTML 元素对象或者系统对象

由给定的标识符获取相关对象。这需要分三种情况来看。如果 isGuid 为 true，那么将返回系统对象。请参考下面的示例。

// 01-19
Example: {
    xml: "<div id='example'/>",
    fun: function (sys, items, opts) {
        var guid = sys.index.guid();
        console.log(sys.index == xp.getElementById(guid, true); // true
    }
}

如果不提供 isGuid 参数，并且当前 HTML 文档中存在 id 值为给定值的元素，那么将返回 HTML 元素，这等效于浏览器自带的 document.getElementById。请参考下面的示例。

// 01-20
<html>
    <head>
        <script src="xmlplus.js"></script>
    </head>
    <body>
        <span id="text">text</span>
        <script>
            console.log(xp.getElementById("text") == document.getElementById("text")); // true
        </script>
    </body>
</html>

如果不提供 isGuid 参数，并且当前 HTML 文档中存在 id 值为给定值的自定义组件对象描述，那么将返回系统对象。请参考下面的示例。

// 01-21
<html>
    <head>
        <script src="xmlplus.js"></script>
        <script>
            xmlplus("xp", function (xp, $_) {
                $_().imports({
                    Index: {}
                });
            }).ready(function() {
                console.log(xp.getElementById("index")); // SystemObject
            });
        </script>
    </head>
    <body>
        <i:Index id="index" xmlns='//xp'></i:Index>
    </body>
</html>

exports

exports(object)
  • object : Proxy 代理对象
  • Returns : PlainObject 转化得到的普通对象

将数据绑定后得到的代理对象转化成普通的 JSON 对象。

// 01-22
Example: {
    xml: "<div id='example'>\
            <button id='item'/>\
          </div>",
    fun: function (sys, items, opts) {
        let data = [1,2,3,4];
        let proxy = sys.item.bind(data);
        console.log(xp.exports(proxy.model));  // [1,2,3,4]
    }
}

集合

集合对象类同于数组，它除了包含 every, forEach, indexOf, map, pop, push, shift, some, slice, splice, unshift 这些函数接口。还包含了下面的特有接口。

call

call(funName[,parameter1][,parameterN])
  • funName : Function 调用的函数名
  • parameter1 : AnyType 给函数提供第一个参数
  • parameterN : AnyType 给函数提供第 N 个参数

遍历集合对象，并调用给定的函数，其中函数的参数由函数名的后续实参提供。

// 02-01
Example: {
   xml: "<div id='example'>\
             <h1 id='dog'>dog</h1>\
             <h1 id='cat'>cat</h1>\
         </div>",
   fun: function (sys, items, opts) {
       var kids = sys.example.kids();             // kids 返回的对象为集合对象
       kids.call("css", "border", "1px solid black");
   }
}

hash

hash()
  • Returns : PlainObject 包含键值对的普通对象

将类数组形式的集合对象转化包含键值对的普通对象，转换过程可参考下面的函数。

function hash() {
    var i = 0, table = {};
    for (; i < this.length; i++)
        table[this[i]] = this[i];
    return table;
}

注：该函数中的 this 即包含系统对象的集合。

// 02-02
Example: {
   xml: "<div id='example'>\
             <h1 id='dog'>dog</h1>\
             <h1 id='cat'>cat</h1>\
         </div>",
   fun: function (sys, items, opts) {
       var kids = sys.example.kids();         // 函数 kids 返回系统对象集
       var objects = kids.hash();             // 函数 hash 返回包含键值对集合的普通对象
       for ( var key in objects ) {
           console.log(key);                  // 会依次打印出 dog、cat
       }
   }
}

values

values()
  • Returns : Collection // 值对象集

将系统对象的集合转化成值对象的集合。转换过程可参考下面的函数。

function values() {
    var result = new Collection;
    for (var i = 0; i < this.length; i++)
        result.push(this[i].val());
    return result;
}

注：该函数中的 this 即包含系统对象的集合。

// 02-03
Example: {
   xml: "<div id='example'>\
             <h1 id='dog'>dog</h1>\
             <h1 id='cat'>cat</h1>\
         </div>",
   fun: function (sys, items, opts) {
       var kids = sys.example.kids();
       var objects = kids.values();
       console.log(kids, objects);        // 前者包含的是系统对象集，后者包含的是值对象集
   }
}

DOM

text

text()
  • Returns : String 获取到的文本

该函数用于获取组件对象的文本，它相当于获取相应 HTML 元素的 textContent 值。

text(value)
  • value : String 要设置的文本
  • Returns : SystemObject 函数的调用者

该函数用于设置组件对象的文本，这需要分两种情况看待。其一，如果组件对象的子级仅包含一个文本对象，那么它相当于设置相应 HTML 元素的 textContent 值。其二，如果组件对象的子级包含多个对象，那么该函数会先移除所有的儿子对象，然后以给定的文本创建一个文本对象。

// 03-01
Example: {
    xml: "<h1 id='example'>hello</h1>",
    fun: function (sys, items, opts) {
        console.log(sys.example.text());  // hello
        sys.example.text("world");
        console.log(sys.example.text());  // world
    }
}

prop

prop(propertyName)
  • propertyName : String 要获取的属性的名称
  • Returns : String 属性的值

该函数根据给定的属性名，获取组件对象的属性值。

prop(propertyName,value)
  • propertyName : String 要设置的属性的名称
  • value : String 要设置的属性值
  • Returns : SystemObject 函数的调用者

该函数根据给定的属性名，设置组件对象的属性值。

// 03-02
Example: {
    xml: "<input id='example' type='checkbox'/>",
    fun: function (sys, items, opts) {
        console.log(sys.example.prop("checked"));  // false
        sys.example.prop("checked", true);
        console.log(sys.example.prop("checked"));  // true
    }
}

removeProp

removeProp(propertyName)
  • propertyName : String 要删除的属性的名称
  • Returns : SystemObject 函数的调用者

该函数用于删除组件对象给定属性。

// 03-03
Example: {
    xml: "<input id='example'/>",
    fun: function (sys, items, opts) {
        sys.example.prop("data", "hello,world");
        console.log(sys.example.prop("data"));   // hello,world
        sys.example.removeProp("data");
        console.log(sys.example.prop("data"));   // undefined
    }
}

attr

attr(attributeName)
  • attributeName : String 要获取的属性的名称
  • Returns : String 属性的值

该函数根据给定的属性名，获取组件对象的属性值。

attr(attributeName,value)
  • attributeName : String 要设置的属性的名称
  • value : String 要设置的属性值
  • Returns : SystemObject 函数的调用者

该函数根据给定的属性名，设置组件对象的属性值。

// 03-04
Example: {
    xml: "<input id='example'/>",
    fun: function (sys, items, opts) {
        console.log(sys.example.attr("data"));   // null
        sys.example.attr("data", "hello");
        console.log(sys.example.attr("data"));   // hello
    }
}

removeAttr

removeAttr(attributeName)
  • attributeName : String 要删除的属性的名称
  • Returns : SystemObject 函数的调用者

该函数用于删除组件对象的给定属性。

// 03-05
Example: {
    xml: "<input id='example'/>",
    fun: function (sys, items, opts) {
        sys.example.attr("data", "hello");
        console.log(sys.example.attr("data"));   // hello
        sys.example.removeAttr("data");
        console.log(sys.example.attr("data"));   // null
    }
}

addClass

addClass(className[,context])
  • className : String 要添加到 class 属性的一个类或多个空格分隔的类。
  • context : SystemObject 指代上下文的系统对象
  • Returns : SystemObject 函数的调用者

该函数用于给组件对象添加类，该类名可以是独立的，也可以是由多个空格分隔的类集合。其中可选的参数 context 是一系统对象，用于指明该对象的宿主组件标识符。该标识符会替换掉参数 className 中出现的符号 #。

默认情况下，context 为函数 addClass 的调用者，请看下面示例。

// 03-06
Example: {
    css: "#klass { color: blue; }",
    xml: "<div id='example'>\
            <Widget id='widget'/>\
            <h1 id='text'>hello, world</h1>\
          </div>",
    fun: function (sys, items, opts) {
        sys.text.addClass("#klass");                // 引用的是当前组件的 klass
    }
},
Widget: {
    css: "#klass { color: red; }",
    xml: "<h1 id='widget'>hello, world</h1>",
    fun: function (sys, items, opts) {
        sys.widget.addClass("#klass", this);        // 引用的是组件 Example 的 klass
    }
}

注意，参数 className 中出现的符号 # 所代表的内容与样式项中出现的符号 $ 所代表的内容一致。对于类名中出现的通配符，详细内容请参考 样式项中的通配符。

removeClass

removeClass([className])
  • className : String 要从 class 属性删除的一个类或多个空格分隔的类。
  • Returns : SystemObject 函数的调用者

该函数用于移除当前对象的相关类，该类名可以是独立的，也可以是由多个空格分隔类集合。如果不指定类名，则默认移除组件对象相关的所有类。

// 03-07
Example: {
    css: "#klass { color: blue; }",
    xml: "<h1 id='example'>hello,world</h1>",
    map: { nofragment: true },
    fun: function (sys, items, opts) {
        sys.example.addClass("#klass");
        console.log(sys.example.css("color")); // rgb(0, 0, 255)
        sys.example.removeClass("#klass");
        console.log(sys.example.css("color")); // rgb(0, 0, 0)
    }
}

注意，此示例中需要禁用文档碎片管理，否则语句 sys.example.css("color") 将返回空值。关于文档碎片的更多内容请参考 使用文档碎片。

contains

contains(target)
  • target : HTMLElement | SystemObject
  • Returns : Boolean

该函数用于判定当前组件对象是否包含给定的对象。该函数的判定逻辑是，当前组件对象对应的 HTML 元素与给定对象对应的 HTML 元素存在上下级关系或者相等关系，那么该函数返回 true，否则返回 false。

// 03-08
Example: {
    xml: "<div id='example'>\
            <h1 id='hello'>hello</h1>\
          </div>",
    fun: function (sys, items, opts) {
        console.log(sys.example.contains(null));             // false
        console.log(sys.example.contains(document.body));    // false
        console.log(sys.example.contains(sys.example));      // true
        console.log(sys.example.contains(sys.hello));        // true
        console.log(sys.example.contains(sys.hello.elem())); // true
    }
}

css

css(propertyName)
  • propertyName : String 要获取的 CSS 属性名称
  • Returns : String CSS 属性值

该函数根据给定的属性名，获取组件对象的 CSS 属性值。

css(propertyName,value)
  • propertyName : String 要设置的 CSS 属性名称
  • value : String 要设置的 CSS 属性值

该函数根据给定的属性名，设置组件对象的 CSS 属性值。

// 03-09
Example: {
    xml: "<h1 id='example'>hello, world</h1>",
    map: { nofragment: true },
    fun: function (sys, items, opts) {
        console.log(sys.example.css("color")); // rgb(0, 0, 0)
        sys.example.css("color", "blue");
        console.log(sys.example.css("color")); // blue
    }
}

注意，此示例中需要禁用文档碎片管理，否则第一个获取颜色值的语句 sys.example.css("color") 将返回空值。关于文档碎片的更多内容请参考 使用文档碎片。

show

show()
  • Returns : SystemObject 函数的调用者

该函数用于显示组件对象。在服务端，它相当于移除相关 HTML 元素的 display 样式。在浏览器端，它会设定 display 样式为初始值。

// 03-10
Example: {
    css: "#hello { display: none; }",
    xml: "<div id='example'>\
             <h1 id='hello'>hello, world</h1>\
             <button id='button'>show</button>\
          </div>",
    fun: function (sys, items, opts) {
        sys.button.once("click", sys.hello.show);
    }
}

hide

hide()
  • Returns : SystemObject 函数的调用者

该函数用于隐藏组件对象，它相当于设定相关 HTML 元素的 display 样式值为 none。

// 03-11
Example: {
    xml: "<div id='example'>\
             <h1 id='hello'>hello, world</h1>\
             <button id='button'>hide</button>\
          </div>",
    fun: function (sys, items, opts) {
        sys.button.once("click", sys.hello.hide);
    }
}

width

width()
  • Returns : Number 返回的宽度值

该函数用于获取组件对象的宽度值。

width(value)
  • value : Number 需要设定的宽度值
  • Returns : SystemObject 函数的调用者

该函数用于设置组件对象的宽度值。

// 03-12
Example: {
    xml: "<h1 id='example'>hello, world</h1>",
    map: { nofragment: true },
    fun: function (sys, items, opts) {
        sys.example.width(100);
        console.log(sys.example.width());
    }
}

注意，此示例中需要禁用文档碎片管理，否则语句 sys.example.width() 将返回 0。关于文档碎片的更多内容请参考 使用文档碎片。

height

height()
  • Returns : Number 返回的高度值

该函数用于获取组件对象的高度值。

height(value)
  • value : Number 需要设定的高度值
  • Returns : SystemObject 函数的调用者

该函数用于设置组件对象的高度值。

// 03-13
Example: {
    xml: "<h1 id='example'>hello, world</h1>",
    map: { nofragment: true },
    fun: function (sys, items, opts) {
        sys.example.height(100);
        console.log(sys.example.height());
    }
}

注意，此示例中需要禁用文档碎片管理，否则的语句 sys.example.height() 将返回 0。关于文档碎片的更多内容请参考 使用文档碎片。

offset

offset()
  • Returns : PlainObject 组件对象的偏移坐标

返回组件对象的偏移坐标。返回的对象包含两个整型属性：top 和 left，以像素计。此函数仅对可见元素有效。

offset(value)
  • value : PlainObject 要设置的偏移坐标对象
  • Returns : SystemObject 函数的调用者

设置组件对象的偏移坐标。它可以是一个值对，比如 { top:100, left:0 }，或者带有 top 和 left 属性的对象。

// 03-14
Example: {
    css: "#example { position: relative; }"
    xml: "<div id='example'>\
            <p id='text'>hello,world</p>\
          </div>",
    map: { nofragment: true },
    fun: function (sys, items, opts) {
        var offset = sys.example.offset();
        console.log(offset.top, offset.left);  // 16 8
        sys.example.offset({top:100, left:0});
        offset = sys.example.offset();
        console.log(offset.top, offset.left);  // 100 0
    }
}

注意，此示例中需要禁用文档碎片管理，否则语句 sys.example.offset() 将返回 { top:0, left:0 }。关于文档碎片的更多内容请参考 使用文档碎片。

position

position()
  • Returns : PlainObject 组件对象相对于父元素的位置（偏移）

该函数返回组件对象相对于父元素的位置（偏移）。返回的对象包含两个整型属性：top 和 left，以像素计。此函数仅对可见元素有效。

// 03-15
Example: {
    xml: "<div id='example'>\
            <p id='text'>hello,world</p>\
          </div>",
    map: { nofragment: true },
    fun: function (sys, items, opts) {
        var p = sys.text.position();
        console.log(p.left, p.top);  // 8 0
    }
}

scrollTop

scrollTop()
  • Returns : Number 垂直偏移值

该函数用于返回组件对象的滚动条的垂直位置。此位置指的是滚动条相对于其顶部的偏移。

scrollTop(offset)
  • Returns : SystemObject 函数的调用者

该函数用于设置组件对象的滚动条的垂直位置。offset 指的是滚动条相对于其顶部的偏移。

// 03-16
Example: {
    css: "#doc { border:1px solid black; width:200px; height:200px; overflow:auto; }",
    xml: "<div id='example'>\
            <div id='doc'>\
                This is some text. This is some text. This is some text. This is some text. \
                This is some text. This is some text. This is some text. This is some text. \
                This is some text. This is some text. This is some text. This is some text. \
                This is some text. This is some text. This is some text. This is some text. \
            </div>\
            <button id='getting'>get scrollbar top offset</button>\
            <button id='setting'>set scrollbar top offset to 30px</button>\
          </div>",
    fun: function (sys, items, opts) {
        sys.getting.on("click", function() {
            console.log(sys.doc.scrollTop());
        });
        sys.setting.on("click", function () {
            sys.doc.scrollTop(30);
        });
    }
}

scrollLeft

scrollLeft()
  • Returns : Number 水平偏移值

该函数用于返回组件对象的滚动条的水平位置。此位置指的是滚动条相对于其左侧边的偏移。

scrollLeft(offset)
  • Returns : SystemObject 函数的调用者

该函数用于设置组件对象的滚动条的水平位置。offset 指的是滚动条相对于其左侧边的偏移。

// 03-17
Example: {
    css: "#doc { border:1px solid black; width:100px; height:130px; overflow:auto }",
    xml: "<div id='example'>\
            <div id='doc'>\
                The longest word in the english dictionary is: pneumonoultramicroscopicsilicovolcanoconiosis. \
            </div>\
            <button id='getting'>get scrollbar left offset</button>\
            <button id='setting'>set scrollbar left offset to 30px</button>\
          </div>",
    fun: function (sys, items, opts) {
        sys.getting.on("click", function () {
            console.log(sys.doc.scrollLeft());
        });
        sys.setting.on("click", function () {
            sys.doc.scrollLeft(30);
        });
    }
}

检索

与检索相关的 API 在文档的相关章节有详细介绍，这里仅给出个概要。更多内容请参考 检索。

sys

sys(selector[,context])
  • selector : String XPath 表达式，比如 * 或者 /div
  • context : SystemObject 代表上下文的系统对象
  • Returns : Collection 检索到的系统对象集

该函数根据给定的 XPath 表达式，获取系统对象集。若不指定上下文，则默认以 XML 文档根为上下文。更多内容请参考 通用检索接口。

// 04-01
Example: {
   xml: "<div id='example'>\
             <button>foo</button>\
             <button>bar</button>\
         </div>",
   fun: function (sys, items, opts) {
       console.log(sys("//*").length); // 3
       sys("//button").call("css", "color", "blue");
   }
}

items

items(selector[,context])
  • selector : String XPath 表达式，比如 * 或者 /div
  • context : SystemObject 代表上下文的系统对象
  • Returns : Collection 检索到的值对象集

该函数根据给定的 XPath 表达式，获取值对象集。若不指定上下文，则默认以 XML 文档根为上下文。更多内容请参考 通用检索接口。

// 04-02
Example: {
   xml: "<div id='example'>\
             <Button>foo</Button>\
             <Button>bar</Button>\
         </div>",
   fun: function (sys, items, opts) {
       console.log(items("//*").length); // 3
       items("//Button").call("color", "blue");
   }
}，
Button: {
    xml: "<button id='button'/>",
    fun: function (sys, items, opts) {
        function color(value) {
            sys.btn.css("color", value);
        }
        return { color: color };
    }
}

find

find(selector)
  • selector : String XPath 表达式，比如 * 或者 /div
  • Returns : Collection 检索到的系统对象集

该函数以当前组件对象为上下文检索所需的对象集。更多内容请参考 find。

// 04-03
Example: {
   xml: "<div id='example'>\
             <button id='foo'>foo</button>\
             <button id='bar'>bar</button>\
         </div>",
   fun: function (sys, items, opts) {
       var res = sys.example.find("button");
       res.call("css", "color", "blue");
   }
}

get

get(index)
  • index : Integer 索引
  • Returns : SystemObject 子级的第 index 个系统对象

该函数根据给定的索引返回当前组件对象子级的某一系统对象，若无则不返回任何对象。更多内容请参考 get。

// 04-04
Example: {
   xml: "<div id='example'>first\
             <button id='foo'>foo</button>\
             <button id='bar'>bar</button>last\
         </div>",
   fun: function (sys, items, opts) {
       console.log(sys.example.get(0).text());  // foo
       console.log(sys.example.get(1).text());  // bar
   }
}

first

first([nodeType])
  • nodeType : Integer XML 的节点类型
  • Returns : SystemObject 子级的第一个系统对象

该函数根据给定的 XML 节点类型，获取当前组件对象子级的第一个对象。默认节点类型为元素。更多内容请参考 first 和 last。

// 04-05
Example: {
   xml: "<div id='example'>first\
             <button id='foo'>foo</button>\
             <button id='bar'>bar</button>last\
         </div>",
   fun: function (sys, items, opts) {
       console.log(sys.example.first().text());  // foo
       console.log(sys.example.first(3).text()); // first
   }
}

last

last([nodeType])
  • nodeType : Integer XML 的节点类型
  • Returns : SystemObject 子级的最后一个系统对象

该函数根据给定的 XML 节点类型，获取当前组件对象子级的最后一个对象。默认节点类型为元素。更多内容请参考 first 和 last。

// 04-06
Example: {
   xml: "<div id='example'>first\
             <button id='foo'>foo</button>\
             <button id='bar'>bar</button>last\
         </div>",
   fun: function (sys, items, opts) {
       console.log(sys.example.last().text());   // bar
       console.log(sys.example.last(3).text());  // last
   }
}

next

next([nodeType])
  • nodeType : Integer XML 的节点类型
  • Returns : SystemObject 下一个系统对象

该函数根据给定的 XML 节点类型，获取当前组件对象的下一个对象。默认节点类型为元素。更多内容请参考 next 和 prev。

// 04-07
Example: {
   xml: "<div id='example'>first\
             <button id='foo'>foo</button>\
             <button id='bar'>bar</button>last\
         </div>",
   fun: function (sys, items, opts) {
       console.log(sys.foo.next().text());               // bar
       console.log(sys.example.next());                  // undefined
       console.log(sys.bar.next(3).text());              // last
   }
}

prev

prev([nodeType])
  • nodeType : Integer XML 的节点类型
  • Returns : SystemObject 前一个系统对象

该函数根据给定的 XML 节点类型，获取当前组件对象前一个对象。默认节点类型为元素。更多内容请参考 next 和 prev。

// 04-08
Example: {
   xml: "<div id='example'>first\
             <button id='foo'>foo</button>\
             <button id='bar'>bar</button>last\
         </div>",
   fun: function (sys, items, opts) {
       console.log(sys.bar.prev().text());               // foo
       console.log(sys.example.prev());                  // undefined
       console.log(sys.foo.prev(3).text());              // first
   }
}

kids

kids([nodeType])
  • nodeType : Integer XML 的节点类型
  • Returns : Collection 儿子系统对象集

该函数根据给定的 XML 节点类型，获取当前组件对象所有儿子对象。默认节点类型为元素。如果给定节点类型为 0，则获取所有类型的儿子对象。更多内容请参考 kids。

// 04-09
Example: {
   xml: "<div id='example'>\
             <button id='foo'>foo</button>\
             <button id='bar'>bar</button>\
         </div>",
   fun: function (sys, items, opts) {
       console.log(sys.example.kids().length); // 2
   }
}

生命周期

与组件生命周期相关的 API 在文档的相关章节有详细介绍，这里仅给出个概要。更多内容请参考 生命周期。

append

append(target[,options])
  • target : XMLElement | SystemObject | String 用于追加的内容
  • options : PlainObject 为追加的新组件对象提供的初始化参数
  • Returns : SystemObject 追加的新系统对象

该函数用于追加一个组件对象到当前对象子级。其中可选的 options 参数用于给被追加的对象提供初始化参数，该参数仅当新对象为非基组件并且非已存在组件对象时才有效。更多内容请参考 组件对象的追加。

// 05-01
Example: {
    xml: "<div id='example'>\
              <button id='foo'>append</button>\
          </div>",
    fun: function (sys, items, opts) {
        sys.foo.on("click", function (e) {
            sys.example.append("<h1>hello,world</h1>");
        });
    }
}

before

before(target[,options])
  • target : XMLElement | SystemObject | String 用于插入的内容
  • options : PlainObject 为插入的新组件对象提供的初始化参数
  • Returns : SystemObject 插入的新系统对象

该函数用于在当前对象之前插入一个组件对象。其中可选的 options 参数用于给被插入的对象提供初始化参数，该参数仅当新对象为非基组件并且非已存在组件对象时才有效。更多内容请参考 组件对象的插入。

// 05-02
Example: {
    xml: "<div id='example'>\
              <button id='foo'>before</button>\
          </div>",
    fun: function (sys, items, opts) {
        sys.foo.on("click", function (e) {
            sys.foo.before("<h1>hello,world</h1>");
        });
    }
}

replace

replace(target[,options])
  • target : XMLElement | SystemObject | String 用于替换的内容
  • options : PlainObject 为新组件对象提供的初始化参数
  • Returns : SystemObject 替换后的新系统对象

该函数用于替换当前组件对象为一个新的组件对象。其中可选的 options 参数用于新对象提供初始化参数，该参数仅当新对象为非基组件并且非已存在组件对象时才有效。更多内容请参考 组件对象的替换。

// 05-03
Example: {
    xml: "<div id='example'>\
              <button id='foo'>replace</button>\
          </div>",
    fun: function (sys, items, opts) {
        sys.foo.once("click", function (e) {
            sys.foo.replace("<h1>hello,world</h1>");
        });
    }
}

remove

remove()

该函数用于移除当前组件对象。更多内容请参考 组件对象的移除。

// 05-04
Example: {
    xml: "<div id='example'>\
             <button id='foo'>destory</button>\
             <h1 id='bar'>Hello, world</h1>\
          </div>",
    fun: function (sys, items, opts) {
        sys.foo.once("click", sys.bar.remove);
    }
}

通信

与通信相关的 API 在文档的相关章节有详细介绍，这里仅给出个概要。更多内容请参考 事件与通信 以及 消息与通信。

on

on(eventType[,selector],handler)
  • eventType : String 事件类型，比如 click 或者 submit
  • selector : String XPath 表达式，比如 * 或者 /div
  • handler : Function(Event event) 侦听器
  • Returns : SystemObject 函数的调用者

该函数用于侦听一个事件，该事件可以是浏览器固有事件，也可以是系统对象接口 trigger 派发的事件。其中可选的 selector 参数用于筛选侦听的目标对象。更多内容请参考 事件的侦听。

// 06-01
Example: {
    xml: "<button id='example'>click</button>",
    fun: function (sys, items, opts) {
        sys.example.on("click", function (e) {
            console.log("hello, world");
        });
    }
}

off

off([handler])
off(selector[,handler])
off(eventType[,selector][,handler])
  • eventType : String 事件类型，比如 click 或者 submit
  • selector : String XPath 表达式，比如 * 或者 /div
  • handler : Function(Event event) 侦听器
  • Returns : SystemObject 函数的调用者

该函数用于取消一个事件的侦听，其中，不提供任何参数的函数调用将取消目标对象上注册的所有事件的侦听。更多内容请参考 事件的注销。

// 06-02
Example: {
    xml: "<button id='example'>click</button>",
    fun: function (sys, items, opts) {
        sys.example.on("click", function (e) {
            sys.example.off("click");
            console.log("hello, world");
        });
    }
}

once

once(eventType[,selector],handler)
  • eventType : String 事件类型，比如 click 或者 submit
  • selector : String XPath 表达式，比如 * 或者 /div
  • handler : Function(Event event) 侦听器
  • Returns : SystemObject 函数的调用者

该函数用于侦听一个事件，它与函数 on 的差别仅在于，前者仅侦听一次事件，后者可以多次侦听同一事件。更多内容请参考 事件的侦听。

// 06-03
Example: {
    xml: "<button id='example'>click</button>",
    fun: function (sys, items, opts) {
        sys.example.once("click", function (e) {
            console.log("hello, world");
        });
    }
}

trigger

trigger(eventType[,data])
  • eventType : String 事件类型，比如 click 或者 submit
  • data : AnyType 一个数组或者其他的任意的数据类型。
  • Returns : SystemObject 函数的调用者

该函数用于派发一个事件，可选参数 data 可以携带额外的数据。更多内容请参考 事件的派发。

// 06-04
Example: {
    xml: "<div id='example'>\
             <span id='span'>trigger</span>\
          </div>",
    fun: function (sys, items, opts) {
        sys.example.on("event", function (e) {
            console.log("hello, world");
        });
        sys.span.trigger("event");
    }
}

watch

watch(messageType,handler[,priority])
  • messageType : String 消息类型，比如 push 或者 ok
  • handler : Function(Message message) 侦听器
  • priority : Number 优先级，可以是 Infinity
  • Returns : SystemObject 函数的调用者

该函数用于侦听一个消息，该消息仅由系统函数 notify 派发。其中可选的 priority 参数用于指定回调函数的优先级。更多内容请参考 消息的派发与捕获。

// 06-05
Example: {
    xml: "<div id='example'/>",
    fun: function (sys, items, opts) {
        sys.example.watch("msg", function (e) {
            console.log(this.toString());
        }).notify("msg");
    }
}

unwatch

unwatch([handler])
unwatch(messageType[,handler])
  • messageType : String 事件类型，比如 push 或者 ok
  • handler : Function(Message message) 侦听器
  • Returns : SystemObject 函数的调用者

该函数用于取消一个消息的侦听。其中，不提供任何参数的函数调用将取消目标对象上注册的所有消息的侦听。更多内容请参考 消息的注销。

// 06-06
Example: {
    xml: "<span id='example'>foo</span>",
    fun: function (sys, items, opts) {
        sys.example.watch("msg", function (e) {
            sys.example.unwatch("msg");
            console.log(this.text());
        });
        sys.example.notify("msg").notify("msg");
    }
}

glance

glance(messageType,handler[,priority])
  • messageType : String 消息类型，比如 push 或者 ok
  • handler : Function(Message message) 侦听器
  • priority : Number 优先级，可以是 Infinity
  • Returns : SystemObject 函数的调用者

该函数用于侦听一个消息，它与函数 watch 的差别仅在于，前者仅侦听一次消息，后者可以多次侦听同一消息。更多内容请参考 消息的派发与捕获。

// 06-07
Example: {
    xml: "<span id='example'>foo</span>",
    fun: function (sys, items, opts) {
        sys.example.glance("msg", function (e) {
            console.log(this.text());
        });
        sys.example.notify("msg").notify("msg");
    }
}

notify

notify(messageType[,data])
  • messageType : String 一个事件类型，比如 push 或者 ok
  • data : AnyType 一个数组或者其他的任意的数据类型
  • Returns : SystemObject 函数的调用者

该函数用于派发一个消息，可选参数 data 可以携带额外的数据。更多内容请参考 消息的派发与捕获。

// 06-08
Example: {
    xml: "<div id='example'>\
             <span id='foo'>foo</span>\
          </div>",
    fun: function (sys, items, opts) {
        sys.foo.watch("msg", function (e, a, b) {
            console.log(a, b); // 37 hello,world
        });
        sys.example.notify("msg", [37, "hello,world"]);
    }
}

messages

messages(object)
  • Returns : Array 字符串数组

该函数用于返当前对象的消息作用域内的所有已被侦听的消息字符串。请参考下面的示例。

// 06-09
Example: {
    xml: "<div id='example'/>",
    fun: function (sys, items, opts) {
        this.watch("foo", ()=> console.log("foo"));
        this.watch("bar", ()=> console.log("bar"));
        console.log(this.messages()); // ["foo", "bar"]
    }
}

数据绑定

bind

bind(target)
  • target : String | Number | Boolean | Object | Array 被绑定的数据
  • Returns : Proxy 数据绑定后的代理对象

该函数用于将一个组件对象与一个数据对象绑定。更多内容请参考 数据绑定。

// 07-01
Example: {
    xml: "<div id='example'>\
            <input type='radio' name='n' value='USA'/>\
            <input type='radio' name='n' value='China'/>\
            <select id='select'>\
                <option>USA</option>\
                <option>China</option>\
            </select>\
          </div>",
    ali: {country: "//input | //select", },
    fun: function (sys, items, opts) {
        this.bind({country: "China"});
    }
}

其它

val

val()
  • Returns : ValueObject 值对象

该函数用于返回组件对象的值对象。值对象可以是 String、null 以及 undefined 等任何类型。在下面示例中，组件 Target 的函数项的返回值即所谓的值对象，此处的值对象与 items.example 相等。

// 08-01
Example: {
    xml: "<Target id='example'/>",
    fun: function (sys, items, opts) {
        var value = sys.example.val();
        console.log(value.text, value == items.example); // hello,world true
    }
},
Target: {
    fun: function (sys, items, opts) {
        return { text: "hello,world" };                  // 值对象由此返回
    }
}

localName

localName()
  • Returns : String 组件名

该函数用于返回组件对象的组件名。注意，只有 HTML 元素对象和自定义组件对象才有组件名，也就是只有这两种对象才包含该函数接口。

// 08-02
Example: {
    xml: "<div id='example'>\
            <Target id='target'/>\
          </div>",
    fun: function (sys, items, opts) {
        console.log(sys.example.localName());  // div
        console.log(sys.target.localName());   // Target
    }
},
Target: {}

namespace

namespace()
  • Returns : String 组件的命名空间

该函数返回组件的命名空间，命名空间以绝对路径形式给出。下面示例中，组件 Example 和 Target 均位于命名空间 //xp 中。

// 08-03
Example: {
    xml: "<Target id='example'/>",
    fun: function (sys, items, opts) {
        console.log(sys.example.namespace());  // //xp
    }
},
Target: {}

guid

guid()
  • Returns : String 组件对象标识符

该函数返回组件对象的标识符。每一组件对象都有一个唯一的标识符，该标识符由全局函数 guid 生成。

// 08-04
Example: {
    xml: "<div id='example'/>",
    fun: function (sys, items, opts) {
        console.log(sys.example.guid());  // 一个组件对象标识符
    }
}

toString

toString()
  • Returns : String 组件对象名或标识符

用于获得组件对象名或者标识符，仅当组件对象相应的 XML 元素不包含 id 属性时才返回唯一标识符，此时返回的标识符与系统函数 guid 返回的内容一致。

// 08-05
Example: {
    xml: "<div id='example'><span/></div>",
    fun: function (sys, items, opts) {
        console.log(sys.example.toString());         // example
        console.log(sys.example.first().toString()); // 组件对象标识符
    }
}

serialize

serialize([serializeXML])
  • serializeXML : Boolean 是否序列化组件的视图项，默认为 false
  • Returns : String 一个 HTML 字符串

用于序列化视图项或者视图项所对应的 HTML DOM 文档树。注意，下面示例中的注释内容是去除了空格以后的结果。

// 08-06
Example: {
    xml: "<div id='example'>\
            <Target id='target'/>\
          </div>",
    fun: function (sys, items, opts) {
        console.log(sys.example.serialize());      // <div><h1>hello, world</h1></div>
        console.log(sys.example.serialize(true));  // <div><Target id='target'/></div>
    }
},
Target: {
    xml: "<h1>hello, world</h1>"
}