埋め込み型CMS納品で出会った全つまずき – NPC
スキルマーケット経由で「自作HTMLを納品してください」という依頼、わりとよく来ます。仕様としてはシンプル。クライアントのサイトに <style> と <script> を含むHTMLブロックを貼り付ければOK、というやつ。
自分も最近、料金計算機系のHTMLを埋め込み型CMSに納品する案件をやりました。ローカルで動作確認して「よし、完成」と思ってクライアントに渡したら、本番で全然違う動きになって慌てて修正する流れになり、結局 v1 → v2 → v3 と3バージョン作り直しました。
最初のやり取りで、作ってもらったhtmlから部分的にパーツを管理画面で貼り付けて使うと言う旨を話してくれれば気づきやすいですが、ほとんどの方はあまり意識されていないのか、話してくれません。同じところでつまずく人を減らしたいので、自分がこの納品スタイルで出会ったつまずきを全部書いておきます。
埋め込み型CMSの納品が普通のWeb制作と違うところ
普通のWeb制作なら、自分でテンプレートやCSSをコントロールできる。WordPressのテーマ開発であれば、親要素から子要素まで全部自分の管轄なので、layoutが壊れたら自分のCSSを疑えば済む。
でも埋め込み型CMSは違います。クライアント側のサイトはすでに完成していて、そこに自分のHTMLが「島」として埋め込まれる。つまり 自分のHTMLは、サイト側のテーマCSSの内側に内包される という構造になります。
- サイト側のテンプレート(自分は触れない)
- 固定ヘッダー(position: fixed)
- 記事コンテナ(overflow: hidden)
- 埋め込み枠ここに自分のHTMLが入る
- 自分の <style>
- 自分の <div> <script>
この「祖先要素のCSSが効いてくる」点を見落とすと、本番反映後に修正の往復が長引きやすくなります。
つまずき①:position: sticky が本番で機能しない
合計金額バーを画面上部に追従させたい、というよくあるUIで position: sticky; top: 0; を書いたら、ローカルでは動いたのに本番では普通の通常フローのまま貼り付かない。
原因は、サイト側のCSSに .articleBox { overflow: hidden; } が入っていたことでした。stickyには発動の前提条件があって、祖先のどれかに以下のCSSが当たっていると無効化されます。
overflow: hidden / auto / scrolltransform/filter/perspective/will-changecontain: paint / layout / strict
これは仕様通りなんですが、自分のHTMLしか見ていないと気づきません。サイト側のCSSは自分で書いたわけじゃないから完全に見落としやすいところです。
つまずき②:is-stuck切替方式はiOSの慣性スクロールで思わぬ動きをする
「stickyが効かないなら scroll イベントで監視して is-stuck クラスを付け外しすればいい」と思って自前実装したのが第2のつまずきでした。
iOS Safari にはフリック慣性スクロール(指を離した後も慣性で滑り続けるアレ)の途中で scrollイベントが間引かれる 仕様があります。そうすると is-stuck 付与が間に合わず、バーが画面外に取り残される瞬間が発生する。
「じゃあ IntersectionObserver で sentinel 要素の交差を監視すれば」と切り替えたら、今度はラバーバンドオーバースクロール(画面端で引っ張ると伸びるやつ)でラベルがコンテンツと一緒に下にずれました。さらに relative ⇄ fixed の切替境界でガビガビ振動も発生。
結論として、自分が辿り着いた最終形はこれです。
- 慣性スクロールでイベント間引き
- ラバーバンドでずれる
- 切替境界で振動
- 切替がないので振動ゼロ
- 慣性スクロールに影響されない
- 親要素にpadding-topでスペーサー確保
「stickyっぽく見せる」よりも「最初から fixed で固定する」ほうが、モバイル含めて全然安定します。バーの高さぶんだけ親コンテナに padding-top を JSで動的計算して入れておけば、レイアウト崩れもありません。
つまずき③:本番で確認しようとすると修正の往復が増える
これは技術じゃなくて検証フローの話です。最初は「修正版をクライアントに渡す → 貼り替えてもらう → 確認 → またずれてる → 修正版を渡す」というループをやっていました。クライアントは管理画面に毎回ログインして貼り替える必要があって、こちらは確認のたびに先方の手を煩わせることになる。お互いの手間が増えてしまう流れです。
これを断ち切ったのが、自家サーバーへのミラーリングでした。手順はシンプル。
SiteSucker は Mac用のサイト一括ダウンロードツールで、CSS や JS も込みで取ってきて相対パスに変換してくれます。これを自分のテストドメインに置けば、本番と完全に同じ祖先構造(ヘッダーの fixed や記事コンテナの overflow:hidden 等)で動作確認ができる。
注意点として、ミラーには必ず X-Robots-Tag: noindex, nofollow を入れること。htaccessでまとめて設定するのが楽です。クライアントのページが自分のドメインで検索インデックスされたら重大なトラブルになります。
納品前にチェックするポイント
埋め込み納品案件で見積もりを出すとき、自分は最近こういうチェックを最初にやるようになりました。
curl で取って、overflow / position / transform を全部洗い出す埋め込み納品は「自分のHTMLだけ動けばOK」と思って組むと想定外の修正が積み重なります。自分は v1 から v3 までの試行錯誤を経て、結局「最初から常時fixed」「自家サーバーで本番ミラー検証」「戻し用ファイル同梱」の3点セットが鉄則だと確信しました。これから埋め込みCMSへの納品案件を受ける人の参考になればうれしいです。
※この記事はNPCの中の人の実務経験をもとに書いています。