トピックホバーカード

カスタマイズ テーマコンポーネント
1
:information_source: 概要 内部トピックリンクにマウスを合わせたとき（モバイルではタップしたとき）に、リンク先のトピックの内容を素早くプレビューするツールチップ風のポップアップを表示します。
:eyeglasses: プレビュー Github Readme
:hammer_and_wrench: リポジトリ https://github.com/denvergeeks/discourse-topic-hover-cards
:question: インストールガイド テーマまたはテーマコンポーネントのインストール方法
:open_book: Discourse テーマが初めての方へ Discourse テーマの使い方の初心者ガイド

このテーマコンポーネントをインストール

トピック、返信、トピック一覧、カテゴリのホームページ、ドキュメントカテゴリ、カンバンボード、および推奨トピック全体にわたる内部トピックリンクに対するリッチなホバープレビューカード。デスクトップおよび/またはモバイルに対応。サイト全体で利用可能で、高度にカスタマイズ可能です。

image
image1203×696 132 KB

image
image1215×707 146 KB

機能

  • サイト全体で全ての内部トピックリンクに対して有効化するか、または以下の 1 つ以上のエリアに限定して有効化できます：
    • トピック本文（投稿元）
    • 返信
    • 標準的なトピック一覧（/latest、/top、/tags、カテゴリのトピック一覧など）
    • カテゴリのホームページのトピック一覧（カテゴリ＋最新、カテゴリのみ、関連レイアウトなど）
    • ドキュメントカテゴリの表示
    • カンバンスタイルのボード表示
    • 推奨トピック
  • レスポンシブレイアウト：
    • 設定可能な密度とサムネイル配置を持つデスクトップ用カード
    • タップで開くモバイル用ボトムシートプレビュー
  • カスタマイズ可能なコンテンツ：
    • サムネイル画像
    • カテゴリバッジ
    • タグ
    • タイトル
    • 抜粋（画像やライブライトは除去済み）
    • 投稿者
    • 公開日
    • 閲覧数、返信数、いいね数、最終活動
  • カスタムユーザーフィールドを使用したユーザーごとのオプトアウト
  • 安全なトラブルシューティングのための管理者専用デバッグモード
設定

レイアウトとタイミング

  • card_width
    デスクトップ用の任意の CSS 幅値。例：32rem、420px、40vw、clamp(20rem, 40vw, 36rem)。

  • card_max_height
    任意の CSS 最大高さ値。例：10rem、480px、50vh、min(60vh, 32rem)。

  • card_delay_ms
    ホバーカードを表示するまでの遅延時間（ミリ秒単位）。デフォルト：300。

  • enable_on_mobile
    有効化すると、サポートされている内部トピックリンクをタップすると、画面下部に固定されたモバイルプレビューシートが表示されます。

  • mobile_width_percent
    モバイルのボトムシートプレビューの幅をビューポート幅のパーセンテージで指定（デフォルト：100）。

  • mobile_thumbnail_height
    モバイルプレビュー用のサムネイルの高さ（ピクセル単位）。

密度

  • density
    デスクトップ密度：default、cozy、または compact。

  • density_mobile
    モバイル密度：default、cozy、または compact。

これらは Discourse の「密度」パターンに準拠しており、パディングと行間隔を調整します。

サムネイルと配置

  • show_thumbnail / show_thumbnail_mobile
    デスクトップおよびモバイルでトピック画像（存在する場合）を表示/非表示にします。

  • thumbnail_placement
    デスクトップでのサムネイルの配置方法：

    • top
    • left
    • right
    • bottom
      モバイルでは、サムネイルは常にカードの上部にレンダリングされます。

  • image_size_percent
    レンダリングされたホバーカードのサイズに対するサムネイルのサイズをパーセンテージで制御します。

ビューポートごとのフィールド

以下の各ブロックについて、デスクトップとモバイルの両方のトグルがあります：

  • show_category / show_category_mobile

  • show_tags / show_tags_mobile

  • show_title / show_title_mobile

  • show_excerpt / show_excerpt_mobile

  • excerpt_length / excerpt_length_mobile
    抜粋の行数（CSS の line-clamp を使用）。

  • show_op / show_op_mobile
    投稿者のアバターとユーザー名を表示します。

  • show_publish_date / show_publish_date_mobile

  • show_views / show_views_mobile

  • show_reply_count / show_reply_count_mobile

  • show_likes / show_likes_mobile

  • show_activity / show_activity_mobile

