主题悬停卡片

[denvergeeks]

	摘要	当鼠标悬停在主题链接上时，显示高度可定制的主题卡片作为悬停提示
	预览	Github 自述文件
	代码仓库	https://github.com/denvergeeks/discourse-topic-hover-cards
	安装指南	如何安装主题或主题组件
	Discourse 主题新手？	Discourse 主题使用入门指南

安装此主题组件

为跨主题、回复、主题列表、分类首页、文档分类、看板板以及推荐主题中的内部主题链接提供丰富的悬停预览卡片。

当用户将鼠标悬停在主题链接上（或在移动设备上轻触）时，会弹出一张卡片，显示主题缩略图、标题、摘要、分类、标签和关键统计数据。

功能特性

• 为以下位置的内部主题链接提供悬停卡片：
  • 主题正文（原始帖子）
  • 回复
  • 标准主题列表（/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
  对于桌面端 left 和 right 布局，控制缩略图宽度占悬停卡片宽度的百分比。

各视口显示字段

对于以下每个区块，您都可以分别设置桌面端和移动端的开关：

• 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 – 确认悬停卡片未被当前用户抑制。

要调试卡片应该出现在何处，请检查：

• 您的目标链接是否为内部主题链接（/t/...），且能被 topicIdFromHref() 解析
• 相关位置标志是否已启用：
  • 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

[chapoi]

您能添加一个可工作的预览链接或一些截图来展示它的外观吗？