jQuery Migrate plugin の使い方と警告文の自分なりのまとめ

jQuery Migrate plugin の README と warnings を読んで、適当にまとめました。 誤訳、情報が古い、使ってない等々のリスクがありますので 読まれる際はご注意下さい。 (※ページをそのまま訳したわけではないと、思いたい)

箇条書きにすると以下のような感じ:

jQuery Migrate plugin について

jQuery Migrate plugin は jQuery 1.9 以降に移行した際に コードの問題となる箇所を指摘したり、1.9 で変更された振る舞いを 1.9 より前のものに復元したりするなど、 jQuery 1.9 以降への移行を助けるためのツールです。

移行の際の問題を特定する用途で使用する場合は jQuery 1.6.4 から使用できます。一方、削除された機能を復元する場合は 1.9 以降を使う必要があります。

基本的にブラウザのコンソールを使用するので、IE 7 などの コンソールがサポートされてないブラウザの場合は、 このプラグインを読み込む前に Firebug Lite 等を 読み込ませてコンソールが使えるようにします。

リストに戻る

開発版と製品版の違い

jQuery Migrate plugin には2つのバージョンがあります。 開発版(Development version)と製品版(Production version)です。

開発版はそのまま使用するとブラウザのコンソールに警告を 表示します。コードは圧縮されていません。 移行の際コードを検証するときは普通こちらを使うと思います。

一方、製品版はそのままではコンソールに警告を表示せず、 コードは圧縮されています(ソースマップに対応しています)。 このプラグインを使わなくてもいいぐらいに コードを修正できない場合はこちらを使うといいと思います。

リストに戻る

使い方

jQuery を読み込んだ後に読み込むようにします。

<script src="http://code.jquery.com/jquery-1.9.1.js"></script>
<script src="http://code.jquery.com/jquery-migrate-1.1.0.js"></script>

これで、削除された機能や変更された振る舞いがある程度 復元されます。 その後、deprecated な機能や削除された機能、 振る舞いが変更された機能を使おうとすると、 コンソールに警告が表示されます。 その機能を使用した地点のスタックトレースも 表示されます。 警告文はコンソールだけでなく、 jQuery.migrateWarningsという配列にも 格納されます。 この情報を元に、警告が出なくなるまで コードを修正していくことになります。

警告が表示されなくなったら、jQuery Migrate plugin を外します。 それでもまだ問題がある場合は、もう地道にコードを調べていくしか ありません。多分。 jQuery Core 1.9 Upgrade Guide の「Changes of Note in jQuery 1.9」で更新時に問題が 発生しそうな挙動変更が羅列されていますので参考にすると いいと思います。(※自分がまとめたのは コチラ 。)

リストに戻る

jQuery Migrate plugin のプロパティ

jQuery Migrate plugin では以下のプロパティやメソッドが使えます。

jQuery.migrateWarnings
配列。そのページで現在までに出力した警告メッセージが 出力した順に格納されます。 同じような状況が複数回起こっても配列のメッセージは 重複しません
jQuery.migrateMute
trueに設定するとコンソールに警告が 出力されなくなります。 jQuery.migrateWarningsには格納されます
jQuery.migrateTrace
警告は欲しいけど コンソールにスタックトレースを 表示したくない場合にはこのプロパティをfalseにします
jQuery.migrateReset()
jQuery.migrateWarningsを空にします。 今まで発したメッセージも忘れるので、既に発した警告も その後発生すれば配列に格納されるようになります。 (※.attr("checked(or selected)")に関する メッセージを忘れないようです。不具合?)
リストに戻る

警告メッセージの種類

追加・変更されるかもしれませんので、最新情報は Github のページ などで確認下さい。

警告メッセージは全て"JQMIGRATE"で始まります。

JQMIGRATE: Logging is active

これは警告ではなくて、このプラグインが最初に読まれた時に コンソールに出力されるメッセージです。 製品版や、プラグインを読み込む前に jQuery.migrateMutetrueに 設定すれば出力されません。

リストに戻る

JQMIGRATE: jQuery.attrFn is deprecated

ドキュメント化されてなかったのですが、jQuery 1.8 より前に 存在していました。 古い jQuery UI や jQuery Mobile 、その他プラグインなどが 使用しているそうです。

修正するためには、jQuery UI や jQuery Mobile に関しては 最新版(jQuery UI は 1.8.21 以降、jQuery Mobile は 1.2.1 以降) を使うようにすればjQuery.attrFnを 使わなくなるそうです。 他のプラグインについては新しいバージョンが jQuery.attrFnを使ってなければ更新し、 jQuery.attrFnを使っていれば そのプラグインの作者に連絡する、と書いてありました。

リストに戻る

