SWELL│スクロールヒント（scroll-hint.js）を表示するカスタマイズ

2023.07.302026.10.21

scroll-hint.jsで、横スクロールできる表に操作のヒントを付ける例です。

SWELLには標準のスクロール案内もあるため、標準表示で足りる場合は追加不要です。

ここでは指定した容器だけに適用し、本文の文言やサイト全体の矢印は消しません。

対象の表を用意する

まず検証用ページのカスタムHTMLブロックへ次を貼り付けます。

waza-scroll-hintがスクロール容器です。

表の内容とaria-labelは実際の用途に合わせて変更してください。

操作方法はアイコンだけでなく文章でも伝えます。

<p>表は横にスクロールできます。キーボードでは表の枠を選択して左右キーを押します。</p>
<div class="waza-scroll-hint" tabindex="0" role="region" aria-label="プラン比較表（横スクロール）">
  <table><caption>比較表のサンプル</caption>
    <thead><tr><th scope="col">項目</th><th scope="col">プランA</th><th scope="col">プランB</th><th scope="col">プランC</th></tr></thead>
    <tbody><tr><th scope="row">利用人数</th><td>1人</td><td>5人</td><td>10人</td></tr></tbody>
  </table>
</div>

専用CSSを追加する

追加CSSまたは子テーマのstyle.cssへ貼り付けます。

600pxはこの比較表の例なので、内容に合わせて変更します。

指定クラスの外の表には適用しません。

