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

jQuery Migrate プラグインの使い方は前にもまとめましたが、 少し追加修正がありますので再び投稿します。

jQuery Migrate プラグインについて

jQuery Migrate プラグイン(以下 jQuery Migrate)は jQuery 1.9 以降への移行を補助するツールです。 jQuery のメジャーバージョンが3となるにあわせて、 jQuery Migrate の種類が1.xと3.xに増えました。

jQuery 1.x(2.x) をその最新版(現在だと1.12.4(2.2.4))まで更新するのを助けるのが jQuery Migrate 1.x で、 jQuery 1.11.0(2.1.0) 以降から 3.x への更新を助けるのが jQuery Migrate 3.x です。

つまり、 jQuery 1.11.0(2.1.0) 未満から 3.x へ更新する場合、 jQuery Migrate 3.x を使う前に jQuery Migrate 1.x を利用するなどして jQuery 1.11.0(2.1.0) 以降に更新する必要があります。

jQuery Migrate は、移行すると問題となるコードの箇所を指摘してくれます。 加えて、jQuery Migrate 1.x は jQuery 1.9 で削除や変更された振る舞いの 復元や修正をしてくれます。

jQuery 3 以降に更新したい場合は、 jQuery Migrate 1.x が指摘した問題を全て解決する必要があります。 一方で、jQuery 3 未満に更新を留めておく場合(例えば、IE 6-8 もサポートするべく jQuery 1.x の最新版までにしておく場合)は、 指摘された問題を解決してなくても jQuery Migrate 1.x の修正機能でうまく動いてくれるかもしれません (もちろん解決した方が良いです)。

jQuery Migrate は、移行の際の問題特定なら jQuery 1.6.4 から使用できます (1.6.4 未満だった場合は、とりあえず 1.6.4 まで リリースノートを見るなどして自力で更新する)。 一方、削除された機能を復元する場合は 1.9 以降を使う必要があります。

リストに戻る

開発版と製品版