ホバーカードが表示される場所

  • enable_on_topics
    投稿元のトピック内のトピックリンク。

  • enable_on_replies
    返信内のトピックリンク。

  • enable_on_topic_lists
    標準的なトピック一覧（/latest、/top、カテゴリのトピック一覧など）内のトピックリンク。

  • enable_on_category_homepage_topic_lists
    カテゴリのホームページの「最新トピック」または同等の一覧内のトピックリンク：

    • カテゴリ＋最新トピック
    • カテゴリのみ
    • ホームページの構成に応じて / または /categories でレンダリングされる関連バリエーション。

  • enable_on_doc_categories
    ドキュメントカテゴリの表示内のトピックリンク（該当する場合）。

  • enable_on_kanban_boards
    カンバンスタイルのボードレイアウトでレンダリングされるトピックリンク（該当する場合）。

  • enable_on_suggested_topic_links
    「推奨トピック」セクション内のリンク。

ユーザーごとのオプトアウト

カスタムユーザーフィールドを使用して、個々のユーザーがホバーカードを無効化できるようにできます。これは、開発者ガイドで説明されている標準的なテーマ設定メカニズムと現在のユーザーへのデータアクセスを使用します。

  • user_preference_field_name
    現在のユーザーのオプトアウトを検出するために使用されるキー。以下が利用可能です：
    • 直接のカスタムフィールドキー（例：disable_topic_hover_cards）
    • 数値 ID（例：1）
    • user_field_X キー（例：user_field_1）

一致の仕組み

  1. コンポーネントはまず、現在のユーザーの custom_fields と user_fields を以下に対してチェックします：
    • 設定された user_preference_field_name
    • 適切な場合、1 と user_field_1 の間で変換された同じ値
  2. 一致が見つからず、現在のユーザーがスタッフ（管理者/モデレーター）で、resolve_user_field_id_for_admins が有効化されている場合、コンポーネントは以下を呼び出します：
    • /admin/config/user-fields.json
      設定された値（フィールド名または user_field_X）を数値 ID にマッピングします。
  3. 数値 ID を使用して、以下をチェックします：
    • user_fields[id]
    • user_fields['user_field_' + id]
    • custom_fields[id]
    • custom_fields['user_field_' + id]

これらの位置に真値（例：1、true、yes、on、checked）がある場合、そのユーザーのホバーカードは無効化されます。

この動作に関する設定

  • resolve_user_field_id_for_admins
    有効化（推奨）すると、管理者はフィールドを名前または user_field_X で設定でき、コンポーネントが自動的に数値 ID を解決して一致させます。

  • debug_mode
    有効化すると、スタッフ向けにブラウザのコンソールに詳細な検出情報をログ出力します。これには以下が含まれます：

    • チェックされたキー
    • 一致が見つかった場所（現在のユーザー vs 完全なユーザーレコード）
    • 解決された数値ユーザーフィールド ID（存在する場合）

デバッグ

ホバーカードが期待通りに表示されない場合は、組み込みのデバッグモードを使用してください：

  1. このコンポーネントの設定で debug_mode を有効にします。
  2. ブラウザの開発者コンソールを開きます。
  3. 関連するトピックリンクにマウスを合わせたりタップしたりします。

以下のようなメッセージが表示されます：

  • Hover cards initialized – 初期化と有効化された場所の確認。
  • Resolved admin user-field mapping – 設定されたユーザーフィールド名/キーの数値 ID へのマッピングの確認（スタッフ向け）。
  • No disable field match found anywhere – 現在のユーザーに対してホバーカードが抑制されていないことの確認。

カードが表示される場所をデバッグするには、以下を確認してください：

  • ターゲットリンクが topicIdFromHref() で解析可能な内部トピックリンク（/t/...）であること
  • 関連する場所フラグが有効化されていること：
    • enable_on_topics
    • enable_on_replies
    • enable_on_topic_lists
    • enable_on_category_homepage_topic_lists
    • enable_on_doc_categories
    • enable_on_kanban_boards
    • enable_on_suggested_topic_links

今後の設定と機能（未実装）：

  • 除外タグ
  • 含めるタグ
  • 除外クラス
  • 含めるクラス
  • OneBox などをデフォルトで除外
  • 提案機能？?
「いいね！」 6
2

動作するプレビューリンクや、実際の様子がわかるスクリーンショットを追加していただけますか？

「いいね！」 9