@ brightlocal/ icons (英语)

亮度本地设计系统图标 - Lucide 默认和自定义图标

概览

这个软件包为亮度本地设计系统提供了一个统一的图标系统,结合了:

• 所有 5000+ Lucide 反应图标( 树能震动)
• 自定义亮度本地图标
• 动态图标加载数据库驱动 UI
• 完整类型脚本支持

安装

pnpm add @brightlocal/icons

使用量

1. 直接进口(建议)

最适合摇树- 只导入您使用的图标 .

import { Check, Heart, Star } from "@brightlocal/icons";

<Check className="w-4 h-4" />
<Heart size={20} color="red" fill="red" />
<Star size={16} strokeWidth={2} />

2. 动态Icon组件

对于数据库驱动的图标渲染,并带有代码分割. 图标仅在使用时才能动态加载 .

import { DynamicIcon } from "@brightlocal/icons";

// From database or CMS
const iconName = user.settings.preferredIcon; // "heart"
<DynamicIcon name={iconName} size={20} />

// Works with custom icons too
<DynamicIcon name="bright-local-logo" size={32} />

// With Suspense fallback (optional)
<React.Suspense fallback={<div className="w-6 h-6 animate-pulse bg-gray-200 rounded" />}>
  <DynamicIcon name={dbIconName} size={16} />
</React.Suspense>

3. 自定义亮度本地图标

import { BrightLocalLogo } from "@brightlocal/icons";

<BrightLocalLogo className="h-8 w-8 text-blue-600" />;

组件道具

动态Icon 组件

• name:图标名称(kebab-case,例如"相机","chevron-down","Bright-local-logo")
• size: 以像素表示的图标大小( 默认: 16)
• color: 图标颜色(默认使用当前颜色)
• strokeWidth: 弦宽( 默认: 1. 33)
• 所有其他 SVG 道具

旗帜和社交媒体图标

• size: 以像素表示的图标大小( 默认: 16)
• className: 用于造型的CSS课程
• 所有标准 SVG 道具

福利

• 树能震动: 只导入您使用的图标( 有直接导入)
• 类型安全: 自动完成的完整类型脚本支持
• 弹性: 用于不同用途的多导入模式
• 懒惰装入: 动态Icon将图标分割成单独的块
• 一致: 覆盖所有图标的统一 API
• 优化: 最小捆绑撞击

添加自定义图标

方法1:使用创建LusideIcon(建议)

与DynamicIcon兼容并遵循了Lucide的准则(16×16画布,2px中风).

// src/custom-icons/my-icon.tsx
import { createLucideIcon } from "@brightlocal/icons";

export const MyIcon = createLucideIcon("MyIcon", [
  ["path", { d: "M12 2v20M2 12h20", key: "cross" }],
  ["circle", { cx: "12", cy: "12", r: "3", key: "center" }],
]);

export default MyIcon;

然后加入动态导入:

// src/icons/dynamic-icon-imports.ts
const customIconImports = {
  "my-icon": () =>
    import("../custom-icons/my-icon.js").then((m) => ({
      default: m.MyIcon,
    })),
};

方法2:普通SVG组件

对于不需要动态加载的图标.

// src/custom-icons/my-icon.tsx
import * as React from "react";

export const MyIcon = (props: React.SVGProps<SVGSVGElement>) => (
  <svg viewBox="0 0 16 16" fill="none" {...props}>
    <path d="M12 2v20M2 12h20" stroke="currentColor" strokeWidth={2} />
  </svg>
);

实例

图标图片库

import { Check, X, Plus, Minus, Heart, Star } from "@brightlocal/icons";

const icons = [Check, X, Plus, Minus, Heart, Star];

<div className="grid grid-cols-6 gap-4">
  {icons.map((Icon, i) => (
    <Icon key={i} size={16} />
  ))}
</div>;

数据库驱动图标

import { DynamicIcon } from "@brightlocal/icons";

// Icons stored in database
const features = [
  { id: 1, name: "Fast", icon: "zap" },
  { id: 2, name: "Secure", icon: "shield" },
  { id: 3, name: "Scalable", icon: "trending-up" },
];

<div className="grid grid-cols-3 gap-4">
  {features.map((feature) => (
    <div key={feature.id}>
      <DynamicIcon name={feature.icon} size={32} />
      <h3>{feature.name}</h3>
    </div>
  ))}
</div>;

装入国

import { Loader2 } from "@brightlocal/icons";

