今年のアドベントカレンダーは、23ほどのjQuery拡張関数を連日ご紹介してまいりました。

おさらい

毎度お世話になっているjQueryで、毎回書いてしまうちょこざいな関数をつらつらとしたためて来ました。 実際の中身はjQueryの機能への依存度はさほど高くない（？）ので、少しいじれば別にjQueryと一緒に使わなくても良い物もあったりします。 強いて言えば元々そんなにjQueryは好きではありませんが、結局使うことが多いので仕方ないですね。

インデックス

23個まとめてリストにしておきます。目次のようなもの。

$.chainCase(str) :String

キャメルケースの文字列をチェインケース・スネークケースに変換する
jQuery依存度 : 無

$.classify(obj) :Function

クラスライクな関数を生成する
jQuery依存度 : 中

$.configify(obj) :Object

オブジェクトに options を設定・変更する config() メソッドを実装する
jQuery依存度 : 中

$.dig(path, obj) :Any

ドットシンタックスの文字列を渡すとそのオブジェクトを掘り起こして返す
jQuery依存度 : 無

$.escapeHTML(str) :String

HTML文字列をエスケープする
jQuery依存度 : 無

$.eventify(obj) :Object

オブジェクトにイベント管理のメソッド（on, off, trigger）を実装する
jQuery依存度 : 低-中

$.attributify(obj) :Object

オブジェクトに属性管理のメソッド .attr() を実装する
jQuery依存度 : 低

$.format(template, str, str…) :String

“%s%d” 形式のフォーマットに則って整形された文字列を返す
jQuery依存度 : 無

$.formatNumber(num) :String

数値を三桁ずつカンマで区切った文字列で返す
jQuery依存度 : 無

$.observe(callback) :Deferred

コールバック関数を渡してその返り値を監視する
jQuery依存度 : 無

$.parseQuery(str, asArray) :String

URLのサーチ文字列（”?key=value&key2=value2″ ）をパースする
jQuery依存度 : 低

$.parseURL(str) :Object

URL文字列をホスト名やサーチ文字列・ハッシュなどにパースする
jQuery依存度 : 無

$.random(start, end) :Any

範囲の間からランダムな数値を取得したり、リストの中からランダムに値を取得する
jQuery依存度 : 無

$.rebase(obj, pattern) :Object

オブジェクトに属しているメソッドをそのオブジェクトに bind する
jQuery依存度 : 低

$.render(template, data) :String|Function

単機能のテンプレート関数
jQuery依存度 : 低

$.scrollTo(dest, offset, options, selector) :void

ページあるいは要素の中身をアニメーションでスクロールする
jQuery依存度 : 高

$.fn.serializeObject() :Object

フォーム要素をシリアライズして、オブジェクトで返す
jQuery依存度 : 高

$.fn.extract(asArray) :Object|Array

非Form要素の内容をシリアライズする
jQuery依存度 : 高

$.series(callback, callback …) :Deferred

連鎖的に直列処理を実行する
jQuery依存度 : 高

$.fn.submitAsync(props) :Deferred

Form要素を非同期でsubmitする
jQuery依存度 : 高

$.times(count, callback) :void

n回処理を繰り返す
jQuery依存度 : 無

$.timing.*

User Timing API のラッパー
jQuery依存度 : 無

$.fn.transition(props, options) :jQueryObject

$.fn.animate() のようにCSS Transitionを実現する
jQuery依存度 : 高

リポジトリ

全て纏めた物をGithubのリポジトリにしてあります。ご自由にどうぞ。

jquery-tiny-extentions @ GitHub

それでは皆様、良い年末をお過ごしください。

$.fn.transition は、$.fn.animate の様にCSS Transitionを実現する関数です。

$.fn.transition(props, options)

CSS Transition によるアニメーションはJavaScriptによるアニメーションに比べてパフォーマンスが非常によく、綺麗です。 しかし一方で、非対応環境の為に .animate() を使わなければならない事が多いので、 両者で動作するように対応できる関数をしたためてみました。

使い方

// 要素を left: 100 に移動
$(".item").transition({
    left: 100
}, {
    duration: 300, // 所要時間 300ms
    delay: 100, // アニメーション開始までのディレイ 100ms
    easing: "linear" // イージング関数の指定
});

基本的な使い方は .animate() と概ね同じです。

• 第一引数 : アニメーションするスタイル
• 第二引数 : オプション

CSS Transition に対応していないレガシーな環境では $.fn.animate で代替しています。 イージング関数名として渡せるのは jQuery.easing の名前ではなく、 CSS Transition で定義されている名前です。（ease | linear | ease-in | ease-out | ease-in-out）