jQuery Migrate には 開発版(http://code.jquery.com/jquery-migrate-1.4.1.js)と 製品版(http://code.jquery.com/jquery-migrate-1.4.1.min.js)があります。

通常、開発版はコードの問題をブラウザのコンソールに表示しますが 製品版は表示しません。加えて製品版は圧縮されて容量が節約されています。

移行の際のコード検証には開発版を、コードを修正しきれなかった場合は 製品版を使うといいと思います。

リストに戻る

使い方

ページ上に移行したいバージョンの jQuery を読み込み、 その後に jQuery Migrate を読み込みます。

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

これで、削除された機能や変更された振る舞いがある程度復元され、 廃止予定や削除された機能、振る舞いが変わった機能をコードが使おうとすると、 コンソールに警告文とスタックトレースが表示されます。 (警告文はjQuery.migrateWarningsという配列にも格納されます。)

警告文の一覧は下にまとめてあります。 この情報を元に、警告が出なくなるまでコードを修正していきます。

警告が表示されなくなったら、jQuery Migrate を外します。 それでもまだ問題が残る場合は、コードを調べて自力で解決します。

jQuery Core 1.9 Upgrade Guide に更新時に問題が発生しそうな挙動変更が 羅列されていますので参考にするといいと思います。 (※自分がまとめたのはコチラ。)

リストに戻る

jQuery Migrate のプロパティ

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

jQuery.migrateWarnings
配列。そのページで現在までに生成された警告メッセージが 生成された順に格納されます。 同じような状況が複数回起こっても格納されるメッセージは重複しません。
jQuery.migrateMute
trueに設定すると警告がコンソールに 出力されなくなります (jQuery.migrateWarningsには格納されます)。
jQuery.migrateTrace
コンソールに警告は出力されて欲しいけど スタックトレースはいらない場合は このプロパティをfalseにします
jQuery.migrateReset()
jQuery.migrateWarningsを空にします。 今まで生成したメッセージも忘れるので、既に生成した警告も 配列に格納されるようになります。
jQuery.migrateVersion
バージョン 1.3.0 で追加されました。 現在使っている jQuery Migrate のバージョンを示す文字列が入っています。
リストに戻る

警告メッセージの種類

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

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

JQMIGRATE: Migrate is installed, version X
JQMIGRATE: Migrate is installed with logging active, version X

これは警告では無くて、このプラグインが最初に読み込まれる時に コンソールに出力されるメッセージです。 バージョン 1.4.0 からは製品版でも表示されます。 jQuery Migrate を本番サイトで使用する時は、 jQuery Migrate がパフォーマンスに影響を与えること、 jQuery の挙動を変更するので デバッグが困難になる恐れがあることに注意して下さい。

※JQMIGRATE: Logging is activeは無くなりました。

リストに戻る

JQMIGRATE: jQuery.attrFn is deprecated

文書化されてなかったのですが、jQuery.attrFnオブジェクトは jQuery 1.8 より前に内部で使われていました。 1.8 で使われなくなり、1.9 で削除されました。 古い jQuery UI や jQuery Mobile 、その他プラグインなどがこれを 使用しているそうです。

jQuery UI は 1.8.21 以降、jQuery Mobile は 1.2.1 以降なら jQuery.attrFnを使わなくなるそうです。 他のプラグインについては、 jQuery.attrFnを使わないバージョンが出ていればそのバージョンに更新し、 出ていなければ作者に連絡する、等が考えられます。

リストに戻る

JQMIGRATE: $(html) HTML strings must start with '<' character

$()に渡される HTML 文字列はタグで始まってタグで終わるようにして下さい。 jQuery 1.9 で、$()に渡す HTML の文字列はタグで(もっと言うと <で)始まらなくてはならなくなりました(セキュリティ的な理由)。 <の前に文字(空白含む)が先行してはいけません (jQuery Migrate 無しだとエラーが throw され、有りだと先行文字列が無視されます)。

任意の HTML 、特に外部から得た HTML をパースして jQuery オブジェクトを取得するには、$.parseHTML()メソッドを使って $($.parseHTML("string"))のようにして下さい。 $.parseHTML()はデフォルトでは HTML ソースの中の script は実行されません。 実行させたい場合は$($.parseHTML("string", document, true))のように 明示的に指定する必要があります。 $.parseHTML()を使えば安全というわけでもないので注意して下さい。

リストに戻る

JQMIGRATE: $(html) text after last tag is ignored

$()に渡される HTML 文字列はタグで始まってタグで終わるようにして下さい。 渡す HTML 文字列がタグで終わっていない場合、エラーの throw はされませんが 最後のタグ以降の文字列は無視されます。

$()に渡す前に$.parseHTML()を通せば警告は出なくなりますが、 その場合 HTML 文字列のタグに先行(もしくは後続)する文字列は 無視されずにテキストノードに変換されることに注意して下さい。

もし先行(後続)する文字列を jQuery オブジェクトに入れたくないなら $.parseHTML()に渡す前に削除して下さい。 もしくは$($.parseHTML(html)).filter("*")とします。 この場合、先行、後続だけでなく最上層のテキストノードが全て jQuery オブジェクトから削除されます。

リストに戻る

JQMIGRATE: Attribute selector with '#' must be quoted
JQMIGRATE: Attribute selector with '#' was not fixed

CSS では、例えばa[href=#main]のように属性セレクタの属性値に '#'のような特殊文字を含む場合は"や'で囲む必要があります。 jQuery 1.11.3/2.1.4 までは囲まなくても受け入れられていました (文書化はされていない)が、後のバージョンでは標準に合わせて エラーを throw します。jQuery Migrate を使えば受け入れられ throw はされなくなりますが、セレクタが複雑だと復元されない恐れがあります。

修正するには、特殊文字がある属性値を、 例えばa[href="#main"]のように"や'で囲んでください。 警告文には問題のセレクタも表示されるのでそれを参考にして下さい。

リストに戻る

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>とするのが推奨されています。

リストに戻る

JQMIGRATE: jQuery.boxModel is deprecated
JQMIGRATE: jQuery.support.boxModel is deprecated

この2つのプロパティは、ページが Quirks モードだとfalseで Standards モードだとtrueになります。 Quirks モードは jQuery でサポートされてないので削除されました。

jQuery を使うページを Standards モードにして下さい(上参照)。

リストに戻る

JQMIGRATE: jQuery.parseJSON requires a valid JSON string

$.parseJSON()にnull以外のfalseになるような値を渡すと警告されます。

jQuery 1.9.0 より前、$.parseJSON()は JSON としては不正な文字列 (例えば空文字列)をある程度許容してエラーを throw せずnullを返していました。 このため$.parseJSON()とJSON.parse()で挙動が異なっていました。

jQuery 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 の製品(圧縮)版を使う、 jQuery Migrate のソースから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.8 で廃止予定になりました。 代わりに$().on("error", fn)のように.on()で書き換えます。

リストに戻る

JQMIGRATE: jQuery.fn.load() is deprecated
JQMIGRATE: jQuery.fn.unload() is deprecated

.load()と.unload()は用法が2つあって、"load"や"unload"の イベントハンドラを登録する用法と、サーバから HTML ソースを読み込んで 置換する用法がありました。そのうちイベントハンドラを登録する用法が 1.9 で 廃止予定になり 3.0 で削除されました。

修正するには$().load(fn)と$().unload(fn)の使用を全て $().on("load", fn)と$().on("unload", fn)に変えて下さい。

リストに戻る

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

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

この警告を出さないようにするには、 .toggle()のこの用法に依存しているコードを書き直す、 jQuery Migrate の製品(圧縮)版を使う、 jQuery Migrate のソースから.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 イベントハンドラを登録しようとすると警告されます。 jQuery 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 上でのみトリガーされるようになりました。 他のグローバルにトリガーされるイベントは文書化されておらず、 サポートも jQuery Migrate で復元もされません。

警告を消すには グローバルイベントを使用しないようにコードを変更します。

リストに戻る

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') might use property instead of attribute

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

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

リストに戻る

JQMIGRATE: deferred.pipe() is deprecated

jQuery 1.8 から.then()メソッドが同じ機能を実行するように変更されたので、 jQuery.Deferredオブジェクトの.pipe()メソッドが廃止予定になりました。

修正するには、大抵は.pipe()を.then()に変更すればできますが、 jQuery 3.0 以降 Promises/A+ 規格に沿うように仕様が変わったので、 コードが仕様変更前の挙動(例えばコールバックが同期的に呼ばれる等)に 依存している場合はそれを解消する必要があります。

リストに戻る

JQMIGRATE: deferred.isResolved() is deprecated
JQMIGRATE: deferred.isRejected() is deprecated

jQuery 1.7 から、jQuery.DeferredオブジェクトのisResolved()と isRejected()メソッドは廃止予定になっていて、1.8 で削除されました。

修正するには、deferred.state()の返り値("resolved"もしくは"rejected")で 判定するようにします。

リストに戻る

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

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

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

リストに戻る

JQMIGRATE: HTML string cannot start with a '#' character

location.hashにページ上の ID の値が入っていると想定して、その ID を持つ要素を $("#"+location.hash)のようにして取得しようとするページがあるらしく、 その場合URL末尾が#<script>...</script>となるようにすると任意のコードを 実行できてしまいます。

jQuery はこのような事態を防ぐため<以外で始まるHTMLソースを受け付けません。 jQuery Migrate はこれを特別な場合として警告しエラーを投げます。

修正するには#で始まる HTML ソースを渡さないようにします。どうしても そうしたい場合は$.parseHTML()を通してください。

リストに戻る

JQMIGRATE: jQuery.fn.andSelf() replaced by jQuery.fn.addBack()

.andSelf()は現在の jQuery オブジェクトが保持する DOM 要素の集合に 前の結果の集合を追加するメソッドです。 このメソッドの機能をより良く反映するために.addBack()に改名され、 .andSelf()は廃止予定になり 3.0 で削除されました。

修正するには、.andSelf()を使っているところを全て.addBack()に換えて下さい。

リストに戻る

JQMIGRATE: jQuery.fn.size() is deprecated; use the .length property

.size()メソッドは現在の jQuery オブジェクトが保持する要素数を返しますが、 .lengthプロパティも同じ機能で効率も良いです。そのため jQuery 1.9 から.lengthプロパティの使用が推奨されます。 .size()は廃止予定になり 3.0 で削除されました。

修正するには.size()の使用箇所を全て.lengthに換えて下さい。

リストに戻る

JQMIGRATE: jQuery.swap() is undocumented and deprecated

jQuery.swap()メソッドは CSS のプロパティの集合を一時的に交換します。 このメソッドは API として公開されておらず、パフォーマンスに問題を 起こす恐れがあるため使うべきではありません。

警告を無くすにはjQuery.swap()を実行しないようにコードを書き直して下さい。

リストに戻る

JQMIGRATE: 'ready' event is deprecated

"ready"イベントは、例えば$( document ).on( "ready", fn )のように 登録し、documentが準備された時に発生します。しかし、 ブラウザのDOMContentLoadedイベントが起きる前に登録しないと発生しません。

ページ読み込み後に jQuery やプラグインを非同期で読み込んだりすると もう実行されません。 "ready"イベントは廃止予定になり 3.0 で削除されました。

修正するには$( document ).on( "ready", fn )となっているところを全て $( document ).ready( fn )か$( fn )に換えます。 交換後のメソッドは例えそのdocumentの準備が完了した後でも確実に動きます。

リストに戻る

スポンサードリンク