JQMIGRATE: Can't change the 'type' of an input or button in IE 6/7/8

DOM ツリーに接続されている input, button 要素の type 属性を 設定しようとすると警告されます。 IE 6,7,8 は input 要素や button 要素の type 属性を 変更しようとすると、エラーを throw します。
1.9 より前は、全てのブラウザの足並みをそろえるため jQuery 側でエラーを throw していて、 1.9 以降はそれを止めた結果、 古いIE だけがエラーを throw するようになりました。

古いIE との互換性を保ちたい場合は、input 要素の type 属性を 変更しないようにします。変更したい場合は 新しく要素を作成して交換するようにします。

リストに戻る

JQMIGRATE: jQuery is not compatible with Quirks Mode

ページが互換モードだと警告されます。 HTML 文書の最初の行に<!doctype ...>が 無いときや、在ってもその doctype が不正な時に ブラウザは Quirks mode (互換モード)になります。 jQuery は Quirks mode でのサポートを止めていて、 テストもしてないそうです。

この警告を無くすには Standards mode (標準モード)にします。 文書に正しい doctype を置けば Standards mode でレンダリングされるようになります。 <!doctype html>とするのが 簡単で HTML 5 でいいと推奨されています。

リストに戻る

JQMIGRATE: jQuery.parseJSON requires a valid JSON string

$.parseJSON()null以外の falseになるような値を渡すと警告されます。
jQuery 1.9.0 より前、$.parseJSON()は 幾つかの JSON として無効な文字列(例えば空文字列)を許容して エラーを throw しないでnullを返していました。 このため$.parseJSON()JSON.parse()で挙動が異なっていました。
1.9.0 ではそれが修正されて、 空文字列のような値を$.parseJSON()は 無効とみなしエラーを throw するようになりました。

もし以前のように""falseなどの値でも エラーを throw させずnullとして扱いたい場合は、 $.parseJSON()に渡す前に値を 以下のように場合分けします。

var json = $.parseJSON(jsonString || "null");
// より 1.8.3 に近づけたいなら
// var json = $.parseJSON(
//   (!jsonString || typeof jsonString !== "string")? "null": jsonString );

もし$.parseJSON()を使ってないのに このメッセージが出ている場合は、 AJAX を使ってサーバから空文字列を返されていることが 考えられます。 サーバが無効な JSON 文字列を返すのを修正できない場合、 レスポンスを一旦テキストとして取得してから変換したりします。

// 掲載されていた例
$.ajax({
    url: "...",
    dataType: "text",
    success: function( text ) {
        var json = text? $.parseJSON(text) : null;
        ...
    }
});
リストに戻る

JQMIGRATE: jQuery.browser is deprecated

jQuery.browserは 1.9 で削除されました。 代わりに Modernizr などで機能特定を使いましょう。 それでもブラウザを判別したい場合は navigator.userAgentを直接覗いて判別します。

リストに戻る

JQMIGRATE: jQuery.sub() is deprecated

jQuery.sub()は 1.9 で削除されました。 jQuery.sub()を使っている場合は、 jQuery.sub()に依存しているコードを書き直す、 jQuery Migrate plugin の製品(圧縮)版を使う、 jQuery Migrate plugin のソースからjQuery.sub() の部分を抜き出して使う、などの選択肢があります。

リストに戻る

JQMIGRATE: 'hover' pseudo-event is deprecated, use 'mouseenter mouseleave'

擬似イベント"hover"は 1.9 で削除されました。 .hover()ではないので注意して下さい。

"hover""mouseenter mouseleave"の エイリアスなので、.on(), .bind(), .delegate()などで使用している "hover""mouseenter mouseleave"に 書き換えればいいそうです。

リストに戻る

JQMIGRATE: jQuery.fn.error() is deprecated

$.error()と混乱することもあって $().error()は 1.9 で削除されました。 代わりに$().on("error", fn)のように .on()で書き換えます。

リストに戻る

JQMIGRATE: jQuery.fn.toggle(handler, handler...) is deprecated

要素の表示・非表示を切り替える用法ではなくて、 クリックするたび一つずつ登録したハンドラを実行する方の用法が 1.9 で削除されました。

この警告を出さないようにするには、 .toggle()のこの用法に依存しているコードを書き直す、 jQuery Migrate plugin の製品(圧縮)版を使う、 jQuery Migrate plugin のソースから.toggle() の部分を抜き出して使う、などの選択肢があります。

リストに戻る

JQMIGRATE: jQuery.fn.live() is deprecated; jQuery.fn.die() is deprecated

.live().die()は 1.9 rc1 で削除されました。 .on(), .off()などで書き換えましょう。 API ドキュメントの .live() のページ で書き換えの方法などが書かれています。