// 要素をアニメーション後、削除
$(".item").transition({
    opacity: 0,
    right: 500
}, {
    done: function(){
        $(this).remove();
    }
});

.animate() 同様に、オプションで done を渡して完了時の処理を実装できます。 .animate() にあるその他多数のオプションは使えません。

また、stop() とかはできません。とまりません。

コード

$.extend($.support, {
    cssTransition: ("transition" in document.createElement("i").style)
});

$.transition = function(props, options){
    var o, transition = [];

    o = $.extend({
        duration: 400,
        delay: 0,
        easing: "ease",
        done: $.noop
    }, options);

    if(! $.support.cssTransition){
        switch(o.easing){
            case "ease": o.easing = "swing";
            case "ease-in": o.easing = "easeInSine";
            case "ease-out": o.easing = "easeOutSine";
            case "ease-in-out": o.easing = "easeInOutSine";
            default: break;
        }
        o.easing = (o.easing in $.easing) ? o.easing : "swing";

        this.stop().delay(o.delay).animate(props, {
            duration: o.duration,
            easing: o.easing,
            done: o.done
        });

        return this;
    }

    $.each(props, function(key, value){
        transition.push(
            [
                key,
                o.duration + "ms",
                o.easing,
                o.delay + "ms"
            ].join(" ")
        );
    });
    transition = transition.join(",");

    this.each(function(){
        var el = $(this),
            done = (function(e){
                o.done.call(this, e);
                $(this).css("transition", "").off("transitionend", done);
            }).bind(this);

        el.css("transition", transition)
        .on("transitionend", done)
        .css(props);

        setTimeout(function(){
            el.trigger("transitionend");
        }, o.duration + 33);
    });

    return this;
};

ベンダープレフィックス無しの “transition” を持たない環境は、使えない物とみなしています。 （面倒だったのもありますが、必要性もあまり感じなかった為）

非対応環境ではイージング関数を jQuery.easing の名前に書き換えています。 といっても、デフォルトで実装されているのは “swing” と “linear” だけなので、 jQuery.easing プラグイン も含めて、近しい物を割り当てています。 こちらも一緒に使う事で表現は豊かになりますが、なければないで、そこらへんが全部 “swing” になるだけです。

完了時の処理に “transitionend” を利用していますが、 これは実際に値が変わってトランジションが発生していないと発火しない代物なので、 時間経過と共に無理やり発火させています。 「アニメーションしないアニメーション」の完了時に何かしたい事なんてないだろうと思いますが、念のため。

$.timing は、User Timing API のラッパーです。 わずかな機能だけですが、非対応環境に擬似的に対応してみました。

User Timing API とは

User Timing APIは、Webページ上のパフォーマンスを計測するためのインターフェースです。 その役割と使い方は下記URLのエントリーで解説されています。

• User Timing API: あなたの Web アプリをもっと理解するために – HTML5 Rocks

ものすごくざっくりと使い方を紹介すると、こんな感じ。

• mark() を使って任意のタイミングでタイムスタンプを「マーク」として記録
• measure() を使って、記録したマーク間の所要時間を計測
• タイムスタンプは1/1000ミリ秒という高精度で記録される

執筆時点でのメジャーどころの対応状況は IE10+ / Edge / Firefox / Chrome / Opera 40+ となっていて、 IE9以前やSafari（iOS含）は非対応です。

$.timing

使い方

// マークを記録
$.timing.mark("foo");
$.timing.mark("bar");

// マーク間の所要時間を記録
$.timing.measure("from_foo_to_bar", "foo", "bar");

// 名前からタイムスタンプを取得
$.timing.get("from_foo_to_bar"); // => number

// 記録したマークを全て取得
$.timing.marks(); // => object

// 記録したメジャーを全て取得
$.timing.measures(); // => object

• .mark(name) でそのタイミングのタイムスタンプを記録します
• .measure(name, start, end) で、開始マークから終了マークまでの所要時間を記録します
• .get(name) で名前からマーク・メジャーの時間を数値で取得します
• .marks() / .measures() で記録したマーク・メジャーを全てオブジェクトで取得

Polyfill とは呼べないモノ

$.timing はほんの一部の機能しか実装していません。 また、擬似的に再現してみたとはいえ1/1000ミリ秒単位で計測はちょっと出来無さそうで、 Polyfillと呼ぶにはあまりに片手落ちですね。

core-js あたりでPolyfillを書いているかも？と思いましたが、 中の人が「無理デス」 とおっしゃっています。

