OD Gradient Motion

WordPress のブロック背景に設定したグラデーションへ、CSSアニメーションを追加するプラグインです。対応ブロックで4種類のアニメーション、3種類の再生方向、1〜60秒の再生時間を設定できます。

色やグラデーション自体はWordPress標準の背景設定を使用します。対応ブロックを選択し、サイドバーの「Gradient motion」でアニメーションを有効にしてください。エディターで結果を確認でき、同じ設定が公開画面にも反映されます。OSの「視差効果を減らす」設定にも対応しています。

標準では次のブロックに対応しています。

• core/group
• unitone/section
• unitone/decorator

使い方

1. 対応ブロックを追加します。
2. WordPress標準の背景設定でグラデーションを指定します。
3. ブロック設定サイドバーの「Gradient motion」を開きます。
4. 「Enable animation」を有効にします。
5. 「Preset」から用途に合う設定を選ぶか、各項目を個別に設定します。
6. 「Animation type」でHorizontal、Vertical、Diagonal、Shiftから動きを選択します。
7. 「Playback direction」でNormal、Reverse、Alternateから再生方向を選択します。
8. 「Duration (seconds)」で1周期の長さを1〜60秒から指定します。

色やグラデーションの定義は保存済みのWordPress標準属性をそのまま利用します。このプラグインを有効にするだけでは、背景グラデーション自体は追加されません。

プリセット

プリセットを選択すると、アニメーション種類、再生方向、再生時間がまとめて更新されます。

プリセット	アニメーション種類	再生方向	再生時間
Flow	Horizontal	Normal	10秒
Aurora	Diagonal	Alternate	18秒
Energy	Shift	Reverse	4秒
Calm	Vertical	Alternate	24秒

プリセット適用後にアニメーション種類、再生方向、再生時間のいずれかを個別に変更すると、表示はCustomへ切り替わります。現在値はそのまま維持されます。プリセット属性を持たない既存ブロックはNo presetとして扱われ、従来の表示は変わりません。

必要環境

• WordPress 6.2 以上
• PHP 7.4 以上
• Node.js 18.12 以上
• npm 8.19 以上
• Composer 2
• Docker（wp-env の起動時）

開発環境

npm install
composer install
npm run env:start

PHP のコーディング規約を確認します。

npm run lint:php

翻訳カタログを更新します。

npm run i18n:pot
npm run i18n:mo

フックによるカスタマイズ

対応ブロックは次の2段階で管理しています。

1. od_gradient_motion_registered_blocks で、プラグインが扱えるブロックとして登録する。
2. od_gradient_motion_enabled_blocks で、エディターUIとフロント処理を実際に有効化する。

有効ブロックに指定しても、登録済みブロックに存在しないブロック名は無視されます。フィルターはテーマの functions.php、または独自プラグインから追加できます。ブロック属性の登録より前に必要なため、ファイルの読み込み時か plugins_loaded で登録してください。

フック一覧

フック	引数	デフォルト値	用途
od_gradient_motion_registered_blocks	array<string, array>	core/group、unitone/section、unitone/decorator	ルート要素へ効果を適用できるブロックを登録します。
od_gradient_motion_enabled_blocks	string[]	core/group、unitone/section、unitone/decorator	登録済みブロックのうち、実際に機能を有効にするブロックを指定します。

Core Coverブロックを追加する

登録と有効化の両方を行います。

add_filter(
    'od_gradient_motion_registered_blocks',
    function ( $blocks ) {
        $blocks['core/cover'] = array(
            'label'  => 'Cover',
            'target' => 'root',
        );

        return $blocks;
    }
);

add_filter(
    'od_gradient_motion_enabled_blocks',
    function ( $blocks ) {
        $blocks[] = 'core/cover';

        return $blocks;
    }
);

サードパーティーブロックを追加する

次の例では example/decoration を追加しています。実際に使用するブロックの名前へ置き換えてください。

add_filter(
    'od_gradient_motion_registered_blocks',
    function ( $blocks ) {
        $blocks['example/decoration'] = array(
            'label'  => 'Decoration',
            'target' => 'root',
        );

        return $blocks;
    }
);

add_filter(
    'od_gradient_motion_enabled_blocks',
    function ( $blocks ) {
        $blocks[] = 'example/decoration';

        return $blocks;
    }
);

登録情報は、ブロック名をキー、設定配列を値にします。

