Lucide 中文文档

Appearance

Lucide ​

核心的 Lucide 包，适用于纯 JavaScript 应用。该包让您可以轻松地在任何 Web 项目中添加可缩放矢量图标，而无需框架依赖。非常适合静态网站、遗留应用或需要轻量化图标集成并兼容最大浏览器的场景。

您可以实现的功能：

  • 使用简单的数据属性将图标添加到 HTML
  • 动态创建并通过 JavaScript 插入 SVG 图标
  • 使用 CSS 类和内联样式自定义图标外观
  • Tree-shake 未使用的图标以保持包大小最小
  • 在任何 JavaScript 环境或纯 HTML 中使用图标

安装 ​

包管理器 ​

sh
pnpm install lucide
sh
yarn add lucide
sh
npm install lucide
sh
bun add lucide

CDN ​

html
<!-- 开发版 -->
<script src="https://unpkg.com/lucide@latest/dist/umd/lucide.js"></script>

<!-- 生产版 -->
<script src="https://unpkg.com/lucide@latest"></script>

使用 ​

使用 unpkg ​

以下是使用 unpkg 的完整示例

html
<!DOCTYPE html>
<body>
  <i data-lucide="volume-2" class="my-class"></i>
  <i data-lucide="x"></i>
  <i data-lucide="menu"></i>

  <script src="https://unpkg.com/lucide@latest"></script>
  <script>
    lucide.createIcons();
  </script>
</body>

使用 ESModules ​

为减小包体积，lucide 采用完全可 Tree-shake 化的构建。 createIcons 函数会搜索带 data-lucide 属性的 DOM 元素，并用相应图标的 SVG 替换之。

html
<!-- 您的 HTML 文件 -->
<i data-lucide="menu"></i>
js
import { createIcons, icons } from 'lucide';

// 注意，这将导入所有图标并打包。
createIcons({ icons });

// 推荐方式，只包含所需图标。
import { createIcons, Menu, ArrowRight, Globe } from 'lucide';

createIcons({
  icons: {
    Menu,
    ArrowRight,
    Globe
  }
});

高级用法 ​

其他选项 ​

在 createIcons 函数中，您可以传入一些额外参数：

  • 可以传入 nameAttr 来调整用来替换的属性名称
  • 可以传入 attrs 来传递额外的自定义属性，例如 CSS 类或描边选项
  • 可以传入 root 指定自定义 DOM 元素，图标将在其中被替换（当操作大型 DOM 片段或 Shadow DOM 的元素时非常有用）
  • 可以传入 inTemplates: true，以在 <template> 标签内替换图标

以下是完整示例：

js
import { createIcons } from 'lucide';

createIcons({
  attrs: {
    class: ['my-custom-class', 'icon'],
    'stroke-width': 1,
    stroke: '#333'
  },
  nameAttr: 'data-lucide', // 图标名称的属性
  root: element, // 要替换图标的 DOM 元素
  inTemplates: true // 同时替换 <template> 标签内的图标
});

Tree-shake 库，只使用所需图标 ​

js
import { createIcons, Menu, ArrowRight, Globe } from 'lucide';

createIcons({
  icons: {
    Menu,
    ArrowRight,
    Globe
  }
});

自定义 Document 根 ​

在自定义根元素（例如 Shadow DOM 根）中应用图标。

js
import { createIcons } from 'lucide';

// 自定义根元素，例如 Shadow DOM 根
const shadowRoot = element.attachShadow({ mode: 'open' });

createIcons({
  root: shadowRoot
});

应用 <template> 标签内的图标 ​

默认情况下 <template> 标签内的图标不会被添加。通过将 inTemplates 选项设为 true，模板中的图标也会被替换。

js
import { createIcons } from 'lucide';

createIcons({
  inTemplates: true
});

自定义元素绑定 ​

js
import { createElement, Menu } from 'lucide';

const menuIcon = createElement(Menu); // 返回 HTMLElement（svg）

// 在 DOM 中插入 HTMLElement
const myApp = document.getElementById('app');
myApp.appendChild(menuIcon);

自定义元素绑定及自定义属性 ​

js
import { createElement, Menu } from 'lucide';

const menuIcon = createElement(Menu, {
  class: ['my-custom-class', 'icon'],
  'stroke-width': 1,
  stroke: '#333'
}); // 返回 HTMLElement（svg）

// 在 DOM 中插入 HTMLElement
const myApp = document.getElementById('app');
myApp.appendChild(menuIcon);

使用 Lucide lab 或自定义图标 ​

Lucide lab 是不属于 Lucide 主库的图标集合。它们可以与官方图标以相同的方式使用。

js
import { coconut } from '@lucide/lab';

createIcons({
  icons: {
    coconut
  }
});