lucide-react-taro

Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

lucide-react-taro 是 Lucide 图标库的 Taro 适配版本，专为 Taro 微信小程序和 Web 平台设计。

渲染原理（微信小程序端）

在微信小程序环境中，图标并非通过原生的 <svg /> 标签进行渲染。为了兼容小程序平台，底层会将 SVG 转换为 data:image/svg+xml 格式的字符串，并交由 @tarojs/components 的 <Image /> 组件来展示（实现入口：src/create-icon.tsx 的 createIcon）。

基于上述实现原理，请注意以下几点：

传入的 className 仅会作用于外层的 <Image /> 组件，通常只能用于控制布局、外边距、对齐等样式，无法穿透修改内部 SVG 的线条（stroke）或填充（fill）。
因此，无法通过类似 text-* 这样的文本颜色类名来更改图标颜色。若需调整图标颜色，请直接使用组件提供的 color 属性。

安装

bash

npm install lucide-react-taro
# or
pnpm add lucide-react-taro

基础用法

✅ 正确示例（用 color/size/strokeWidth，以及可选的 style 覆盖尺寸）

tsx

import { House, Settings, Camera, Zap, Heart } from 'lucide-react-taro';

function MyComponent() {
  return (
    <View>
      <House />
      <Settings size={32} />
      <Camera color="#ff0000" />
      <Zap size={48} color="#1890ff" strokeWidth={1.5} absoluteStrokeWidth />
      <Heart filled color="#ff3e98" />
      <House className="my-icon" style={{ marginRight: 8 }} />
    </View>
  );
}

❌ 错误示例（className 的 text-* 不会改变 icon 的 stroke/fill；它只是 <Image /> 的 class）

tsx

import { House } from 'lucide-react-taro';

function MyComponent() {
  return (
    <View>
      <House className="text-red-500 w-8 h-8" />
    </View>
  );
}

Props

属性	类型	默认值	说明
`size`	`number \	string`	`24`	图标尺寸
`color`	`string`	-	图标颜色（未设置时回退为黑色）
`filled`	`boolean`	`false`	是否渲染为实心（fill=currentColor）
`strokeWidth`	`number \	string`	`2`	描边宽度
`absoluteStrokeWidth`	`boolean`	`false`	绝对描边宽度，启用后描边不随 size 缩放
`className`	`string`	-	Image 的 className（用于布局等）
`style`	`CSSProperties`	-	内联样式

同时支持 Taro Image 组件的其他属性。

按需导入

支持 tree shaking，只打包使用到的图标：

tsx

import { House, Settings } from 'lucide-react-taro';
import { House } from 'lucide-react-taro/icons/house';

图标列表

所有图标名称与 Lucide 官方保持一致，使用 PascalCase 命名。

常用图标：House、Settings、User、Search、Menu、ChevronRight、Check、X、Plus、Minus、Heart、Star、Camera、Image、Share、Download、Upload

CLI 工具：查找和验证图标

本库提供了 CLI 工具来查找和验证图标是否存在。这对 AI 助手非常有用，可以在生成代码前验证图标名称是否正确。

查找图标

bash

# 模糊查找（默认）
pnpm dlx taro-lucide-find arrow

# 精确查找
pnpm dlx taro-lucide-find arrow-up --exact

# 列出所有图标
pnpm dlx taro-lucide-find --list

验证图标

推荐在生成代码前，使用 --json 参数批量验证图标是否存在。

bash

pnpm dlx taro-lucide-find arrow-up user settings arw --json

输出示例：

json

[
  {
    "query": "arrow-up",
    "exists": true,
    "name": "ArrowUp",
    "suggestions": []
  },
  {
    "query": "arw",
    "exists": false,
    "name": null,
    "suggestions": ["ArrowBigDownDash", "Archive", "..."]
  }
]

如果 exists 为 false，请使用 suggestions 中的推荐图标名称。

CLI 工具：生成 TabBar 图标

微信小程序的 TabBar 不支持 base64 或 SVG 图片，只能使用本地 PNG 文件。本库提供了 CLI 工具来生成 TabBar 所需的 PNG 图标。

批量生成 TabBar 图标

支持一次性生成所有 TabBar 图标。

bash

pnpm dlx taro-lucide-tabbar House Settings User -c "#999999" -a "#1890ff"

指定输出目录和尺寸

bash

pnpm dlx taro-lucide-tabbar House Settings User -c "#999999" -a "#1890ff" -o ./src/assets/tabbar -s 81

CLI 参数

参数	简写	默认值	说明
`--color`	`-c`	`#000000`	图标颜色
`--active-color`	`-a`	-	选中状态颜色
`--size`	`-s`	`81`	图标尺寸
`--output`	`-o`	`./tabbar-icons`	输出目录
`--stroke-width`	-	`2`	描边宽度

在 app.config.ts 中使用

export default defineAppConfig({
  tabBar: {
    color: '#999999',
    selectedColor: '#1890ff',
    backgroundColor: '#ffffff',
    borderStyle: 'black',
    list: [
      {
        pagePath: 'pages/index/index',
        text: '首页',
        iconPath: './assets/tabbar/house.png',
        selectedIconPath: './assets/tabbar/house-active.png',
      },
      {
        pagePath: 'pages/settings/index',
        text: '设置',
        iconPath: './assets/tabbar/settings.png',
        selectedIconPath: './assets/tabbar/settings-active.png',
      },
    ],
  },
});

LucideTaroProvider（全局默认配置）

通过 LucideTaroProvider 为子树中所有图标设置默认颜色和尺寸，避免每个图标重复传 props。优先级：color prop > defaultColor > 回退为黑色。

tsx

import { LucideTaroProvider, House, Settings } from 'lucide-react-taro';

function App() {
  return (
    <LucideTaroProvider defaultColor="#666" defaultSize={20}>
      <House />              {/* 使用 #666, 20px */}
      <Settings color="red" /> {/* color prop 优先 */}
    </LucideTaroProvider>
  );
}

LucideTaroProvider Props

属性	类型	说明
`defaultColor`	`string`	子组件默认图标颜色
`defaultSize`	`number \	string`	子组件默认图标尺寸

注意事项

禁止颜色继承：小程序端是 <Image /> 渲染，无法从父元素继承文本颜色（currentColor 在 Data URL 中回退为黑色）；请通过 LucideTaroProvider 或 color prop 显式设置颜色，不要依赖 className 的 text-*。
性能优化：组件内部已实现 base64 缓存，相同参数组合只计算一次。
兼容性：已内置 base64 编码 polyfill，无需额外配置即可在微信小程序中使用。
TabBar 图标：小程序 TabBar 不支持 SVG/base64，请使用 CLI 工具生成 PNG 图标。
TabBar 图标路径：iconPath 和 selectedIconPath 必须添加 ./ 前缀（如 ./assets/tabbar/house.png），否则图片无法正确加载。