new-api 前端图标使用规范：shadcn/ui 的 iconLibrary 配置、data-icon 属性与图标组件化传递
new-api 前端图标使用规范shadcn/ui 的 iconLibrary 配置、data-icon 属性与图标组件化传递【免费下载链接】new-apiA unified AI model hub for aggregation distribution. It supports cross-converting various LLMs into OpenAI-compatible, Claude-compatible, or Gemini-compatible formats. A centralized gateway for personal and enterprise model management.项目地址: https://gitcode.com/gh_mirrors/ne/new-apinew-api 的前端web/目录基于 shadcn/ui 构建控制台界面仓库在.agents/skills/shadcn-ui/下内置了一套 shadcn/ui 上下文技能Skill并把上游skills/shadcn的图标规范快照到了 icons.md。本文以该规范为主体逐条讲解“选对图标库、用对>{ style: base-nova, rsc: false, tsx: true, iconLibrary: hugeicons, aliases: { components: /components, ui: /components/ui, utils: /lib/utils } }因此按规则推导在 new-api 前端新增图标时图标来源应是 Hugeicons 生态而不是lucide-react。仓库中的官方组件正是这样落码的例如分页组件 pagination.tsx 从两个包协作导入import { ArrowLeft01Icon, ArrowRight01Icon, MoreHorizontalCircle01Icon, } from hugeicons/core-free-icons // 图标数据 import { HugeiconsIcon } from hugeicons/react // 渲染组件注意两种库的 API 形态差异lucide-react/tabler/icons-react直接导出可渲染的组件如Search /、IconSearch /而 Hugeicons 是“图标数据 HugeiconsIcon包装组件”的组合图标以icon{...}属性传入HugeiconsIcon icon{ArrowLeft01Icon} strokeWidth{2} >cd web bunx shadcnlatest info --json该命令会输出框架、Tailwind 版本、别名、baseradix或base、图标库、已安装组件与解析后的路径。规范强调“check theiconLibraryfield from project context”即把shadcn info --json的输出作为导入与 API 的事实来源ground truth这正是“不要假设lucide-react”这条规则的落地手段。规则一Button 内的图标用>Button SearchIcon classNamemr-2 size-4 / Search /Button正确写法Button SearchIcon>has-data-[iconinline-end]:pr-2 has-data-[iconinline-start]:pl-2, // xs 尺寸档 gap-1 has-data-[iconinline-end]:pr-1.5 has-data-[iconinline-start]:pl-1.5 [_svg:not([class*size-])]:size-3, // sm 尺寸档 gap-1 has-data-[iconinline-start]:pl-2.5 ... [_svg:not([class*size-])]:size-3.5,这里有两条 Tailwind 选择器在起作用has-data-[iconinline-start]/has-data-[iconinline-end]只要 Button 的后代存在data-iconinline-start的元素就收紧对应一侧的内边距图标在前则减pl图标在后则减pr同时用gap-1.5控制图标与文字的间距[_svg:not([class*size-])]:size-3xs 档/size-3.5sm 档自动给按钮内没有显式尺寸类的 svg 补上默认尺寸。not([class*size-])这个排除条件很关键——它意味着“组件默认尺寸但尊重你显式写的size-*”。badge.tsx 同理has-data-[iconinline-end]:pr-1.5 has-data-[iconinline-start]:pl-1.5 ... [svg]:size-3!说明这套“data-icon 声明位置 CSS 接管尺寸”的约定贯穿多个 shadcn 组件而不只是 Button。实际业务代码中这一模式随处可见例如 summary-cards.tsx 的ArrowRight>Button SearchIcon classNamesize-4>Button SearchIcon>const iconMap { check: CheckIcon, alert: AlertIcon, } function StatusBadge({ icon }: { icon: string }) { const Icon iconMap[icon] return Icon / } StatusBadge iconcheck /正确写法// 从项目配置的 iconLibrary 对应包导入 // 本仓库为 hugeicons 生态若配置为 lucide 则为 lucide-react import { CheckIcon } from lucide-react function StatusBadge({ icon: Icon }: { icon: React.ComponentType }) { return Icon / } StatusBadge icon{CheckIcon} /从工程角度理解这条规则字符串键把“图标名 → 组件”的解析推迟到运行时查表类型系统无法校验键是否存在打错键名只会得到undefined渲染时静默失败或抛错而直接传递组件对象React.ComponentType让 TypeScript 在编译期即可约束取值调用方StatusBadge icon{CheckIcon} /也一目了然。仓库中pagination.tsx的HugeiconsIcon icon{ArrowLeft01Icon}正是“图标作为组件/对象值传递”这一思想的体现图标是数据属性而非被间接索引的字符串。规范落地速查综合 icons.md 原文与仓库实现在 new-api 前端写含图标的界面时可按以下清单自检检查项依据图标导入来源与components.json的iconLibrary本仓库为hugeicons一致不默认lucide-reactcomponents.json、icons.md 总纲Button 内前缀/后缀图标分别写data-iconinline-start/data-iconinline-endpagination.tsx 等真实用法组件内图标不写size-*、mr-*等尺寸/间距类交给组件 CSS 处理button.tsx 的has-data-[icon...]与[_svg:not([class*size-])]选择器需要自定义图标尺寸时显式size-*类是规范保留的例外选择器会自动让位badge.tsx、pagination.tsx图标作为组件对象icon{CheckIcon}传递不用字符串键查表icons.md “Pass icons as component objects”拿不准当前项目图标库时先执行cd web bunx shadcnlatest info --json查询SKILL.md这套规范的价值在于图标位置、尺寸、间距被收敛到 shadcn 组件的样式层统一治理业务代码只声明“哪里放什么图标”既不重复手写尺寸也不把图标库细节泄漏到渲染逻辑里——这正是 new-api 控制台大量按钮、菜单与 Badge 能保持视觉一致性的底层约定。【免费下载链接】new-apiA unified AI model hub for aggregation distribution. It supports cross-converting various LLMs into OpenAI-compatible, Claude-compatible, or Gemini-compatible formats. A centralized gateway for personal and enterprise model management.项目地址: https://gitcode.com/gh_mirrors/ne/new-api创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考