Scroll Image Sequence

スクロールに合わせて、連番の画像(コマ)を canvas に描く WordPress のブロックプラグインです。

ブロックを置いたセクションは、スクロールしているあいだ画面に固定されます。そのあいだ、スクロールの量に合わせてコマが進みます。車が回る、部品がばらける、といった「動画のような動き」を、スクロールで前後に操作できる形で見せられます。

• ブロックエディター用の普通のブロックです(ACF などのほかのプラグインは要りません)
• コマ画像は、管理画面から ZIP で上げて登録します
• WordPress.org には登録していません。更新は GitHub の Release から、管理画面で行えます

動作の要件

インストール

1. Releases から、l2d-scroll-image-sequence.{版}.zip をダウンロードします
2. 管理画面の「プラグイン」→「新規追加」→「プラグインのアップロード」で、その ZIP を上げます (または、ZIP を展開した l2d-scroll-image-sequence フォルダを /wp-content/plugins/ に置きます)
3. 「プラグイン」の画面で有効にします

更新

GitHub の Release に新しい版が出ると、管理画面の「プラグイン」に、ほかのプラグインと同じように更新の案内が出ます。「今すぐ更新」で更新できます。プラグインごとの「自動更新を有効化」も使えます。

更新の確認には、同梱している l2d-wp-github-update-lib を使っています。

使い方

1. コマ画像の ZIP を用意する

• 画像の形式は WebP・JPEG・PNG です

• コマの順番はファイル名の自然順です(frame-2 は frame-10 より前に来ます)。frame-000.webp・frame-001.webp … のように、数字の桁をそろえておくと確実です

• ZIP の中にフォルダがあってもかまいません(中の画像はまとめて 1 列に並べます)。ただし、フォルダが違っても同じファイル名の画像が 2 つあると、取り込みは止まります

• 画像以外のファイル(__MACOSX、隠しファイル、PHP など)は取り込みません。取り込まなかった数は、保存後のお知らせに出ます

• すべてのコマを同じ縦横比にしてください。SP の枠の比率は、1 コマ目の大きさで決まります

• 大きさの上限(既定値。フィルターで変えられます):

  項目	既定の上限
  ZIP の中のファイルの数	1,000
  コマの数	300
  1 コマの大きさ	10MB
  1 コマの画素数(幅 × 高さ)	16,000,000(16 メガピクセル)
  コマの合計の大きさ	100MB
  コマの画素数の合計	500,000,000(5 億画素)
  アップロードできる ZIP の大きさ	サーバーの設定(upload_max_filesize・post_max_size)に従う

  どれかを超えると取り込みは止まり、それまでのコマはそのまま残ります。

• 参考: 1 本 90〜140 コマ、2048 × 1152 の WebP で、合計 3〜7MB 程度のシーケンスで使っています。SP 用にもう少し小さい画像(例: 1280 × 720)を別に用意すると、SP での読み込みが軽くなります

SP 用のコマを少なくする

SP 用のシーケンス(ブロックの「Sequence for small screens」で選ぶもの)は、PC 用より少ないコマで足ります。SP は画面が低いので、同じコマの数だと 1 コマあたりのスクロールの量が PC より小さくなり、コマを減らしても動きの細かさは PC と同じくらいに保てます。

• 間引き方: 元のコマから等間隔に選びます(半分なら 1 つおき)。最初と最後のコマは必ず残してください。 最後のコマが無いと、スクロールし終えたときの絵が変わります
• ファイル名: 元の番号のままでかまいません(例: frame-000・frame-002・…・frame-089)。並びはファイル名の自然順なので、番号が飛んでいても順番は崩れません
• 登録: 間引いたコマを別の ZIP にして、PC 用とは別のシーケンスとして登録し、ブロックの「Sequence for small screens」で選びます
• 効果: コマの数に比例して、SP で展開したときの最大のメモリと通信量が減ります。半分にすれば、どちらも半分です

例(実際のサイトでの測定。画面 390 × 844・SP の「Scroll length」0.9 のとき):

半分にしても 1 コマあたり約 17px で、PC(約 23px)より細かく動きます。数値はコマの大きさ・数・スクロールの長さで変わるので、目安として見てください。

2. 「Image Sequences」に登録する

1. 管理画面のメニュー「Image Sequences」→「Add New Image Sequence」を開きます
2. タイトルを付けます(ブロックで選ぶときの名前になります)
3. 「Frames」の欄で ZIP を選び、「公開」(または「更新」)を押します
4. 保存後、取り込んだコマの数と、1 コマ目・最後のコマの縮小画像が出ます

• コマを差し替えるときは、新しい ZIP を上げて保存します。古いコマはすべて入れ替わります(新しいコマの取り込みに失敗したときは、古いコマが残ります)
• 「Download frames as ZIP」で、取り込んだコマを ZIP でダウンロードできます。本番のサイトへ運ぶときや、差し替えの元に使えます(上げた ZIP そのものはサーバーに残しません)
• フロントに表示されるのは「公開」の状態のシーケンスだけです。 下書きのシーケンスは、編集できる人がプレビューで見るときだけ表示されます
• ZIP を上げられるのは、「メディアのアップロード」の権限(upload_files)があるユーザーです(既定では投稿者以上)

3. ブロックを置く

1. 投稿やページの編集画面で、ブロック「Scroll Image Sequence」(カテゴリー「メディア」)を置きます
2. 右のサイドバーで、表示するシーケンスを選びます
3. ブロックの中に、コマの上に重ねたい見出しや段落などのブロックを入れます

編集画面では、1 コマ目を背景にして中身のブロックを重ねて表示します。固定やコマの動きは、編集画面では付きません(フロントで確かめてください)。

4. ブロックの設定

サイドバーの「Image sequence」パネル:

「Small screens」パネル(SP の幅だけに効く設定):

ブロックの「配置」は「幅広」「全幅」を選べます。HTML アンカーも付けられます。

表示のしかた

• PC: コマを画面いっぱいに描き(はみ出す分は切り抜きます)、その上に中身のブロックを重ねます
• SP(既定 1024px 以下): コマの縦横比の枠を、画面の上下左右の中央に置き、コマ全体を描きます。横向きの画面では、枠が画面の高さに収まるよう幅を縮めます
  • 「Minimum frame height」を入れると、枠は幅いっぱいになり、高さは「画面の高さ」と「最小の高さ・幅に合わせた高さの大きいほう」の小さいほうになります。はみ出す分は切り抜きます。100vh にすると画面いっぱいです
• 固定するのは、中身のブロックが画面の高さに収まるときだけです。収まらないとき(画面が低い SP など)は固定せず、1 コマ目の画像の上に中身を重ねた普通のセクションとして表示します。中身が切れることはありません
• JS が動かないときも、固定しない表示になります(1 コマ目の画像と中身)
• OS の設定で「視差効果を減らす」(prefers-reduced-motion: reduce)をオンにしている人には、固定もコマの動きも付けず、最後のコマの静止画を見せます。読み込む画像も最後の 1 枚だけです
• コマの読み込みは、セクションが画面の 2 つ分手前まで近づいたときに始まります。ページ全体で同時に 6 件ずつ、今の位置に近いコマから読みます。まだ届いていないコマは、届いている中でいちばん近いコマで代わりに描きます
• ブラウザのメモリを使いすぎないよう、一度に持つコマは今の位置の前後だけです。ページ全体で、デコードした画像の画素数の合計が 2 億画素(RGBA で約 800MB)に収まる枚数を、ページの中のブロックの数で分けます(例: ブロックが 2 つで、コマが 2048 × 1152 なら、1 つあたり約 42 コマ)。離れたコマは手放し、戻ってきたらブラウザのキャッシュから読み直します

テーマで調整する

このプラグインが持つのは、固定・canvas・重ね方・フェードインだけです。見出しや数値の文字の大きさ・位置・余白などは、テーマの CSS で書きます。

中身のブロックに付けるクラス

ブロックの設定の「高度な設定」→「追加 CSS クラス」に書きます。

l2dsis-after-mobile は、ブロックの中身のいちばん上の階層(直下)のブロックだけに効きます。グループの中のブロックには効きません。テーマのクラスを付けたグループで囲みたいときは、グループをこのブロックの外側に置いてください。こうすると、SP で移したあとも同じグループの中にあるので、親のクラスから書いた CSS もそのまま効きます。