$blocks['namespace/block-name'] = array(
    'label'  => 'Block label',
    'target' => 'root',
);

現在対応している target は root のみです。label は連携内容を識別するための情報で、現時点のエディターUIには表示されません。

デフォルトのグループブロックを無効にする

有効ブロックの一覧から core/group を取り除きます。

add_filter(
    'od_gradient_motion_enabled_blocks',
    function ( $blocks ) {
        return array_values(
            array_diff( $blocks, array( 'core/group' ) )
        );
    }
);

すべてのブロックで機能を無効にする場合は、空の配列を返します。

add_filter( 'od_gradient_motion_enabled_blocks', '__return_empty_array' );

複数ブロックをまとめて有効にする

各ブロックは、先に od_gradient_motion_registered_blocks へ登録しておく必要があります。

add_filter(
    'od_gradient_motion_enabled_blocks',
    function ( $blocks ) {
        return array_merge(
            $blocks,
            array(
                'core/cover',
                'example/decoration',
            )
        );
    }
);

対応ブロックの条件

MVPでは、次の条件を満たすブロックを対象とします。

• ブロックのルートHTML要素に背景グラデーションが出力されること。
• ブロック名が登録済みブロックと有効ブロックの両方に含まれること。
• 保存時にルート要素を出力し、render_block フィルターで処理できること。

背景グラデーションが内部要素に設定されるブロックには対応していません。例えば、次の構造では .decoration__background を直接動かせないため、現在のMVPでは対象外です。

<div class="wp-block-example-decoration">
    <div class="decoration__background"></div>
</div>

内部要素を指定するセレクターやAdapter APIは、将来の拡張候補です。

保存属性と出力

有効化したブロックには、次の属性が保存されます。

属性	型	デフォルト	内容
odGradientMotionEnabled	boolean	false	アニメーションの有効状態
odGradientMotionDuration	number	10	1周期の秒数。出力時に1〜60へ制限されます。
odGradientMotionAnimation	string	horizontal	アニメーション種類。horizontal、vertical、diagonal、shiftから選択します。
odGradientMotionDirection	string	normal	再生方向。normal、reverse、alternateから選択します。
odGradientMotionPreset	string	空文字	エディターで選択中のプリセット。フロントエンドの描画には使用しません。

アニメーション種類や再生方向に不正な値が保存されている場合は、それぞれ horizontal と normal に戻します。新しい属性を持たない既存ブロックも同じデフォルト値で表示されます。

フロントエンドでは、対象ブロックのルート要素へ次の値が追加されます。

<div
    class="wp-block-group od-gradient-motion od-gradient-motion--horizontal od-gradient-motion--direction-normal"
    style="--od-gradient-motion-duration:10s;"
></div>

アニメーションはCSSのみで実行されます。フロントエンドでJavaScriptを実行する必要はありません。

背景の拡大率を変更する

アニメーション中の背景サイズは、デフォルトで 400% 400% です。WordPressやブロックテーマがインラインの background 一括指定を出力してもアニメーションが成立するよう、専用クラスの background-size は !important で適用されます。

ブロックごとに拡大率を変更する場合は、--od-gradient-motion-background-size を指定してください。

.my-custom-block {
    --od-gradient-motion-background-size: 250% 250%;
}

この指定はアニメーションを有効にしたブロックだけに作用します。アニメーションを無効にすると専用クラスが外れ、ブロック本来の背景サイズへ戻ります。

トラブルシューティング

設定パネルが表示されない

• ブロック名が od_gradient_motion_registered_blocks に登録されているか確認してください。
• 同じブロック名が od_gradient_motion_enabled_blocks に含まれているか確認してください。
• フィルターを init 後に追加していないか確認してください。
• ブロック名が namespace/block-name 形式の実際の登録名と一致しているか確認してください。

有効にしても背景が動かない

• WordPress標準の背景グラデーションが設定されているか確認してください。
• グラデーションがブロックのルート要素へ出力されているか確認してください。
• OSやブラウザで「視差効果を減らす」が有効な場合、prefers-reduced-motion によりアニメーションは停止します。

リリース

1. od-gradient-motion.php と package.json のバージョンを更新します。
2. v1.2.3 形式のタグを push します。
3. GitHub Actions が od-gradient-motion.zip を生成し、同じタグのGitHub Releaseに添付します。

プラグインの updater は、検出したリリースタグに対応する od-gradient-motion.zip をWordPress管理画面からインストールします。