lucide-icons

Rails 中的 Lucide 图标

通过 lucide-rails gem 将 Lucide 图标渲染为内联 SVG。图标使用 currentColor，因此会自动继承文本颜色。

何时使用此技能

• 在 Rails 视图中添加图标（按钮、导航、徽章、空状态）
• 为 UI 元素选择合适的 Lucide 图标名称
• 确保图标具有可访问性（装饰性图标与交互式图标）
• 使用 CSS 为 SVG 图标设置样式或尺寸

理念

1. 图标通常只是装饰 — 装饰性图标无需标签。交互式图标（按钮、链接）必须带有可访问文本。
2. 有意设置尺寸 — 始终传入 size:。默认的 24px 对大多数内联场景来说都太大。
3. 让 CSS 处理颜色 — 图标会继承 currentColor。为父元素设置样式，而不是 SVG。
4. 使用辅助方法，绝不直接写 SVG — lucide_icon 可确保图标保持一致、可缓存且可更新。
5. 仅使用 kebab-case 名称 — 应为 "chevron-right"，而不是 "chevronRight" 或 "ChevronRight"。

安装

# Gemfile
gem "lucide-rails"

bundle install

无需 JavaScript、导入映射或资源管线配置。该 gem 提供了一个用于渲染内联 SVG 的 Ruby 辅助方法。

基本用法

<%= lucide_icon "home", size: 18 %>

渲染结果：

<svg width="18" height="18" viewBox="0 0 24 24" fill="none"
     stroke="currentColor" stroke-width="2"
     stroke-linecap="round" stroke-linejoin="round">
  <path d="..."></path>
</svg>

辅助方法参数

参数	默认值	描述
size	24	宽度和高度（像素）
class	nil	CSS 类
stroke_width	2	描边宽度（通常为 1–3）

<%= lucide_icon "home", size: 16, class: "text-muted" %>
<%= lucide_icon "home", size: 24, stroke_width: 1.5 %>

所有其他 HTML 属性都会传递给 <svg> 元素：

<%= lucide_icon "copy", size: 14, data: { action: "click->clipboard#copy" } %>
<%= lucide_icon "x", size: 18, aria: { label: "Close" } %>

尺寸指南

根据使用场景选择尺寸。确保每种场景中的尺寸保持一致。

场景	尺寸	适用情况
徽章、内联标签	12px	空间紧凑、文本较小
关闭/关闭按钮、内联操作	14px	搭配正文文本
带文本的按钮	16px	最常见的操作尺寸
导航侧边栏	18px	导航链接、菜单项
卡片/列表项图标	20px	内容类型指示图标
空状态、主视觉区域	32–48px	大型装饰性图标

使用 CSS 设置样式

颜色继承

图标使用 currentColor 描边，因此会继承父元素的 color：

.nav-link { color: var(--color-muted); }
.nav-link:hover { color: var(--color-default); }
/* Icon color changes automatically on hover */

直接设置图标样式

需要为图标单独设置颜色时，可在父元素或图标包装元素上使用实用类：

.text-success { color: var(--color-positive); }
.text-danger  { color: var(--color-negative); }
.text-warning { color: var(--color-warning); }
.text-muted   { color: var(--color-muted); }

<span class="text-success"><%= lucide_icon "check", size: 14 %></span>
<span class="text-danger"><%= lucide_icon "alert-circle", size: 14 %></span>

描边宽度

较细的描边在较大尺寸下看起来更精致。较粗的描边在较小尺寸下更清晰。

<%= lucide_icon "settings", size: 48, stroke_width: 1.5 %>  <%# Large, elegant %>
<%= lucide_icon "check", size: 12, stroke_width: 2.5 %>     <%# Small, readable %>

深色模式

由于图标使用 currentColor，文本颜色适配深色模式时，图标也会随之适配。如果你的颜色系统使用 CSS 自定义属性，则无需额外处理。

常见模式

图标 + 文本按钮

<button class="btn btn-primary">
  <%= lucide_icon "plus", size: 16 %>
  Create Project
</button>

.btn {
  display: inline-flex;
  align-items: center;
  gap: 0.5rem;
}

纯图标按钮

<button class="btn-icon" aria-label="Close">
  <%= lucide_icon "x", size: 18 %>
</button>

.btn-icon {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  padding: 0.5rem;
}

纯图标按钮必须带有 aria-label。

导航链接

<%= link_to dashboard_path, class: "nav-link" do %>
  <%= lucide_icon "layout-dashboard", size: 18 %>
  Dashboard
<% end %>

带图标的徽章

<span class="badge">
  <%= lucide_icon "lock", size: 12 %>
  Restricted
</span>

