この記事について この記事は、生成AIを活用した自動生成フローで作成しています。 MDNのMutationObserver公式資料を確認し、架空のカードを追加・削除・変更すると何が通知されるかを観察する教材を作りました。コードの構文は確認しましたが、ブラウザ実表示は未確認です。
検証ステータス：📘 公式仕様照合・JavaScript構文確認済み／ブラウザ・WordPress実表示は未確認
Webページの中身が変わった瞬間を、JavaScriptはどうやって知るのでしょうか。MutationObserverは、HTMLの要素が増えたり属性が変わったりしたことを、変更記録として受け取るためのブラウザAPIです。今回はカードの変化を自分で起こし、通知ログと見比べます。
| 項目 | この教材の条件 |
|---|---|
| 対象 | PC・スマホの現代的なブラウザ（実機未確認） |
| 技術 | JavaScript標準のMutationObserver |
| 費用 | 無料。外部ライブラリ・ログイン不要 |
| 入力 | 架空のカードをボタンで操作 |
| 通信 | デモの実行時に外部API送信なし |
| 制限 | カード最大8枚、ログ最新12行 |
まず動かす：カードを増やして通知を見よう
カードの変更監視ライブデモを開く（ソースはGitHubに保存済み。GitHub Pagesへの反映・実ブラウザでの動作は未確認）
「カードを追加」を押します。
「先頭の状態を切替」を押します。
「監視を停止」を押してから、もう一度カードを追加します。
画面の上側ではカードの枚数や状態が変わり、下側の「通知ログ」では監視した変更が文字で表示される想定です。3番目では、カードは増えても通知が増えない点を見てください。
操作後はここを見る
| 操作 | 画面の変化 | 通知の予想 |
|---|---|---|
| カードを追加 | 2枚→3枚 | 追加：1枚 |
| 先頭を切替 | 未完了→完了 | pending → done |
| 監視を停止して追加 | 3枚→4枚 | 新規通知なし |
| 監視を再開して追加 | 4枚→5枚 | 追加：1枚 |
これらはコードとAPI仕様から予想した結果です。今回のブラウザ実測ではありません。監視を再開しても、停止していた間の変更が後からまとめて届くわけではありません。再開後の新しい変更だけが通知対象です。
「最後のカードを削除」を押すと、一覧の末尾が1枚減り、「削除：1枚」という通知が出る想定です。「ログを消す」は表示済みログを消すだけで、カード一覧は変えません。
観察のコツ カードが変わったことと、通知が届いたことは別です。監視停止中もカードは変えられます。変更を実行する処理と、変更を知らせる処理を分けて考えると仕組みが分かります。
なぜ通知が届くのか
ブラウザはページをDOM（Document Object Model）という要素の木として扱います。今回の教材では、カード一覧の ul 要素を監視対象にします。ボタンを押すとJavaScriptが要素を追加したり、カードの data-state 属性を変更したりします。
flowchart LR A["ボタン操作"] --> B["DOMを変更"] B --> C["MutationObserver"] C --> D["変更記録"] D --> E["通知ログ"]
図は概念的な順序です。実際の通知コールバックはDOM変更の処理と同期して直ちに割り込むのではなく、変更後のマイクロタスク処理で配信されます。したがって、同じ処理中に複数の変更が起きた場合、1回のコールバックへ複数の記録がまとめられることがあります。通知回数と操作回数は必ずしも一致しません。
大事なコードはこの設定
observer.observe(list, {
childList: true,
subtree: true,
attributes: true,
attributeFilter: ["data-state"],
attributeOldValue: true
});
childList は要素の追加・削除、attributes は属性変更を監視します。subtree を true にすると、一覧の子カードに付いた属性も監視できます。attributeFilter は今回必要な data-state だけを対象にし、attributeOldValue は変更前の値を記録する設定です。
ただし、subtree: true ではカード内の文字更新も childList の記録になる場合があります。完成版は「追加・削除」として表示する記録をカード一覧の直下だけに限定しています。これをしないと、カードの状態ラベルを書き換えただけで「カードが増えた」と誤認するおそれがあります。
1か所変えてみる
JavaScriptの完成版にある attributeOldValue: true を false に変更し、ページを再読込して「先頭の状態を切替」を押してみてください。
| 比較 | 変更前の状態 |
|---|---|
true | pendingと記録される想定 |
false | 不明と記録される想定 |
どちらでも変更後の done は取得できます。違うのは「変更前の値まで通知に含めるか」です。元に戻せば同じ条件で比較できます。
この実験は、後から状態を読み取るだけでは「前に何だったか」を復元できないことを示します。監視したい情報に応じて、必要な記録を先に選ぶのが重要です。
うまく動かないとき
| 症状 | まず確認 | 対処 |
|---|---|---|
| ボタンが動かない | Consoleのエラー | app.js の読み込みを確認 |
| 通知が増えない | 「停止中」表示 | 「監視を再開」を押す |
| 追加できない | カードの枚数 | 8枚なら先に削除 |
| 変更前が不明 | attributeOldValue | true に戻す |
| 通知が予想より多い | 監視対象と種類 | 対象外の記録を除外 |
注意 MutationObserverは、監視を開始する前の履歴を取得する機能ではありません。監視停止中の変更も後から復元できません。重要な操作履歴や監査証跡を残すには、別の保存設計が必要です。
自分のPCで動かす
GitHubの固定コミットから docs/demos/mutation-observer-card-log/ にある index.html と app.js を同じフォルダへ保存し、HTMLをブラウザで開きます。ビルド、CDN、外部ライブラリは不要です。
HTMLファイルの直接表示で動かない場合は、作業フォルダで python3 -m http.server 8000 --bind 127.0.0.1 を実行し、同じPCから http://127.0.0.1:8000/ を開きます。終了は Ctrl+C です。管理者権限は不要です。なお、これらのローカル手順は今回の実ブラウザでの成功確認を意味しません。
仕事・学習で使うなら
動的にカードや通知を追加する画面では、「いつ新しい要素が現れたか」を検出したいことがあります。例えば、別のUI処理が一覧へ行を追加したときに、その行へ補助表示を付ける用途です。既存の処理を直接変更できるなら、変更した関数から必要な処理を呼ぶ方が単純な場合もあります。
MutationObserverはDOMの変化を見つけますが、業務データが正しいか、誰が変更したか、サーバーへ保存されたかまでは証明しません。ログを画面上だけに残す今回の教材を、監査ログや証跡保全の仕組みとして使わないでください。
大量の要素を監視すると通知処理が負荷になる可能性があります。対象要素を絞り、必要な変更だけを attributeFilter で選び、不要になった監視は disconnect() で止めます。今回のサンプルは最大8枚で、変更ログも12行までに制限しています。
通知される変更を正しく読み取るための補足実験
MutationObserverはページの変更をすべて同じ形で知らせるわけではありません。子要素の追加・削除、属性値の変更、テキストの変更は別の種類の変更です。監視を開始するときに何を対象にするかを指定するため、通知が届かない場合はイベントが壊れたと決めつける前に、監視オプションと実際に変更した場所を比べてください。カードを追加した実験と文字だけを変えた実験では、記録に現れる内容が異なることがあります。
複数の変更を短時間に行うと、一回のコールバックで複数の変更記録をまとめて受け取る場合があります。そのため、通知回数と実際に追加したカード数が一致しないことだけでは不具合とはいえません。何件の変更記録があり、それぞれの種類が何かを確認することが重要です。追加と削除を続けて行う操作では、最後の見た目と途中の変更履歴が異なる場合がある点にも注意してください。
監視を止める操作では、画面上のカード自体が消えるわけではありません。disconnect()は以後の変更を監視しないための操作であり、すでに追加したDOMを削除する操作とは別です。停止中にカードを変更した場合、再開しても過去に行った変更が自動で再通知されるとは限りません。停止前後のログを見比べて、何を観測した時間帯なのかをはっきりさせます。
実務でこのAPIを使うときは、監視対象を必要な要素だけに絞る方が問題を切り分けやすくなります。ページ全体を無条件で監視すると、無関係な表示更新も大量に記録される可能性があります。個人情報を含む画面では、変更内容の全文を安易にログへ保存せず、変更種別と数だけを集計するなどの配慮も必要です。教材は架空のカードを使うため、この注意を本番の顧客画面へ転用する前に検討できます。
公式資料
公式資料確認：2026年11月2日。JavaScriptの構文確認以外に、実ブラウザ、GitHub Pages到達、WordPress青い囲み、アイキャッチ、モバイル、印刷/PDFの実表示は確認していません。
GitHubサンプル
MutationObserverカード監視教材：README ／ デモのHTMLとJavaScript
本文は仕組みの短い抜粋、GitHubは完成版と改造手順を担当します。アイキャッチ・公開日・更新日・Source/LicenseはWordPress既存の共通表示に委ね、本文に重複挿入しません。独自CSSやJavaScriptをWordPress本文へ埋め込んでいません。