グループ(テーマのクラス. 例: my-section)
└ Scroll Image Sequence
   ├ 見出し
   └ グループ(l2dsis-reveal l2dsis-after-mobile)

SP で移したあとのブロックだけに CSS を当てたいときは、.l2dsis-sequence__after から書きます(SP の幅で JS が移したときだけ、この中に入ります)。

/* 例: SP で枠の下に移った数値を、2 列に並べて枠との間をあける */
.l2dsis-sequence__after > .my-numbers {
    display: grid;
    grid-template-columns: repeat(2, 1fr);
    margin-top: 24px;
}

CSS 変数

主な要素のクラス

ブロックの下地は黒(#000)です。コマの背景の色に合わせたいときは、テーマの CSS で .l2dsis-sequence の background-color を変えてください。

フィルター

functions.php などで値を変えられます。

// 例: SP の扱いにする幅を 768px にする.
add_filter(
    'l2dsis_breakpoint',
    function () {
        return 768;
    }
);

自己更新の仕組みのフィルター(l2dwpghul_updater_enabled など)は、l2d-wp-github-update-lib の README を見てください。

注意

• コマの画像は、wp-content/uploads/l2d-scroll-image-sequence/{投稿 ID}/frames/ に、公開の URL で置かれます。 シーケンスを下書きや非公開にしても、URL を知っていれば画像そのものは取れます。人に見せられない画像には使わないでください
• シーケンスはデータベースと uploads にだけあります。別のサイト(本番など)へ運ぶときは、「Download frames as ZIP」で取った ZIP を、運び先の「Image Sequences」で上げ直してください。投稿 ID が変わるので、ブロックでシーケンスを選び直す必要があります
• 同じシーケンスに、2 つの取り込みを同時に行うことはできません。後から始めた方は「別の取り込みの途中です」と断られ、今のコマはそのまま残ります。少し待ってから上げ直してください。この排他の仕組みは PHP の flock() を使うので、NFS などのネットワークのファイルシステムでは効かないことがあります
• 編集画面がシーケンスの一覧を取るときは、全件を読み、それぞれのフォルダを調べます。シーケンスは数件から数十件程度の運用を想定しています
• マルチサイトでは、サイトごとにシーケンスを登録します

無効化・削除したとき

• 無効化: データは何も消しません。ページに置いたブロックの中身(見出しなど)は、普通のブロックとして表示されます(固定とコマは出ません)

• 削除(「プラグイン」の画面で「削除」): このプラグインが作ったデータをすべて消します。元に戻せません

  • 「Image Sequences」の投稿(ゴミ箱・下書きを含む)
  • wp-content/uploads/l2d-scroll-image-sequence/(コマの画像と、取り込みの排他に使うファイル)
  • お知らせの一時データと、更新の確認のキャッシュ

  コマの画像を残したいときは、削除の前に「Download frames as ZIP」で取っておいてください。ページに置いたブロックは本文に残り、中身だけが表示されます。

開発

# Node(mise.toml の版)と依存のインストール
npm ci
composer install

# ビルド(src/ → build/)
npm run build

# lint
npm run lint:js
npm run lint:css
composer lint      # phpcs(WordPress Coding Standards)

# テスト・静的解析
npm run test:unit  # Vitest(src/sequence/test/. コマの選び方・読み方・持ち方の判断)
composer test      # PHPUnit(tests/. WordPress のテストスイートは使わず、必要な関数だけを置き換える)
composer analyse   # PHPStan(level 5)

• CI(.github/workflows/ci.yml)は、main への push と PR で、PHP の構文(7.4〜8.4)・phpcs・PHPStan・PHPUnit・JS と CSS の lint・Vitest・build/ が最新か・Plugin Check を確かめます

• build/ は Git に入れています。リリースの ZIP は、作業ツリーを .distignore で絞って作り、ビルドの工程を持たないためです。src/ を変えたら、npm run build のあとで build/ も一緒にコミットしてください

• 配布の ZIP は bash bin/build-zip.sh で作れます(l2d-scroll-image-sequence.{版}.zip)

• lib/l2d-updater/ は、l2d-wp-github-update-lib を git subtree で取り込んだものです。直接編集しないでください

• タグと Release の名前には v を付けません(例: 1.0.0)

ファイルの構成

ライセンス

GPLv2 or later