.badge {
  display: inline-flex;
  align-items: center;
  gap: 0.25rem;
}

空状态

<div class="empty-state">
  <%= lucide_icon "folder-plus", size: 48, stroke_width: 1.5 %>
  <h3>No projects yet</h3>
  <p>Create your first project to get started.</p>
</div>

.empty-state {
  text-align: center;
  padding: 3rem 1rem;
}
.empty-state svg {
  color: var(--color-muted);
  margin-bottom: 1rem;
}

链接中的图标（Turbo）

<%= link_to edit_post_path(@post), class: "action-link", data: { turbo_frame: "post_form" } do %>
  <%= lucide_icon "edit", size: 14 %>
  Edit
<% end %>

Stimulus 集成

<button data-controller="clipboard" data-action="click->clipboard#copy"
        data-clipboard-text-value="<%= @invite_url %>">
  <%= lucide_icon "copy", size: 14 %>
  Copy Link
</button>

可访问性

规则：装饰性与有意义的图标

装饰性 — 图标伴随可见文本。无需额外标记：

<button>
  <%= lucide_icon "plus", size: 16 %> Add Item
</button>

有意义 — 图标是唯一内容。必须添加可访问文本：

<%# Option 1: aria-label on the interactive element %>
<button aria-label="Close" class="btn-icon">
  <%= lucide_icon "x", size: 18 %>
</button>

<%# Option 2: sr-only span %>
<button class="btn-icon">
  <%= lucide_icon "x", size: 18 %>
  <span class="sr-only">Close</span>
</button>

仅供屏幕阅读器使用的类

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

SVG 默认设为 aria-hidden

lucide_icon 辅助方法渲染的 SVG 会被屏幕阅读器跳过。这是正确的做法 — 可访问名称应添加到交互式父元素上，而不是图标上。

常见使用场景的图标

导航

图标名称	用途
home	首页/仪表板
layout-dashboard	仪表板/概览
settings	设置
users	团队/人员
file-text	文档/页面
log-out	登出
log-in	登录
menu	汉堡菜单
search	搜索

操作

图标名称	用途
plus	创建/添加
edit	编辑/修改
trash	删除
copy	复制到剪贴板
x	关闭/取消
check	确认/保存
eye	查看/预览
eye-off	隐藏
download	下载
upload	上传
external-link	在新标签页中打开

箭头和尖括号

图标名称	用途
arrow-left	返回
arrow-right	前进
chevron-down	展开/下拉
chevron-right	下一步/深入查看
chevron-up	收起
arrow-up-right	外部/外链

状态和反馈

图标名称	用途
check-circle	成功
alert-circle	错误
alert-triangle	警告
info	信息
help-circle	帮助
loader	加载中（使用 CSS 添加动画）
lock	受限/私有
unlock	公开/开放

通信

图标名称	用途
mail	电子邮件
bell	通知
message-circle	聊天/评论
megaphone	公告
send	发送消息

文件和内容

图标名称	用途
file	通用文件
file-text	文档
folder	文件夹/类别
folder-plus	新建文件夹
image	图像/照片
video	视频
link	链接/URL

社交和其他

图标名称	用途
github	GitHub
twitter	Twitter/X
globe	网站/世界
calendar	日期/日程
clock	时间/历史记录
star	收藏
heart	点赞
filter	筛选
sort-asc	升序排序
sort-desc	降序排序

反模式

1. 图标名称大小写错误 — "chevronRight" → 应使用 "chevron-right"（始终使用 kebab-case）
2. 未指定大小 — 不要依赖默认的 24px。请明确指定：size: 16
3. 直接使用原始 <svg> 或 <img> 标签 — 始终使用 lucide_icon 辅助方法
4. 直接设置 SVG 样式 — 应设置父元素的 color，而非 SVG 的 stroke
5. 仅含图标的按钮未设置 aria-label — 屏幕阅读器无法描述该按钮
6. 大小不一致 — 为每种使用场景选定一个大小，并保持一致
7. 图标种类过多 — 在应用中，同一概念应重复使用同一个图标
8. 含义不明确时只用图标而不显示文字 — 铅笔图标可能表示“编辑”或“书写”。请添加文字或工具提示。

查找图标

在 lucide.dev/icons 浏览完整的图标库。

搜索提示：

• 按概念搜索：“arrow”“file”“user”“check”
• 图标名称具有描述性：使用 circle-check，而不是 checkmark-in-circle
• 相关图标共享前缀：file、file-text、file-plus、file-x
• 如果 lucide-rails 中不存在某个图标，辅助方法会在渲染时引发错误

参考

有关详细模式、边缘情况和高级用法，请参阅 reference.md。