Thanks for proposal, but it can’t be polyfilled – only little part and with serious limitations.
https://github.com/zloirock/core-js/issues/130

コード

$.timing = {
    _supported: ("performance" in window) && ("timing" in window.performance),
    _data: {},
    _start: (new Date()).getTime(),

    mark: function(name){
        if(this._supported){
            window.performance.mark(name);
        } else {
            this._data[name] = {
                type: "mark",
                startTime: (new Date()).getTime() - this._start
            };
        }
    },

    marks: function(){
        return this.getEntries("mark", "startTime");
    },

    measure: function(name, start, end){
        if(this._supported){
            window.performance.measure(name, start, end);
        } else {
            this._data[name] = {
                type: "measure",
                duration: this.get(end) - this.get(start)
            };
        }
    },

    measures: function(){
        return this.getEntries("measure", "duration");
    },

    get: function(name){
        if(this._supported){
            var items = window.performance.getEntriesByName(name);
            return items.length ? items[0].startTime : void 0;
        }
        return (name in this._data) ? this._data[name].startTime : void 0;
    },

    getEntries: function(type, key){
        var data = {};
        if(this._supported){
            window.performance.getEntriesByType(type)
            .forEach(function(item){
                data[item.name] = item[key];
            });
        } else {
            $.each(this._data, function(name, item){
                if(item.type === type){
                    data[name] = item[key];
                }
            });
        }
        return data;
    }
};

$.times() は、n回処理を繰り返してくれる関数です。

$.times(count, callback)

使い方

var str = "";

$.times(10, function(index){
    str += index;
});

console.log(str); // => "0123456789"

第一引数に繰り返したい回数を整数で、 第二引数に実行したい関数を渡します。 関数には0からはじまるインデックスが渡されます。

コード

$.times = function(count, callback){
    var i = count;
    while(i--){
        callback(count - i - 1);
    }
};

正直細かすぎたかなって思ってます。

実際にプロダクトのコードに使われる事はあまりなく、デモデータの生成やテスト等で使ったりはします。

$.fn.submitAsync() は、form要素を非同期でsubmitするための関数です。

$.fn.submitAsync(options)

使い方

<form action="/" method="post" id="demo-form"> ... </form>

<script>

$("#demo-form").submitAsync()
.then(function(){
    console.log("--送信完了--");
});

</script>

返り値は $.ajax() なので、then/done 等で結果を受け取ることができます。 引数には $.ajax() のオプションを渡すことができます。

$("#demo-form").submitAsync({
    url: "/api/foo",
    dataType: "jsonp"
})
.then(function(){ ... });

送信先のURLは通常 action 属性が使用されますが、引数のオプションで上書きする事もできます。 リクエストメソッド（”type”）も同様。

コード

$.fn.submitAsync = function(options){
    var props = $.extend({
        url: this.prop("action"),
        type: this.prop("method"),
        data: this.serializeObject()
    }, options);
    return $.ajax(props);
};

Form の属性を読んで $.ajax() するだけの簡単なお仕事ですね。なくてもまったく困りません。 尚、内部で先に紹介した $.fn.serializeObject() を使用しています。

$.series() は、連鎖的に直列処理を実行していく関数です。

$.series(callback, callback, …)

使い方

// 引数で渡した関数を順番に呼んでいきます
$.series(
    function(){
        console.log("Process: 1");
        // 数値（ミリ秒）を返すとその時間分次の処理を遅延させます
        return 1000;
    },
    function(){
        console.log("Process: 2");
        // 何も返さない（undefined）場合は `return 1;` と同じ
    },
    function(){
        // Deferredオブジェクトを返すと処理完了時に次の処理に移行します
        return $.ajax({url: "/api"}).done(function(){
            console.log("Process: 3");
        });
    },
    function(){
        // false を返すとそこで処理を中断して reject します
        return false;
    }
)
.then(
    function(){
        console.log("--処理完了--");
    },
    function(){
        console.log("--途中で処理が中断されました--");
    }
);

渡した関数が返す値によって、次の処理までの挙動が変わります。

• 数値 : 数値（ミリ秒）待機してから次の処理へ
• Deferred : resolveされてから次の処理へ
• false : 一連の処理を中断してrejectする
• undefined : 何も返さない場合は 1 を返した場合と同じ

$.series() は Deferred を返すので、完了・失敗を then() 等で受け取る事ができます。

コード