<button disabled>
  <Loader2 className="mr-2 animate-spin" size={16} />
  Loading...
</button>;

图标命名公约

使用时 DynamicIcon,图标名称遵循 kebab 大小写格式 :

• 路西德图标: 将 PascalCase 转换为 kebab- case
  • ChevronDown → "chevron-down"
  • AlertCircle → "alert-circle"
  • UserPlus → "user-plus"
• 自定义图标: 一致使用 kebab 大小写
  • BrightLocalLogo → "bright-local-logo"

业绩考量

直接导入对 DynamicIcon

当 :

• 图标在构建时已知
• 需要最大摇动树
• 你想要最小的可能捆绑

import { Camera, Heart } from "@brightlocal/icons";

当 :

• 图标名称来自数据库/ API
• 大型图标集需要代码共享
• 建筑可配置的UI组件

<DynamicIcon name={iconFromDatabase} />

套装大小影响

• 直接导入: ~1-2KB 每个图标( 树形)
• DynamicIcon: ~4KB + 按要求装入图标

默认图标属性

所有路西德图标来自 @brightlocal/icons 包含设计系统默认值:

按图标类型分列的默认大小

// Lucide icons default to 16px with 1.33 strokeWidth
<Check />

// Explicit size — stroke stays consistent (absoluteStrokeWidth: true)
<Check size={20} />
<Check size={12} />

类型脚本支持

完全类型脚本支持和类型推论 :

import { DynamicIcon } from "@brightlocal/icons";
import type { DynamicIconProps } from "@brightlocal/icons";

// Props are fully typed
const props: DynamicIconProps = {
  name: "heart",
  size: 16,
  color: "#ff0000",
};

无障碍

图标应包括适当的无障碍属性:

// Decorative icons (no semantic meaning)
<Check aria-hidden="true" />

// Meaningful icons (provide label)
<Heart aria-label="Like this post" role="img" />

// Interactive icons (use with button/link)
<button aria-label="Close dialog">
  <X size={20} />
</button>

解决问题

未显示图标

1. 检查图标名称是否正确( 对直接导入的大小写敏感)
2. 校验图标存在于 Lucide 库
3. 对于 DynamicIcon ,请确保图标在 dynamic-icon-imports.ts

类型脚本出错

确保您安装了最新的类型 :

pnpm add -D @types/react

套装大小太大

使用直接导入而不是导入所有 :

// ❌ Don't do this
import * as Icons from "@brightlocal/icons";

// ✅ Do this
import { Camera, Heart, Star } from "@brightlocal/icons";

从其他图标图书馆迁移

从反应图标

// Before (react-icons)
import { FaHeart } from "react-icons/fa";
<FaHeart size={16} />;

// After (brightlocal/icons)
import { Heart } from "@brightlocal/icons";
<Heart size={16} />;

从赫罗伊孔斯

// Before (heroicons)
import { HeartIcon } from "@heroicons/react/16/outline";
<HeartIcon className="h-6 w-6" />;

// After (brightlocal/icons)
import { Heart } from "@brightlocal/icons";
<Heart className="h-6 w-6" />;

资源

• Lucide 图标画廊 - 浏览所有可用的 5000+ 图标
• 路西德文档 - 更多地了解Lucide图标
• 故事书文档 - 交互式图标画廊
• 软件包来源 - 查看源代码

捐款

要添加新自定义图标 :

1. 在其中创建图标文件 src/custom-icons/
2. 导出自 src/index.ts
3. 添加到动态导入 src/icons/dynamic-icon-imports.ts
4. 更新 customIconsData 在故事书文档中
5. 运行构建 : pnpm build

添加社交媒体图标

社交媒体的图标 src/social-media/ 使用自动生成的枪管(index.ts) (中文(简体) ). 这个 SourceLogo 构成部分 @brightlocal/ui-components 自动解析图标名称 以公约方式执行的name → <PascalName>Original 编号 : <PascalName>Neutral),所以大多数新图标 工作时无需更改代码 ui-components。 。 。 .

何时添加别名: 如果消费者造型源密钥与图标文件干不匹配 (例如消费者通过) "twitter" 但图标文件是 x-ex-twitter-original.tsx,添加一个 条目为 SOURCE_ICON_ALIASES 内 packages/ui-components/src/components/source-logo.tsx。 。 。 .

许可证

明亮局部设计系统的一部分. 许可证详情见主仓库.