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/sveltetabler→tabler/icons-svelte以此类推。这一约定不仅是写作规范更是 CLI 底层的事实依赖。在 packages/cli/src/icons/libraries.ts 中CLI 内置了五套受支持的图标库定义每套都声明了自己的packages、import、usage与export模板iconLibrary 值图标包导入语句示例lucidelucide/svelteimport SearchIcon from lucide/svelte/icons/searchtablertabler/icons-svelteimport { SearchIcon } from tabler/icons-sveltehugeiconshugeicons/sveltehugeicons/core-free-iconsimport { SearchIcon } from hugeicons/core-free-iconsphosphorphosphor-svelteimport SearchIcon from phosphor-svelte/lib/searchremixiconremixicon-svelteimport SearchIcon from remixicon-svelte/icons/search注意各库导入语法并不一致Lucide 走默认导入 kebab-case 子路径toLucideKebab会把 PascalCase 名称转成 kebab 并去掉-icon后缀Tabler 与 HugeIcons 用命名导入而 HugeIcons 还需要额外的HugeiconsIcon包装组件见getAdditionalImports。正因如此直接复制 Lucide 的导入写法到其他图标库必然报错——这就是以components.json为准这条规则存在的意义。配置从哪里来CLI 初始化时写入配置npx shadcn-sveltelatest init过程中会询问图标库选择见 packages/cli/src/preset/presets.ts 中的iconLibrary交互选项并将结果写入components.json。默认值为lucide见 packages/cli/src/utils/config/schema.ts 与 docs 侧设计系统配置的 docs/src/lib/registry/config.tsiconLibrary均默认lucide但默认值不等于事实任何预设preset都可以覆盖它。预设preset会固定图标库例如仓库内置预设中 Vega 用lucideNova、Maia 用hugeicons见 docs/src/lib/registry/config.ts 的PRESETS数组。初始化时使用npx shadcn-sveltelatest 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 langts 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 classmr-2 size-4 / Search /Button原因有两层间距应由>script langts import { Button } from $lib/components/ui/button; import { Spinner } from $lib/components/ui/spinner; /script Button disabled Spinner>!-- 错误Button 内图标加尺寸类 -- Button SearchIcon classsize-4>!-- 错误字符串 key 查表避免 -- DynamicIcon namecheck /!-- 正确直接传组件引用 -- script langts import type { Component } from svelte; import CheckIcon from lucide/svelte/icons/check; let { Icon }: { Icon: Component } $props(); /script Icon / !-- 用法示例StatusBadge Icon{CheckIcon} / --为什么推荐组件引用类型安全Icon: Component来自svelte的类型导出让 Svelte 编译器与 TS 能静态校验传入的是合法组件字符串 key 只能在运行时通过查表发现错误。树摇友好tree-shaking直接 import 具体图标组件lucide/svelte/icons/search打包器可以只保留用到的图标字符串 key 整包查表映射会拖入大量无关图标。与注册表组件用法一致CLI 转换后的注册表组件同样采用直接 import 图标组件 直接渲染的模式见 packages/cli/src/icons/libraries.ts 中usage字段生成的IconName ... /字符串 key 是生态外的写法。与相关规则的协同一份可复制的完整示例图标规则不是孤立的它与样式、表单、组合规则一起构成了 shadcn-svelte 的编写约定。下面是 SKILL.md 中Key Patterns给出的综合示例节选图标相关部分演示了data-icon、无尺寸类、命名导入与语义样式如何协同script langts 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考