$.series = function(){
    var df = $.Deferred(),
        args = arguments,
        i = -1,
        timer = null,
        run;

    run = function(){
        var r;

        clearTimeout(timer);
        i += 1;
        if(i >= args.length){
            return df.resolve();
        }
        r = args[i]();
        if(false === r){
            df.reject();
        }
        r = (r === void 0) ? 1 : r;
        switch($.type(r)){
            case "number": timer = setTimeout(run, r); break;
            case "object":
                if($.isFunction(r.then)){
                    r.then(run ,function(){
                        df.reject();
                    });
                }
                break;
            default: break;
        }
    }

    run();

    return df;
};

Cに必要なAとBをやって、Dに必要なCをやってからDやって…というような感じに連鎖的に直列処理したい時や、 タイムラインで組んだアニメーション等が作れそうですね。

普通に Deferred 等で繋いでいっても良いんですが、コードが見づらくなってしまうので、 気持ちよく書きたいがためにうまれた関数です。

$.fn.extract() は、非Form要素の内容をシリアライズする関数です。

$.fn.extract(asArray)

使い方

<div id="demo">
    <input type="text" name="name" value="john">
    <input type="text" name="age" value="23">
</div>

<script>

$("#demo").extract();
/* => {
    name: "john",
    age: 23
} */

// 引数にtrueを渡すと配列で返します
$("#demo").extract(true);
/* => [
    { key: "name", value: "john" },
    { key: "age", value: "23" }
] */

</script>

基本的な挙動は先に紹介した $.fn.serializeObject と同じです。 オブジェクトではなく配列で受け取りたい場合は引数に true を渡します。

ちなみに、$.fn.serialize() や $.fn.serializeArray() は、非Form要素で使用しても空の文字列・配列を返します。 （後述にもありますが、それが正しいと思います）

コード

$.fn.extract = function(asArray){
    var list = [], data = {};
    this.find("input[name], select[name], textarea[name]").each(function(){
        var name = this.name;
        if(["radio", "checkbox"].indexOf(this.type) >= 0){
            return ! this.checked ? null : list.push({
                name: name,
                value: this.value
            });
        }
        if(this.nodeName === "SELECT"){
            return $(this).find("option:selected").each(function(){
                list.push({
                    name: name,
                    value: this.value
                });
            });
        }
        list.push({
            name: name,
            value: this.value
        });
    });
    if(asArray){
        return list;
    }
    list.forEach(function(item){
        if(data[item.name] !== void 0){
            if($.type(data[item.name]) !== "array"){
                data[item.name] = [data[item.name]];
            }
            data[item.name].push(item.value);
            return;
        }
        data[item.name] = item.value;
    });
    return data;
};

オブジェクトで返すのをデフォルトとしている理由は、 わたし自身が基本的にオブジェクトで受け取りたいと思っているからです。

存在意義

なお、この関数の存在意義はあまりありません。 form でマークアップすれば済む話ですし、そうすべきでしょう。 どうしてもレイアウトの都合で form の外に input を置かなければいけない場合は、 HTML5の form 属性で親となる form を指定してやれば対応可能です。

<form action="/" id="demo-form"></form>
<input type="text" name="name" value="john" form="demo-form">

<script>

$("#demo-form").serialize(); // => "name=john"

</script>

こうすれば、$.fn.serialize/serializeArray() でもシリアライズする事ができ、仕様にも則っていますね。

$.fn.serializeObject() は、フォーム要素をシリアライズして、オブジェクトで返す関数です。 jQueryには文字列で返す $.fn.serialize() や、 配列で返す $.fn.serializeArray() がありますが、そのオブジェクト版です。

$.fn.serializeObject()

使い方

<form action="/" id="demo-form">
    <input type="text" name="name" value="John">
    <input type="text" name="age" value="23">
    <input type="radio" name="gender" value="male" checked>
    <input type="radio" name="gender" value="female">
</form>

<script>

$("#demo-form").serializeObject();
/* => {
    name: "John",
    age: 23,
    gender: "male"
} */

</script>

複数選択された項目は、値が配列になります。

<form action="/" id="demo-form">
    <input type="checkbox" name="color" value="red" checked>
    <input type="checkbox" name="color" value="green">
    <input type="checkbox" name="color" value="blue" checked>
</form>

<script>

$("#demo-form").serializeObject();
/* => {
    color: ["red", "blue"]
} */

</script>

コード

$.fn.serializeObject = function(){
    var vars = {};
    this.serializeArray().forEach(function(item){
        if(item.name in vars){
            if(! $.isArray(vars[item.name])){
                vars[item.name] = [vars[item.name]];
            }
            vars[item.name].push(item.value);
            return;
        }
        vars[item.name] = item.value;
    });
    return vars;
};

