loader

loader 是脚本加载器的实现, 弥补了 javascript 语言机制的不足, 提供类似其他语言原生的模块化机制。KISSY loader 实现了 KISSY 模块规范

add() <static>

add(name,fn[,config]) ⇒ void

parameters

KISSY 添加模块/逻辑片段的函数,config为配置对象,包括config.requires,给出当前模块的依赖模块。模块返回一个对象,通过引用它的时候来调用到。

当模块名称 name 为包内模块时, 则requires的模块名称可使用相对路径来引用包内其他模块,比如package/a来引用package/a.js,也可以用./a来引用package/a.js

// package/a.js
KISSY.add('package/a',function(S){
    return ObjA;
},{
    // 当前逻辑依赖一个包内的文件b,一个全局模块node,一个同目录下的css文件
    requires:['package/b','node','./mod.css']
});

使用该模块

KISSY.use('package/a',function(S,ObjA){
    // 可引用ObjA
});

本地开发时,模块名称可留空,不过在部署阶段需要使用Kissy Mobule Compiler 生成模块依赖关系表,或者直接生成合并后的文件。

// package/a.js
KISSY.add(function(S){
    return ObjA;
},{
    requires:['./b','./mod.css']
});

add()中的函数回调可以调用它依赖的模块所返回的对象

// package/a.js
KISSY.add(function(S,Node,ObjB){
    // 使用 Node 和 ObjB
},{
    requires:['node','./b']
});

当模块名称 name 为包内模块< 参见 下文包配置 >时, 则requires的模块名称可使用相对路径 refer 包内其他模块

// tc/mods/mod1 依赖于 tc/mods/mod2
KISSY.add("tc/mods/mod1",function(){
    // Your code...
},{requires:['./mod2']});

Changed in version 1.3+: KISSY.add 表示模块定义, fn 并不会执行, 只有在 use 时才执行, 懒加载原则.

add(factory)

也可以选择 commonjs 的模块书写方式,这种写法仅限于一个 JS 文件包含一个add()(这时文件名可以用作模块名),例如

// a/b.js
KISSY.add(function(S,require,exports,module){
    var c = require('a/c');
    return c; // 或者 module.exports=c;
});

config() <static>

parameters

全局配置函数,用以读写全局配置项,包括注册包、预注册模块名称,模块文件的引用规则等等。其中配置项包括这些字段,modulespackages是JSON对象:

modules

以单个模块为键,单个模块配置对象为值的键值对对象。单个模块配置对象包括:

packages

以单个包名为键,单个包配置对象为值的键值对对象。单个包配置对象包括:

Example

配置项可以在脚本引用时带入,比如:

<script src='seed.js' data-config='{combine:true}'></script>

完整的配置样例:

KISSY.config({
    // 开启自动 combo 模式
    combine:true,
    // kissy 库内置模块的时间戳
    tag:'2012',
    // kissy 的基准路径
    base:'http://x.com/a',
    packages:{
        x:{
            // x 包的基准路径
            base:'http://x.com/biz/',
            // x 包的时间戳
            tag:'x',
            // 开启 x 包 debug 模式
            debug:true
        },
        y:{
           // y 包的基准路径
           base:'http://x.com/biz/',
           // y 包不开启自动 combo
           combine:false
           // 不配置 tag,则取 kissy 内置模块的时间戳
        }
    },
    modules:{
        "x/b1":{
            // "x/b1" 模块的依赖信息
            requires:["x/b2","x/b3"]
        },
        "y/b2":{
            // y/b2 模块单独的时间戳
            tag:'234'
        }
    }
});

packages 范例: 包配置

KISSY.config({
    packages:{
        // 包名
        "tc": {
            tag:"20110323", // 动态加载包内的模块js文件时,
                            // 自动加上 ?t=20110323, 用于文件更新
            base:"../", // 包对应路径, 相对路径指相对于当前页面路径
            charset:"gbk" // 包里模块文件编码格式
        }
    }
});

当要在包内添加模块时, 必须遵守一些约定:

KISSY.add("tc/mods/mod1",function(){
    // 模块代码
});

模块名也可以省略, 不过部署阶段需要使用 KISSY Module Compiler 静态打包。

getScript() <static>

动态加载目标地址的资源文件,config 为JSON对象,返回值为HTMLElement,为创建的link或者script节点,参数如下:

parameters

return

HTMLElement 返回创建的link或者script节点

Example

简写写法getScript(url,success,charset)中,success为回调函数,charset为编码类型。相当于:

 KISSY.getScript(url , { 
     success : success , 
     charset : charset 
});

use() <static>

use (modNames[,callback]) ⇒ void

载入并运行模块,和add一起使用,详细用法参照KISSY 模块规范callback类型可以是function也可以是object。参数说明:

parameters

Example

callback为函数时

KISSY.use("depMod1,depMod2",function(S,DepMod1,DepMod2){
    // Your code...
});

callback为对象时

KISSY.use("depMod1,depMod2",{
    success:function(S,DepMod1,DepMod2){
        // Your code
    },
    error:function(){
        var errorMods = KISSY.makeArray(arguments);
    }
});

如果使用经过配置的包内的模块, 则这些包内模块不需要事先注册, 直接 use 即可, 如果模块名以 / 结尾, 则自动加后缀 index , 例如 use("mods/m1/") 相当于 use("mods/m1/index") , 即自动加载 m1 目录下的 index.js

importStyle() <static>

importStyle (modNames) => void

阻塞加载 css 模块或 js 模块依赖的 css 模块, 和 KISSY.add 中的 require 配置一起使用.

parameter

modNames (String|String[]) – 以,分割的 js 模块或 css 模块名称集合字符串,例如 KISSY.use("mod1,mod2/xx.css");

require

如果requires的模块过多,回调参数需要和模块列表一一对应,有没有更简单的办法?

经常看到这种代码:

// requires 的模块太多,一不小心就和 function() 里的回调不对应了
KISSY.add(function(S,A,B,C,D,E,F,G){
    // Your code...
},{requires:['a','b','c','d','e','f','g']});

有没有办法不用去肉眼找模块和变量的对应关系?有方法,KISSY 1.4.1 提供了require

KISSY.add(function(S, require){
    var A = require('a');
    var B = require('b');
    var C = require('c');
    // Your code...
});