# 组件

## Kico Style 的扩展组件，可提升网页的交互体验

> 📢：作者已经逐渐转移至 Vue/React 阵营，本框架的原生 JS 组件及其样式则不再作为优先维护对象，敬请谅解～ 但基础的 CSS 框架依然会持续更新！

# 元素创建

快速创建虚拟 DOM 元素。

参数 | 可选值 | 说明
--- | --- | ---
obj `必须` | 字符串 | 新建元素采用的标签名
prop { id } | 字符串 | 新建元素的 ID（id）
prop { href } | 字符串 | 新建外联元素的地址（href）
prop { class } | 字符串 | 新建元素的类名（class）
prop { text } | 字符串 | 新建元素的内容（innerText）
prop { html } | 字符串 | 新建元素的 HTML 内容（innerHTML）
prop { child } | DOM 对象 | 数组 | 新建元素添加的子元素，支持单条或是以数组形式添加多条
prop { attr } | 对象 | 数组 | 新建元素添加的属性，支持单条或是以数组形式添加多条

示例：创建一个 `p` 标签的对象

    ks.create("p");

    // 返回 <p></p>

示例：创建一个 `div` 标签的对象，并给予 `test` 类名

    ks.create("div", {class: "test"});

    // 返回 <div class="test"></div>

示例：创建一个 `div` 标签的对象，并给予 `ks-thumb` 和 `ks-original` 属性用于设置懒加载的图片灯箱

    var item = ks.create("div", {
        class: "gallery-item",
        attr: [
            {name: "ks-thumb", value: `/static/saratoga-thumb.jpg`},
            {name: "ks-original", value: `/static/saratoga.jpg`}
        ]
    });

    // 返回 <div class="gallery-item" ks-thumb="static/saratoga-thumb.jpg" ks-original="static/saratoga.jpg"></div>

    // 设置图片灯箱与懒加载
    ks.image(".gallery-item");
    ks.lazy(".gallery-item", true);

示例：创建一个 `div` 标签的对象，在给予 `hello` 类名的同时，写入“这是一个 DIV”的内容

    ks.create("div", {
        class: "hello",
        text: "这是一个 DIV"
    });

    // 返回 <div class="hello">这是一个 DIV</div>

示例：添加一个有多重子元素的 `div` 对象

    ks.create("div", {
        class: "first",
        text: "这是第一层 DIV",
        child: ks.create("div", {
            class: "second",
            text: "这是第二层 DIV",
            child: ks.create("div", {
                class: "third",
                text: "这是第三层 DIV"
            })
        })
    });

    // 返回
    // <div class="first">这是第一层 DIV
    //     <div class="second">这是第二层 DIV
    //         <div class="third">这是第三层 DIV</div>
    //     </div>
    // </div>

# 元素选择器

快速选择单个/多个符合条件的元素，像编写 CSS 选择器一样简单。

示例：选择标签为 `header` 的第一个对象

    ks.select("header");

示例：选择类名为 `post-content` 的所有图片

    ks.selectAll(".post-content img");

> PS：ks() 返回的内容和 ks.selectAll() 是相同的，所以上面的代码也可以这样写：

    ks(".post-content img");

# 批量运行

快速设置多个数组或是 DOM 元素。

参数 | 可选值 | 说明
--- | --- | ---
obj `必须` | 数组 | NodeList | 被执行操作的对象
fn `必须` | 函数 | 对 obj 执行的操作
fn(i) | 被执行的其中一个对象 | 当前执行的 obj 对象
fn(j) | 被执行的对象索引值 | 当前执行的 obj 对象索引值
fn(k) | 被执行的对象整体 | 也就是 obj 本身

示例：批量选择 `h1` 元素，并设置其字体样式

    ks("h1").each(function (i) {
        i.style.color = "green";
        i.style.fontWeight = "bold";
    })

# 消息弹框

使用消息弹框，比 `alert` 更加友好，提升用户体验。

静态的消息弹框样式
静态的消息弹框样式
静态的消息弹框样式
静态的消息弹框样式
静态的消息弹框样式
静态的消息弹框样式

参数 | 可选值 | 说明
--- | --- | ---
content `必须` | 字符串 | 要输出给弹框的内容
attr | `time` `color` `overlay` | 子属性，配置时间、颜色和遮罩
attr { time } | 整数，单位为毫秒 | 指定弹框显示之后的移除时间，默认为手动关闭
attr { color } | `red` `yellow` `blue` `green` | 指定弹框颜色，默认为 `null`

示例：一个在 1.5 秒后自动清除的弹窗

    ks.notice("这是一个有时间的弹窗测试", {
        time: 1500
    });

示例：没有时长的蓝色弹窗

    ks.notice("这是一个蓝色的可关闭弹窗", {
        color: "blue"
    });

# 图片灯箱

使用图片灯箱可以让页面的图片放大展示。

通过增加 `ks.original` 字段，还可以实现缩略图点击变成原图的效果！

使用 `div` 也可以增加灯箱，只是必须增加 `ks.original` 字段才可以展示出来。

示例：选中所有 `article` 标签里面的图片

    ks.image("article img");

示例：选中包含原图字段的可触发 `div`

    ks.image(".original");

> PS：如果在一个页面里反复调用本函数，将等同于 重置，此前执行的对象将失效！

# 图片懒加载

使用图片懒加载可以提升浏览体验，减小服务器并发压力。

通过给 `img` 元素增加 `ks.original` 字段，并运行即可实现懒加载。

如果想让用户认为这是一个正在加载的图片，建议你将图片的 `src` 设置成一张以示加载的图片。

    <img src="示例加载的图片地址" ks-original="懒加载完成后的图片地址"/>

如果想使得一个块元素的 `background` 背景图片实现懒加载，依旧需要只需要增加 `ks.original` 字段，并将额外一个参数设置为 `true` 字段才可以实现懒加载。

示例：选中所有 `img` 图片，并开启懒加载

    ks.lazy("img");

示例：选中所有类名为 `original` 的块元素，并对其实现背景形式的懒加载。

    ks.lazy(".original", true);

# 快速 AJAX

和 JQuery 类似的一个简易 AJAX 功能，在不刷新网页的情况下快速更新页面内容。

示例：一个带了请求头的 GET 请求

    ks.ajax({
        method: "GET",
        data: {
            text: "Yeah!"
        },
        header: [
            ["sended", "Dreamer-Paul"]
        ],
        url: 手动指定 URL,
        success: function (req){
            console.log("成功了");
            console.log(req); // 返回的 XHR 对象
        },
        failed: function (req){
            console.log("失败了");
            console.log(req); // 返回的 XHR 对象
        }
    });

示例：一个 POST 请求

    ks.ajax({
        method: "POST",
        data: {
            id: 5,
            text: "Yeah!"
        },
        url: "post",
        success: function (req){
            console.log("成功了");
            console.log(req); // 返回的 XHR 对象
        },
        failed: function (req){
            console.log("失败了");
            console.log(req); // 返回的 XHR 对象
        }
    });

# 平滑滚动 Beta

通过添加了页面锚链接的 `a` 元素，平滑滚动页面到对应的元素，可添加偏移值。

示例：选中 `.sub-sidebar` 元素里面的所有 `a` 链接，在点击它们的时候，页面将会平滑滚动到其指定的对应内容。同时保留 `100px` 的偏移间距。

    ks.scrollTo(".sub-sidebar a", 100);

或者是

    ks(".sub-sidebar a").scrollTo(100);