$.fn.serializeArray() が返す配列を読んでオブジェクトに変えているだけです。

Formの内容を非同期でPOSTしたい時などに使えるかもしれませんが、それはまた別の関数の話。

$.scrollTo() は、ページあるいは要素の中身をアニメーションでスクロールしてくれる、よくある関数です。

$.scrollTo(dest, offset, options, selector)

使い方

// ページの先頭に戻る
$.scrollTo(0);

// "#destination" 要素の40px上に1秒かけてスクロールする
$.scrollTo("#destination", -40, {
    duration: 1000
});

// "#section-01" の位置まで移動して、完了時に location.hash を書き換える
$.scrollTo("#section-01", 0, {
    done: function(){
        location.hash = "#section-01";
    }
});

// #scrollArea の中身を、#destPosition の位置までスクロールする
$.scrollTo("#destPosition", 0, null, "#scrollArea");

• 到達点の指定（第一引数）は、数値かセレクタで渡します。
• 非数値である場合は、セレクタとみなしてその要素の位置までスクロールします。
• options はjQueryのanimate関数にそのまま渡されます
• 第四引数は、スクロールをする要素のセレクタです。（デフォルトは “html,body”）

なお、縦スクロールの事しか考えていない点はご容赦ください。

注意したい点

ページ内にある要素（”html,body” ではない要素）のスクロールをおこなう場合は、 その要素の position は “static” 以外でないといけない点に注意が必要です。 コンテキストを生成しないと親のコンテキストから位置を計算してしまうので、到達点の計算がズレズレになってしまいますね。 （到達点を数値で指定する場合はその限りではありません）

コード

$.scrollTo = function(dest, offset, options, selector){
    if($.type(dest) !== "number"){
        dest = $(dest)[selector === void 0 ? "offset" : "position"]().top;
    }
    offset = offset || 0;
    options = options || {};
    selector = selector || "html,body";
    $(selector).animate({
        scrollTop: dest + offset
    }, options);
};

$.render() は単機能のテンプレート関数です。 エンジンと呼称するにはおこがましいくらい単機能です。

$.render(template, data)

使い方

// template と data を渡すと即時展開
$.render("わたしは{{name}}、{{age}}歳だ！", {
    name: "ジョン",
    age: 23
});
// => "わたしはジョン、23歳だ！"

// template のみの場合は関数を返す
var render = $.render("わたしは{{name}}、{{age}}歳だ！");
render({name: "ジョン", age: 23}); // => "わたしはジョン、23歳だ！"

// キー名はドットシンタックスが使える
$.render("{{user.name}}, {{user.age}}", {
    user: {
        name: "john",
        age: 23
    }
});
// => "john, 23"

// {{key}} はHTMLをエスケープする
// {{{key}}} はHTMLをエスケープしない
$.render("{{content}}, {{{content}}}", {
    content: "<script>"
});
// => "&lt;script&gt;, <script>"

• テンプレートとデータを渡してキーを基に差し替えて返します。
• data を渡さないことで、_.templateのようにレンダー関数を返す事もできます。
• キー名にはドットシンタックスが使えます。（先に紹介した $.dig を内部で使用）
• “{{key}}” はHTMLエスケープします。（先に紹介した $.escapeHTML を内部で使用）
• “{{{key}}}” はエスケープせずにそのまま出力します。

テンプレートの体裁は Mustache っぽいですが、条件分岐やループ処理などは搭載していません。 本当にテンプレートに値をはめ込むだけの機能しかありません。 敢えて言わせていただくと、「MustacheなりHandlebarsをつかっておけ」で済む話ですね。

• {{ mustache }}
• Handlebars.js: Minimal Templating on Steroids

コード

$.render = function(template, data){
    var func = function(vars){
        return template.replace(/([\{]{2,3})([\w\.\-]+)([\}]{2,3})/g, function(a,b,c){
            var value = $.dig(c, vars) || "";
            value = (b.length > 2) ? value : $.escapeHTML(value);
            return value;
        });
    };
    return data === void 0 ? func : func(data);
}

6年前に書いた以下のエントリーの物から余計な物を削って若干改修・簡略化した関数です。

• シンプルなjQueryテンプレートプラグインを書いてみる – Mach3.laBlog

HTMLのテンプレートとして使うには力不足が否めない関数ですが、 URL文字列を組み立てたりするプレースホルダとしてなら、コード量少ないですし使い道があるかもしれませんね。 ないかもしれませんね。