Properties

version - String

KISSY 类库的版本号。

Config - KISSY.Config

KISSY 的配置信息。目前 Config 对象含有 debug 属性,可以通过设置 KISSY.Config.debug = true 来开启 debug 模式。

debug 模式默认关闭,但在以下情况下会自动开启:

  1. 引入的 js 文件是未压缩版本,比如 <script src="ks-core.js"></script>
  2. 访问的 url 路径中,带有 ks-debug 参数,比如 http://localhost/kissy.html?ks-debug

debug 模式开启时,源码中的 S.log 会利用浏览器的 console 对象输出调试信息。debug 模式关闭时,不会输出调试信息。

Methods

add KISSY add ( name, fn )

添加模块到 KISSY 对象。


KISSY.add('module-name', function(S) {
    // module code
    // 注:参数 S 就是 KISSY 本身。
});

这是 KISSY 内部代码的基本组织方式。当你想扩展 KISSY 时,推荐通过 add 方法来组织代码。

ready KISSY ready ( fn )

添加函数,在 DOM 加载完毕时执行。


KISSY.ready(function(S) {
    // code
});

这是 KISSY 外部代码的基本调用方式。为了保证代码执行时,依赖的 DOM 结构已准备好,推荐尽可能的将代码写在通过 ready 注册的函数里。

注意:在 DOM 加载完毕后,依旧可以通过 ready 添加函数,此时会立刻执行。

available void available ( id, fn )

添加函数,在 id 元素可用时立刻执行。

mix Object mix ( r, s, ov, wl )

将 s(upplier) 对象的成员复制到 r(eceiver) 对象上。

Parameters:
ov <Boolean> override, 表示复制时是否采用覆盖模式。默认为 true.
wl <Array> whitelist, 非空时,表示仅添加该列表中的成员。
Returns: Object
r 对象

var S = KISSY,
    r = { a: 'a', b: 'b' };

S.mix(r, { c: 'c' });
S.log(r.c); // => 'c'

S.mix(r, { a: 'a2' }, false);
S.log(r.a); // => 'a'

S.mix(r, { e: 'e', f: 'f' }, true, ['f']);
S.log(r.e); // => undefined
S.log(r.f); // => 'f'

该方法在 KISSY 里具有非常重要的地位。JavaScript 是一门动态语言,利用 mixin 特性,可以很方便的实现特性的静态复制和动态修改。

merge Object merge ( arguments/* Object* */ )

将多个对象的成员合并到一个新对象上。参数中,后面的对象成员会覆盖前面的。

Returns: Object
合并后的新对象

var S = KISSY,
    a = { a: 'a' },
    b = { b: 'b' },
    c = { b: 'b2', c: 'c' };

var o = S.merge(a, b, c);
S.log(o.a); // => 'a'
S.log(o.b); // => 'b2'
S.log(o.c); // => 'c'

// 常用的使用场景:
var defaultConfig = {
        /* ... */
    };
function ClassA(config) {
    // 合并配置信息
    config = S.merge(defaultConfig, config);
}

merge 方法常用来合并配置信息。

augment Object augment ( r, s, ov, wl )

将 s.prototype 的成员复制到 r.prototype 上。

s 可以是非函数对象,此时复制的就是 s 的成员。

可以一次传入多个 s, 比如 S.augment(r, s1, s2, s3, ov, wl)

Returns: Object
r 对象

var S = KISSY,
    Shoutable = {
        shout: function() { alert('I am ' + this.name + '.'); }
    };

function Dog(name) { this.name = 'Dog ' + name; }
function Pig(name) { this.name = 'Pig ' + name; }

S.augment(Dog, Shoutable);
S.augment(Pig, Shoutable);

new Dog('Jack').shout(); // => I am Dog Jack.
new Pig('Mary').shout(); // => I am Pig Mary.

augment 方法在 KISSY 里非常基础非常重要。传统 OO 语言里,可以通过继承或接口来实现共性方法。在 JavaScript 里,通过 mixin 特性,一切变得更简单。augment 是动态语言 mixin 特性的体现,灵活运用,能让代码非常优雅简洁。

extend Object extend ( r, s, px, sx )

让函数对象 r 继承函数对象 s.

Parameters:
r <Function> receiver, 子类
s <Function> supplier, 父类
px <Object> extra prototype members, 需要添加/覆盖的原型成员。
sx <Object> extra static members, 需要添加/覆盖的静态成员。
Returns: Object
扩展后的子类 r

var S = KISSY;

function Bird(name) { this.name = name; }
Bird.prototype.fly = function() { alert(this.name + ' is flying now!'); };

function Chicken(name) {
    Chicken.superclass.constructor.call(this, name);
}
S.extend(Chicken, Bird);

new Chicken('Frank').fly();

extend 方法是 KISSY 里类继承的实现方式。书写 JavaScript 代码时,请忘记传统 OO 里的继承体系。还 JavaScript 本色,给代码一身轻松。

namespace Object namespace ( arguments/* String* */ )

创建命名空间。

Returns: Object
创建的最后一个对象。

var S = KISSY;

S.namespace('app', 'test'); // 创建 KISSY.app 和 KISSY.test 对象
S.namespace('app.Shop'); // 创建 KISSY.app.Shop 对象

namespace 方法提供了最基本的命名空间管理。

app Object app ( name, sx )

创建应用对象。

Parameters:
name <String> 应用的名称。
sx <Object> extra static members, 需要添加/覆盖的静态成员。
Returns: Object
创建的应用对象。

KISSY.app('FrontPage');
FrontPage.namespace('app'); // 创建 FrontPage.app 对象
FrontPage.add('slide', function(FP) {
    // module code
    // 注:FP 指向 FrontPage
});

app 方法为基于 KISSY 的应用提供了最基本的代码组织方式。通过 app 创建的应用对象,自动具有了 add 和 namespace 方法。

log KISSY log ( msg, cat, src )

输出调试信息。

Parameters:
msg <String> 调试信息。
cat <String> 类别,可以取 info, warn, error, dir, time 等 console 对象的方法名,默认为 log.
src <String> 调试代码所在的源信息。

只有在 debug 模式下,才会输出调试信息。debug 模式的说明请参考 Config

error void error ( msg )

抛出错误异常。

只有在 debug 模式下,才会抛出异常。debug 模式的说明请参考 Config

guid String guid ( pre )

返回全局唯一 id.