// .live() のページに掲載されていた例
$("a.offsite").live("click", function(){ alert("Goodbye!"); }); // jQuery 1.3+
$(document).delegate("a.offsite", "click", function(){ alert("Goodbye!"); }); // jQuery 1.4.3+
$(document).on("click", "a.offsite", function(){ alert("Goodbye!"); }); // jQuery 1.7+

※自分のブログだと 1.7 の変更箇所のまとめ で書き換え例がありました。

リストに戻る

JQMIGRATE: AJAX events should be attached to document

document 要素以外に AJAX イベントハンドラを登録しようとすると 警告されます。
1.9 から、グローバルな AJAX イベント(ajaxStart, ajaxStop, ajaxSend, ajaxComplete, ajaxError, ajaxSuccess)は document 要素上でのみトリガーされます。 警告を消すには、AJAX イベントのハンドラを document に 登録するようにコードを変えます。

// 掲載されていた例
$("#status").ajaxStart(function(){ $(this).text("Ajax started"); });
//  ↓
$(document).ajaxStart(function(){ $("#status").text("Ajax started"); });
リストに戻る

JQMIGRATE: Global events are undocumented and deprecated

文書化されているグローバルイベントは上述した AJAX イベントだけで、 1.9 で document 上でのみトリガーされるようになりました。 他のグローバルにトリガーされるイベントは文書化されておらず、 サポートも Migrate plugin で復元もされません。 警告を消すには グローバルイベントを使用しないようにコードを変更します。

リストに戻る

JQMIGRATE: jQuery.event.handle is undocumented and deprecated

jQuery.event.handleは ドキュメント化されてなく、 そして 1.7 で deprecated になり、1.9 で削除されました。 代わりに.trigger()のような、 ドキュメント化されている API を使うようにしましょう。

リストに戻る

JQMIGRATE: jQuery.fn.attr('value') no longer gets properties

button, input, option 以外の要素で $().attr("value")を使うと警告されるようです。
1.9 より前、$().attr("value")は value 属性ではなく value プロパティを取得していました。 そのため value 属性を参照するセレクタと矛盾した挙動を 行っていたそうです。 1.9 では属性の値を取得するようになりました。

警告を消すには、フォーム部品には$().val()を、 他の要素には$().prop("value")を、 現在値を取得するのに使うようにします。そして、 input や option 要素にセレクタを使ってアクセスするときは、 属性セレクタ([value=…])をなるべく 使わないようにします。

リストに戻る

JQMIGRATE: jQuery.fn.attr('value', val) no longer sets properties

button, input, option 以外の要素で $().attr("value", val)を使うと警告されるようです。
1.9 より前、$().attr("value", val)は value 属性ではなく value プロパティを設定していました。 1.9 では属性の値を設定するようになりました。

警告を消すには、フォーム部品には$().val( val )を、 他の要素には$().prop("value", val)を、 現在値を設定するのに使うようにします。

リストに戻る

JQMIGRATE: jQuery.fn.attr('selected') may use property instead of attribute
JQMIGRATE: jQuery.fn.attr('checked') may use property instead of attribute

selected, checked にjQuery.fn.attr()で アクセスすると警告されます(jQuery.migrateReset()を 使ってもリセットされない(1.1.0))。
$().attr("selected"), $().attr("checked")等は 時々属性ではなくプロパティを使います。 これは$().prop()を導入する前のバージョンからの 互換性を保つためですが、現在値の取得・設定には $().prop()を使うことが推奨されています。

警告を消すには、checked, selected 等の Boolean 型のプロパティにアクセスするのに $().attr()を使うのは止めて $().prop()を使うようにします。

リストに戻る

JQMIGRATE: jQuery.clean() is deprecated

jQuery.buildFragment()jQuery.clean()は 文書化されていない内部メソッドで、 jQuery.buildFragment()の用法は 1.9 で変更され、jQuery.clean()は 1.9 で 削除されました。

警告を消して 1.9 以降に対応するためには、 コードを書き換えてこれらのメソッドを利用しないようにします。 代わりにjQuery.parseHTML()の使用を例に 挙げています。

リストに戻る

JQMIGRATE: Use of jQuery.fn.data('events') is deprecated

1.7 までは、キー"events"で何かしらのデータを 登録してなければ.data("events")で その要素の内部のイベントデータを取得することができました。 1.8 でこれは削除されました。

警告を消すには、キー"events"で何かしらのデータを 登録していないのに.data("events")を 実行しないようにします。 内部の data 構造を取得するインターフェースは公開も文書化も されていません。 一応jQuery._data("events") を使えば取得可能だそうですが、これも文書化されない 使い方です。

リストに戻る

スポンサードリンク