.waza-scroll-hint { overflow-x:auto; overflow-y:hidden!important; padding-bottom:1rem; max-width:100%; }
.waza-scroll-hint:focus-visible { outline:3px solid #075aab; outline-offset:2px; }
.waza-scroll-hint > table { min-width:600px; width:100%; border-collapse:collapse; }
.waza-scroll-hint th, .waza-scroll-hint td { border:1px solid #888; padding:.75em; }

ライブラリの後で初期化する

子テーマのfunctions.phpをバックアップし、既存PHPの内側へ以下を追加します。

PHPスニペット管理プラグインを使う場合はそちらだけに登録します。

旧記事のadd_scroll_hint・motoki_scrollhint・motoki_columns_schroll_hint・motoki_scrollhint_arrowとそれぞれの登録行は置き換えてください。

function waza_enqueue_scroll_hint() {
    wp_enqueue_style('waza-scroll-hint', 'https://unpkg.com/scroll-hint@1.1.10/css/scroll-hint.css', array(), '1.1.10');
    wp_enqueue_script('waza-scroll-hint', 'https://unpkg.com/scroll-hint@1.1.10/js/scroll-hint.js', array(), '1.1.10', true);
    wp_add_inline_script('waza-scroll-hint', <<<'WAZA_HINT'
(() => {
    const init = () => {
        if (!document.querySelector('.waza-scroll-hint')) return;
        if (typeof ScrollHint !== 'function') return;
        new ScrollHint('.waza-scroll-hint', {i18n:{scrollable:'横にスクロールできます'}});
    };
    if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', init, {once:true});
    else init();
})();
WAZA_HINT
    , 'after');
}
add_action('wp_enqueue_scripts', 'waza_enqueue_scroll_hint');

例では既存記事と同じ1.1.10を明示しています。

最新版であるという意味ではありません。

外部CDNから読み込むので利用者のブラウザはunpkg.comへ接続します。

ヒント用JSを取得できなくても、専用CSSが適用されていれば表を横スクロールできます。

表の前の操作説明もHTMLとして残ります。

サンプルはフロント画面でファイルを読み込み、対象クラスがあるときだけ初期化します。対象がないページでもJS・CSSは読み込むコードです。初回のDOM構築時を対象とし、後からAjax等で追加する表の再初期化は含みません。

wp_add_inline_scriptのafterでライブラリの出力後に初期化コードを置きます。

高速化プラグインが実行順を変更する場合は別途確認が必要です。

オプションはScrollHintの公式リポジトリを参照してください。

左右キーで操作できる比較表

下の表は上のHTML・CSSと同じ構成の公開見本です。

枠へTabで移動して左右キーを押すと表を横へ送れます。

幅の狭い画面ではスクロールヒントが表示されます。

スマホ幅でもページ全体を横へ動かす必要はありません。

表は横にスクロールできます。キーボードでは表の枠を選択して左右キーを押します。

比較表のサンプル
項目	プランA	プランB	プランC
利用人数	1人	5人	10人

SWELLの既存ブロックに適用するとき

横スクロールを担当している要素にクラスを付けます。

リッチカラムの外枠と内側のスクロール要素は同じとは限りません。

まず上の単独表で確認し、既存ブロックへ応用するときはoverflowと実際に動く要素を確認してください。

入れ子の全カラムへ一括適用しません。

標準の案内と重なる場合は、対象ブロックの設定で標準案内を調整します。

本文全体から「スクロールできます」を文字列置換で削除したり、.icon-more_arrow全体を非表示にしたりしないでください。

リッチカラムのスクロール要素へ適用する

SWELL 2.19.0では、リッチカラムの外枠ではなくswell-block-columns__innerが横へ動きます。

リッチカラムの「横スクロール」を有効にし、項目の幅を240pxへ設定します。

ブロックの「高度な設定」のHTMLアンカーへwaza-hint-columnsを指定してください。

次のPHPはWordPress 6.2以降のWP_HTML_Tag_Processorを使います。クラスを利用できない旧環境へそのまま追加しないでください。上の読み込み用PHPと一緒に追加すると、指定アンカーを持つ横スクロール用カラムの内側へ専用クラス・Tab操作・読み上げ用の名前を付けます。

アンカー名はこの例1か所に使い、別のカラムへ重複させません。

function waza_rich_column_scroll_hint($content, $block) {
    if (($block['attrs']['anchor'] ?? '') !== 'waza-hint-columns'
        || empty($block['attrs']['isScrollable'])) {
        return $content;
    }
    $html = new WP_HTML_Tag_Processor($content);
    if (!$html->next_tag(array('class_name' => 'swell-block-columns__inner'))) {
        return $content;
    }
    $html->add_class('waza-scroll-hint');
    $html->set_attribute('tabindex', '0');
    $html->set_attribute('role', 'region');
    $html->set_attribute('aria-label', 'リッチカラムの項目一覧（横スクロール）');
    return $html->get_updated_html();
}
add_filter('render_block_loos/columns', 'waza_rich_column_scroll_hint', 20, 2);

次のCSSも専用CSSの末尾へ加えます。

標準の案内を隠すのは指定アンカーの直下だけです。

CDNの案内が出ない場合でも操作方法が分かるよう、カラムの前に「項目は横にスクロールできます。枠へTabで移動して左右キーを押してください。」という段落を残します。

キーボード操作は、本文全体ではなくスクロール枠へフォーカスして行います。

案内文は、JavaScriptが動かない場合にも読み取れる通常の段落にします。

#waza-hint-columns > .c-scrollHint { display:none; }
#waza-hint-columns > .swell-block-columns__inner { margin-left:0; }
#waza-hint-columns > .swell-block-columns__inner:focus-visible { outline-offset:-3px; }

下はSWELLのリッチカラムブロックで作った3項目の見本です。

比較表の外枠とは別に、実際に横へ動く内側の枠へフォーカスします。

項目は横にスクロールできます。

枠へTabで移動して左右キーを押してください。

スクロールできます

項目A

最初の項目です。狭い画面では右キーで次へ送れます。

項目B

中央の項目です。左キーで最初の項目へ戻れます。

項目C

最後の項目です。ページ全体の幅は広げません。

SWELLのリッチカラムをスマホ幅で表示し、横スクロールする内側の枠へキーボードフォーカスを移した画面 — 2026年10月2日撮影。公開ページのスマホ表示。Tabで内側のスクロール枠へ移動すると青い枠が表示され、左右キーで項目を移動できます。

確認と戻し方

PC・スマホ幅で表のはみ出す場合だけヒントが出ること、枠へTabで移動して左右キーでスクロールできることを確認します。

表が収まる広い画面ではスクロール用アイコンは不要です。

戻す場合は追加したPHP関数・登録行・専用CSSを外し、カスタムHTMLを変更前の表へ戻します。

リッチカラムの例を戻す場合は追加したrender_block用の関数・filter登録・専用CSSを外し、カラムのHTMLアンカーを元へ戻します。

標準の横スクロール設定と案内が残ることを確認してください。

旧例はGitHubの過去コードに残っています。

今回の限定適用版とは異なります。

SWELL検証環境の390px幅。比較表の上に横スクロールの案内が表示された状態。実際に掲載コードを適用して撮影しました。

旧コードが残っている場合

「スクロールできます」が本文から消える、対象外の表やカラムにも案内が付く場合は、以前のPHP登録を確認します。

本稿の関数へ置き換える際は、旧関数とadd_action・add_filterも一緒に外します。

旧関数を残したまま追加すると、ライブラリの二重読み込みや本文の文字列置換が続きます。

WAZAの公開見本では、このページに限定していた既存スニペットを専用クラス版へ置き換えました。

本文の文字列置換と、全テーブル・全カラムへのクラス追加をやめています。

比較表に付く案内は1件です。

リッチカラムの追加例では指定アンカーの標準案内だけをCSSで隠し、本文の操作説明は保持します。

公開見本の操作確認

2026年10月2日、公開見本でライブラリとヒントが各1件であることを確認しました。

1280px幅では表が枠内に収まり、390px幅では右キーで表を40px横へ送れます。

青いフォーカス枠、表の最終行、本文の案内文も表示されます。

この時点の確認対象は比較表です。

リッチカラムの見本は別途追加しています。

その後、10月3日にヒント用JSだけを404にする専用条件で、CSSによる横スクロールが残ることを確認しました（次節）。

公開CDN全体の障害、編集画面での保存・再表示、実機のタッチ操作、WP Rocketとの併用は未検証です。

スマホ幅で比較表の枠を選択した公開見本。横へ送る前のスクロールヒントと青いフォーカス枠。 — 2026年10月2日撮影。SWELL 2.19.0、scroll-hint 1.1.10、390px幅。横へ送る前の状態。

ヒント用JSを取得できなくても表を操作できるか確認する

切り分け	見る結果
ヒント用JSを取得できない	ヒントを付ける処理が中断される
表の枠を選択して右キー	CSSによる横スクロールが残る
左キー	表の先頭へ戻れる

ヒント用ライブラリは案内を補うためのもので、表の横スクロール自体は専用CSSで設定します。

取得失敗時にも読めるよう、表の前に操作案内を置き、スクロール枠のtabindexとフォーカス表示を残します。

2026年10月3日、隔離したWordPress 7.1.2 / SWELL 2.19.0で、ヒント用JSだけがHTTP 404になる条件を用意しました。

PCの画面内に幅300pxの枠と幅600pxの表を配置し、右キーで横へ送り、左キーで先頭に戻れることを確認しました。

ヒントのアイコンはなく、表の枠には青いフォーカス表示が残りました。

これは専用の取得失敗条件での確認であり、公開CDNの実際の障害、CDN全体の遮断、スマホのタッチ操作を再現したものではありません。

導入先では開発者ツールのNetworkでJSとCSSを分けて確認し、ライブラリが取得できない場合でも表の末尾まで読めるかを試してください。

追加したヒント処理を停止しても、読み手が操作できるスクロール枠と案内文は残します。

ヒント用JavaScriptを取得できなくても右キーで横へ送れる比較表 — ヒント用JSを404にした条件で、右キー操作と青いフォーカス枠を確認。PC内の300px幅の枠です。2026年10月3日、隔離環境で撮影。

よくある質問：SWELLでスクロールヒント（scroll-hint.js）を表示するとき

SWELLには標準のスクロール案内がありますが、この方法は必要ですか？

記事では、SWELLには標準のスクロール案内もあるため、標準表示で足りる場合は追加不要です。この例は、scroll-hint.jsで、横スクロールできる表に操作のヒントを付けるものです。

どのブロックに適用されますか？

記事では、指定した容器だけに適用し、本文の文言やサイト全体の矢印は消しません。専用のクラス（waza-scroll-hint）がスクロール容器になり、指定クラスの外の表には適用しません。

コードは、どこに追加しますか？

記事では、CSSは追加CSSまたは子テーマのstyle.cssへ貼り付けます。子テーマのfunctions.phpをバックアップし、既存PHPの内側へライブラリ読み込み用のコードを追加します。PHPスニペット管理プラグインを使う場合はそちらだけに登録します。

ライブラリは、どこから読み込みますか？

記事では、外部CDNから読み込むので、利用者のブラウザはunpkg.comへ接続します。例では既存記事と同じ1.1.10を明示していますが、最新版であるという意味ではありません。

ヒント用のJSを取得できないと、表は操作できなくなりますか？

いいえ。記事では、ヒント用ライブラリは案内を補うためのもので、表の横スクロール自体は専用CSSで設定します。ヒント用JSを取得できなくても、専用CSSが適用されていれば表を横スクロールできます。取得失敗時にも読めるよう、表の前に操作案内を置き、スクロール枠のtabindexとフォーカス表示を残します。

キーボードでも、横スクロールできますか？

できます。記事では、表の枠を選択して左右キーを押します。Tabで内側のスクロール枠へ移動すると青い枠が表示され、左右キーで項目を移動できます。

SWELLのリッチカラムにも使えますか？

使えます。記事では、SWELL 2.19.0では、リッチカラムの外枠ではなくswell-block-columns__innerが横へ動くため、リッチカラムの「横スクロール」を有効にし、ブロックの「高度な設定」のHTMLアンカーにwaza-hint-columnsを指定します。アンカー名はこの例1か所に使い、別のカラムへ重複させません。

やってはいけないことや、旧コードが残っているときは？

記事では、本文全体から「スクロールできます」を文字列置換で削除したり、.icon-more_arrow全体を非表示にしたりしないよう案内しています。旧コードが残っていて、案内が消える、対象外の表やカラムにも案内が付く場合は、以前のPHP登録を確認し、旧関数とadd_action・add_filterも一緒に外します。なお、公開CDN全体の障害、編集画面での保存・再表示、実機のタッチ操作、WP Rocketとの併用は未検証です。