主题悬停卡片

[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
  控制缩略图大小占悬停卡片渲染尺寸的百分比。

各视口显示字段

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

• 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

计划中但尚未添加的设置与功能：

• 排除特定标签
• 包含特定标签
• 排除特定类
• 包含特定类
• 默认排除 OneBoxes 及其他元素
• 建议功能？？

[chapoi]

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