企业官网建设流程全解析

shadcn-svelte 图标规范实战：data-icon 属性、iconLibrary 配置与组件级图标传参

【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelte

导读

在 shadcn-svelte 项目中，图标的使用方式与普通 Svelte 组件有明显差异：图标库由components.json中的iconLibrary字段决定而非默认假设为 Lucide；图标放在<Button>等组件内部时依赖data-icon属性完成前缀/后缀定位；组件的尺寸样式由 CSS 统一接管，禁止手动添加size-4之类的大小类。本文以仓库中 skills/shadcn-svelte/rules/icons.md 为核心，结合 CLI 源码与组件注册表实现，系统梳理这三条强制规则的正确写法、错误示例及底层原理，帮助你在接入、维护和调试 shadcn-svelte 组件时一次写对。

规则一：始终使用项目配置的 iconLibrary 作为图标导入来源

永远不要假设项目一定使用@lucide/svelte。正确的做法是读取项目根目录components.json中的iconLibrary字段，再决定图标包从哪里导入：lucide→@lucide/svelte，tabler→@tabler/icons-svelte，以此类推。

这一约定不仅是写作规范，更是 CLI 底层的事实依赖。在 packages/cli/src/icons/libraries.ts 中，CLI 内置了五套受支持的图标库定义，每套都声明了自己的packages、import、usage与export模板：

注意各库导入语法并不一致：Lucide 走默认导入 + kebab-case 子路径（toLucideKebab会把 PascalCase 名称转成 kebab 并去掉-icon后缀），Tabler 与 HugeIcons 用命名导入，而 HugeIcons 还需要额外的HugeiconsIcon包装组件（见getAdditionalImports）。正因如此，直接复制 Lucide 的导入写法到其他图标库必然报错——这就是"以components.json为准"这条规则存在的意义。

配置从哪里来

• CLI 初始化时写入配置：npx shadcn-svelte@latest init过程中会询问图标库选择（见 packages/cli/src/preset/presets.ts 中的iconLibrary交互选项），并将结果写入components.json。
• 默认值为lucide：见 packages/cli/src/utils/config/schema.ts 与 docs 侧设计系统配置的 docs/src/lib/registry/config.ts，iconLibrary均默认lucide，但默认值不等于事实，任何预设（preset）都可以覆盖它。
• 预设（preset）会固定图标库：例如仓库内置预设中 Vega 用lucide，Nova、Maia 用hugeicons（见 docs/src/lib/registry/config.ts 的PRESETS数组）。初始化时使用npx shadcn-svelte@latest init --preset <code>会连带决定iconLibrary（见 packages/cli/src/commands/apply/index.ts）。

实操建议：在写任何图标导入前，先执行以下两步——① 打开项目根目录components.json，确认iconLibrary字段；② 打开components.json中aliases.ui指向的目录，按 packages/cli/src/icons/libraries.ts 中对应库的导入模板书写 import。切勿凭空猜测。

规则二：Button 内的图标使用><script lang="ts"> import { Button } from "$lib/components/ui/button"; import SearchIcon from "@lucide/svelte/icons/search"; import ArrowRightIcon from "@lucide/svelte/icons/arrow-right"; </script> <Button> <SearchIcon><!-- 错误：图标上手动加间距类 --> <Button> <SearchIcon class="mr-2 size-4" /> Search </Button>

原因有两层：

1. 间距应由><script lang="ts"> import { Button } from "$lib/components/ui/button"; import { Spinner } from "$lib/components/ui/spinner"; </script> <Button disabled> <Spinner><!-- 错误：Button 内图标加尺寸类 --> <Button> <SearchIcon class="size-4"><!-- 错误：字符串 key 查表，避免 --> <DynamicIcon name="check" />

   <!-- 正确：直接传组件引用 --> <script lang="ts"> import type { Component } from "svelte"; import CheckIcon from "@lucide/svelte/icons/check"; let { Icon }: { Icon: Component } = $props(); </script> <Icon /> <!-- 用法示例：<StatusBadge Icon={CheckIcon} /> -->

   为什么推荐组件引用

   1. 类型安全：Icon: Component（来自svelte的类型导出）让 Svelte 编译器与 TS 能静态校验传入的是合法组件，字符串 key 只能在运行时通过查表发现错误。
   2. 树摇友好（tree-shaking）：直接 import 具体图标组件（@lucide/svelte/icons/search），打包器可以只保留用到的图标，字符串 key + 整包查表映射会拖入大量无关图标。
   3. 与注册表组件用法一致：CLI 转换后的注册表组件同样采用"直接 import 图标组件 + 直接渲染"的模式（见 packages/cli/src/icons/libraries.ts 中usage字段生成的<IconName ... />），字符串 key 是生态外的写法。

   ---

   与相关规则的协同：一份可复制的完整示例

   图标规则不是孤立的，它与样式、表单、组合规则一起构成了 shadcn-svelte 的编写约定。下面是 SKILL.md 中"Key Patterns"给出的综合示例（节选图标相关部分），演示了data-icon、无尺寸类、命名导入与语义样式如何协同：

   <script lang="ts"> import { Button } from "$lib/components/ui/button"; import SearchIcon from "@lucide/svelte/icons/search"; import { Badge } from "$lib/components/ui/badge"; </script> <!-- Icons in buttons: contenteditable="false">【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelte