范實戰(zhàn)指南：data-icon 屬性、圖標尺寸控制與組件化傳遞)
React Starter Kit 圖標規(guī)范實戰(zhàn)指南data-icon 屬性、圖標尺寸控制與組件化傳遞【免費下載鏈接】react-starter-kitModern React starter kit with Bun, TypeScript, Tailwind CSS, tRPC, Stripe, and Cloudflare Workers. Production-ready monorepo for building fast web apps.項目地址: https://gitcode.com/gh_mirrors/rea/react-starter-kit導讀本指南以 shadcn 技能庫中的圖標規(guī)則文檔.agents/skills/shadcn/rules/icons.md為核心骨架結合本倉庫react-starter-kit的packages/ui、apps/app的實際組件與路由源碼系統(tǒng)講解在 shadcn/ui 項目中正確使用圖標的三條硬性規(guī)則始終使用項目配置的iconLibrary導入圖標、在Button等組件內(nèi)通過data-icon屬性定位圖標而不再手寫尺寸類、以及以組件對象而非字符串鍵傳遞圖標。讀完本文你將能在 shadcn 組件中寫出既符合設計系統(tǒng)規(guī)范、又具備類型安全與可維護性的圖標代碼。一、先從配置說起iconLibrary 決定圖標導入路徑在 shadcn/ui 體系中圖標并非組件自帶的固定資源而是由項目在components.json中聲明的iconLibrary字段決定的。規(guī)則文檔的第一條規(guī)則即明確始終使用項目配置的iconLibrary進行導入。檢查項目上下文中的iconLibrary字段lucide→lucide-reacttabler→tabler/icons-react以此類推。永遠不要默認假定是lucide-react。在本倉庫中packages/ui/components.json的第 19 行聲明了iconLibrary: lucideapps/app/components.json同樣如此。因此本項目的正確導入方式為import { CheckIcon, SearchIcon, ArrowRightIcon } from lucide-react;為什么不能寫死lucide-react因為 shadcn 的 preset 與社區(qū) registry 允許項目自由切換圖標庫。一旦項目將iconLibrary切換為tabler或hugeicons寫死的lucide-react導入將全部失效且圖標命名如CheckvsCheckIcon也會隨之變化。倉庫的技能文檔 .agents/skills/shadcn/SKILL.md 的“Key Fields”一節(jié)明確說明iconLibrary決定圖標導入方式并強調(diào)“永遠不要假設是lucide-react”。這也是在接入第三方 registry 組件后需要校驗并替換圖標導入的根本原因。二、規(guī)則一Button 內(nèi)的圖標使用data-icon屬性問題傳統(tǒng)做法為什么不對在 shadcn 組件內(nèi)部圖標不再需要手動添加間距與尺寸類。規(guī)則文檔給出的反例{/* Incorrect */} Button SearchIcon classNamemr-2 size-4 / Search /Buttonmr-2手動制造圖標與文本的間距size-4手動鎖定圖標尺寸。這兩者都屬于“把組件內(nèi)部樣式細節(jié)泄漏到調(diào)用方”的做法會導致圖標尺寸與按鈕變體default/sm/lg/icon不匹配間距在不同主題、不同按鈕變體下無法統(tǒng)一調(diào)整視覺不一致維護成本高。正確寫法data-icon定位圖標位置規(guī)則文檔給出的正例{/* Correct: 前綴圖標 */} Button SearchIcon>[_svg]:pointer-events-none [_svg]:size-4 [_svg]:shrink-0這表示Button內(nèi)部通過 CSS 選擇器[_svg]自動對所有SVG 圖標統(tǒng)一應用size-4即width: 1rem; height: 1rem與shrink-0防止 flex 壓縮并禁用其指針事件。這就是“組件通過 CSS 管理圖標尺寸”的實現(xiàn)證據(jù)——圖標的大小由組件決定與調(diào)用方傳入的 className 無關。因此即使你在Button內(nèi)省略size-4圖標也會被組件內(nèi)部的[_svg]:size-4規(guī)則自動縮放到標準尺寸。而data-icon屬性的作用則是讓組件 CSS 能夠區(qū)分圖標在按鈕中的位置前綴或后綴從而精確控制其與文本之間的間距如gap-2由Button的inline-flex items-center justify-center gap-2統(tǒng)一提供無需手動mr-2。三、規(guī)則二組件內(nèi)部禁止為圖標添加尺寸類適用范圍規(guī)則文檔明確指出禁止在Button、DropdownMenuItem、Alert、Sidebar*等 shadcn 組件內(nèi)部為圖標添加size-4、w-4 h-4等尺寸類。除非用戶明確要求自定義圖標尺寸。反例與正例{/* Incorrect */} Button SearchIcon classNamesize-4>{/* Incorrect */} const iconMap { check: CheckIcon, alert: AlertIcon, }; function StatusBadge({ icon }: { icon: string }) { const Icon iconMap[icon]; return Icon /; } StatusBadge iconcheck /;這種寫法存在明顯缺陷無類型安全icon是任意字符串拼寫錯誤如chekc不會在編譯期暴露運行時風險字符串鍵在映射表中不存在時返回undefined渲染直接崩潰維護成本高每新增一個圖標都要同步維護映射表不利于 Tree Shaking整個映射表被引用編譯器難以準確移除未使用的圖標。正例直接傳遞組件對象// 從項目配置的 iconLibrary 導入如 lucide-react、tabler/icons-react import { CheckIcon } from lucide-react; function StatusBadge({ icon: Icon }: { icon: React.ComponentType }) { return Icon /; } StatusBadge icon{CheckIcon} /;要點解析類型即文檔icon: React.ComponentType明確約束參數(shù)必須是 React 組件編譯期即可捕獲錯誤傳參零映射開銷調(diào)用方直接傳入組件引用無需任何查找表Tree Shaking 友好只導入實際使用的圖標打包體積更小命名解構{ icon: Icon }將 prop 重命名為局部變量Icon以便在 JSX 中作為組件使用JSX 要求組件名大寫開頭。倉庫中的實際應用這一模式在本倉庫中已有真實落地?？?apps/app/components/layout/sidebar-nav.tsx 的實現(xiàn)import type { LucideIcon } from lucide-react; interface SidebarNavItem { icon: LucideIcon; label: string; to: keyof FileRoutesByTo; } export function SidebarNav({ items }: SidebarNavProps) { return ( nav classNameflex-1 p-4 space-y-1 {items.map((item) ( Link key{item.to} to{item.to} className... item.icon classNameh-4 w-4 / span{item.label}/span /Link ))} /nav ); }這里icon字段的類型是LucideIconlucide-react 導出的圖標組件類型item.icon /直接渲染傳入的組件對象——正是“以組件對象傳遞圖標”的工程化實踐。調(diào)用方只需SidebarNav items{[{ icon: Settings, label: Settings, to: /settings }]} /與之類似apps/app/components/user-menu.tsx 中LogOut、RefreshCw、User均從lucide-react直接導入并以組件形式使用而 apps/app/components/auth/auth-form.tsx 中的Mail、ArrowLeft也是如此。這些頁面級代碼共同印證了規(guī)則三在真實項目中的落地形態(tài)。五、三條規(guī)則的內(nèi)在邏輯讓組件成為圖標樣式的唯一來源將三條規(guī)則放在一起看它們其實指向同一個設計原則規(guī)則解決的問題核心機制使用iconLibrary導入圖標來源不確定components.json的iconLibrary字段data-icon屬性圖標在按鈕中的位置前綴/后綴data-iconinline-start/inline-end禁止尺寸類圖標尺寸與間距統(tǒng)一組件內(nèi) CSS[_svg]:size-4、gap-2組件對象傳遞類型安全與 Tree Shakingicon: React.ComponentType/LucideIcon其核心思想是圖標是組件的“零件”組件的 CSS 負責其外觀調(diào)用方只負責“放什么圖標”和“放哪里”。這一約定保證了整個設計系統(tǒng)在不同頁面、不同變體間保持視覺一致同時將圖標的導入來源、尺寸、間距、類型約束集中管理。在實際編碼中你可以通過npx shadcnlatest info --json獲取當前項目的iconLibrary配置通過npx shadcnlatest docs component獲取組件的 API 文檔與示例參見 .agents/skills/shadcn/cli.md再結合本文的三條規(guī)則檢查自己寫的圖標代碼是否合規(guī)。六、快速自查清單在提交圖標相關代碼前請對照以下清單檢查依據(jù) .agents/skills/shadcn/rules/icons.md導入來源正確圖標是否從項目iconLibrary對應的包導入本倉庫為lucide-react而非寫死其他圖標庫Button 內(nèi)使用data-iconButton內(nèi)的圖標是否使用了data-iconinline-start或data-iconinline-end且未添加className組件內(nèi)無尺寸類Button、DropdownMenuItem、Alert、Sidebar*等組件內(nèi)部的圖標是否沒有任何size-*、w-* h-*、mr-*類組件對象傳遞自定義組件接收圖標時是否使用icon{SomeIcon}類型為React.ComponentType或LucideIcon而非字符串鍵查找表頁面級場景例外非 shadcn 組件內(nèi)使用圖標時尺寸與間距是否仍由你自己負責此時size-*類可用對照這三條規(guī)則與本倉庫的 packages/ui 組件實現(xiàn)、apps/app 頁面代碼你就能寫出與設計系統(tǒng)完全一致、類型安全且易于維護的 shadcn 圖標代碼。【免費下載鏈接】react-starter-kitModern React starter kit with Bun, TypeScript, Tailwind CSS, tRPC, Stripe, and Cloudflare Workers. Production-ready monorepo for building fast web apps.項目地址: https://gitcode.com/gh_mirrors/rea/react-starter-kit創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 React Starter Kit 圖標規(guī)范實戰(zhàn)指南：data-icon 屬性、圖標尺寸控制與組件化傳遞
React Starter Kit 圖標規(guī)范實戰(zhàn)指南data-icon 屬性、圖標尺寸控制與組件化傳遞【免費下載鏈接】react-starter-kitModern React starter kit with Bun, TypeScript, Tailwind CSS, tRPC, Stripe, and Cloudflare Workers. Production-ready monorepo for building fast web apps.項目地址: https://gitcode.com/gh_mirrors/rea/react-starter-kit導讀本指南以 shadcn 技能庫中的圖標規(guī)則文檔.agents/skills/shadcn/rules/icons.md為核心骨架結合本倉庫react-starter-kit的packages/ui、apps/app的實際組件與路由源碼系統(tǒng)講解在 shadcn/ui 項目中正確使用圖標的三條硬性規(guī)則始終使用項目配置的iconLibrary導入圖標、在Button等組件內(nèi)通過data-icon屬性定位圖標而不再手寫尺寸類、以及以組件對象而非字符串鍵傳遞圖標。讀完本文你將能在 shadcn 組件中寫出既符合設計系統(tǒng)規(guī)范、又具備類型安全與可維護性的圖標代碼。一、先從配置說起iconLibrary 決定圖標導入路徑在 shadcn/ui 體系中圖標并非組件自帶的固定資源而是由項目在components.json中聲明的iconLibrary字段決定的。規(guī)則文檔的第一條規(guī)則即明確始終使用項目配置的iconLibrary進行導入。檢查項目上下文中的iconLibrary字段lucide→lucide-reacttabler→tabler/icons-react以此類推。永遠不要默認假定是lucide-react。在本倉庫中packages/ui/components.json的第 19 行聲明了iconLibrary: lucideapps/app/components.json同樣如此。因此本項目的正確導入方式為import { CheckIcon, SearchIcon, ArrowRightIcon } from lucide-react;為什么不能寫死lucide-react因為 shadcn 的 preset 與社區(qū) registry 允許項目自由切換圖標庫。一旦項目將iconLibrary切換為tabler或hugeicons寫死的lucide-react導入將全部失效且圖標命名如CheckvsCheckIcon也會隨之變化。倉庫的技能文檔 .agents/skills/shadcn/SKILL.md 的“Key Fields”一節(jié)明確說明iconLibrary決定圖標導入方式并強調(diào)“永遠不要假設是lucide-react”。這也是在接入第三方 registry 組件后需要校驗并替換圖標導入的根本原因。二、規(guī)則一Button 內(nèi)的圖標使用data-icon屬性問題傳統(tǒng)做法為什么不對在 shadcn 組件內(nèi)部圖標不再需要手動添加間距與尺寸類。規(guī)則文檔給出的反例{/* Incorrect */} Button SearchIcon classNamemr-2 size-4 / Search /Buttonmr-2手動制造圖標與文本的間距size-4手動鎖定圖標尺寸。這兩者都屬于“把組件內(nèi)部樣式細節(jié)泄漏到調(diào)用方”的做法會導致圖標尺寸與按鈕變體default/sm/lg/icon不匹配間距在不同主題、不同按鈕變體下無法統(tǒng)一調(diào)整視覺不一致維護成本高。正確寫法data-icon定位圖標位置規(guī)則文檔給出的正例{/* Correct: 前綴圖標 */} Button SearchIcon>[_svg]:pointer-events-none [_svg]:size-4 [_svg]:shrink-0這表示Button內(nèi)部通過 CSS 選擇器[_svg]自動對所有SVG 圖標統(tǒng)一應用size-4即width: 1rem; height: 1rem與shrink-0防止 flex 壓縮并禁用其指針事件。這就是“組件通過 CSS 管理圖標尺寸”的實現(xiàn)證據(jù)——圖標的大小由組件決定與調(diào)用方傳入的 className 無關。因此即使你在Button內(nèi)省略size-4圖標也會被組件內(nèi)部的[_svg]:size-4規(guī)則自動縮放到標準尺寸。而data-icon屬性的作用則是讓組件 CSS 能夠區(qū)分圖標在按鈕中的位置前綴或后綴從而精確控制其與文本之間的間距如gap-2由Button的inline-flex items-center justify-center gap-2統(tǒng)一提供無需手動mr-2。三、規(guī)則二組件內(nèi)部禁止為圖標添加尺寸類適用范圍規(guī)則文檔明確指出禁止在Button、DropdownMenuItem、Alert、Sidebar*等 shadcn 組件內(nèi)部為圖標添加size-4、w-4 h-4等尺寸類。除非用戶明確要求自定義圖標尺寸。反例與正例{/* Incorrect */} Button SearchIcon classNamesize-4>{/* Incorrect */} const iconMap { check: CheckIcon, alert: AlertIcon, }; function StatusBadge({ icon }: { icon: string }) { const Icon iconMap[icon]; return Icon /; } StatusBadge iconcheck /;這種寫法存在明顯缺陷無類型安全icon是任意字符串拼寫錯誤如chekc不會在編譯期暴露運行時風險字符串鍵在映射表中不存在時返回undefined渲染直接崩潰維護成本高每新增一個圖標都要同步維護映射表不利于 Tree Shaking整個映射表被引用編譯器難以準確移除未使用的圖標。正例直接傳遞組件對象// 從項目配置的 iconLibrary 導入如 lucide-react、tabler/icons-react import { CheckIcon } from lucide-react; function StatusBadge({ icon: Icon }: { icon: React.ComponentType }) { return Icon /; } StatusBadge icon{CheckIcon} /;要點解析類型即文檔icon: React.ComponentType明確約束參數(shù)必須是 React 組件編譯期即可捕獲錯誤傳參零映射開銷調(diào)用方直接傳入組件引用無需任何查找表Tree Shaking 友好只導入實際使用的圖標打包體積更小命名解構{ icon: Icon }將 prop 重命名為局部變量Icon以便在 JSX 中作為組件使用JSX 要求組件名大寫開頭。倉庫中的實際應用這一模式在本倉庫中已有真實落地?？?apps/app/components/layout/sidebar-nav.tsx 的實現(xiàn)import type { LucideIcon } from lucide-react; interface SidebarNavItem { icon: LucideIcon; label: string; to: keyof FileRoutesByTo; } export function SidebarNav({ items }: SidebarNavProps) { return ( nav classNameflex-1 p-4 space-y-1 {items.map((item) ( Link key{item.to} to{item.to} className... item.icon classNameh-4 w-4 / span{item.label}/span /Link ))} /nav ); }這里icon字段的類型是LucideIconlucide-react 導出的圖標組件類型item.icon /直接渲染傳入的組件對象——正是“以組件對象傳遞圖標”的工程化實踐。調(diào)用方只需SidebarNav items{[{ icon: Settings, label: Settings, to: /settings }]} /與之類似apps/app/components/user-menu.tsx 中LogOut、RefreshCw、User均從lucide-react直接導入并以組件形式使用而 apps/app/components/auth/auth-form.tsx 中的Mail、ArrowLeft也是如此。這些頁面級代碼共同印證了規(guī)則三在真實項目中的落地形態(tài)。五、三條規(guī)則的內(nèi)在邏輯讓組件成為圖標樣式的唯一來源將三條規(guī)則放在一起看它們其實指向同一個設計原則規(guī)則解決的問題核心機制使用iconLibrary導入圖標來源不確定components.json的iconLibrary字段data-icon屬性圖標在按鈕中的位置前綴/后綴data-iconinline-start/inline-end禁止尺寸類圖標尺寸與間距統(tǒng)一組件內(nèi) CSS[_svg]:size-4、gap-2組件對象傳遞類型安全與 Tree Shakingicon: React.ComponentType/LucideIcon其核心思想是圖標是組件的“零件”組件的 CSS 負責其外觀調(diào)用方只負責“放什么圖標”和“放哪里”。這一約定保證了整個設計系統(tǒng)在不同頁面、不同變體間保持視覺一致同時將圖標的導入來源、尺寸、間距、類型約束集中管理。在實際編碼中你可以通過npx shadcnlatest info --json獲取當前項目的iconLibrary配置通過npx shadcnlatest docs component獲取組件的 API 文檔與示例參見 .agents/skills/shadcn/cli.md再結合本文的三條規(guī)則檢查自己寫的圖標代碼是否合規(guī)。六、快速自查清單在提交圖標相關代碼前請對照以下清單檢查依據(jù) .agents/skills/shadcn/rules/icons.md導入來源正確圖標是否從項目iconLibrary對應的包導入本倉庫為lucide-react而非寫死其他圖標庫Button 內(nèi)使用data-iconButton內(nèi)的圖標是否使用了data-iconinline-start或data-iconinline-end且未添加className組件內(nèi)無尺寸類Button、DropdownMenuItem、Alert、Sidebar*等組件內(nèi)部的圖標是否沒有任何size-*、w-* h-*、mr-*類組件對象傳遞自定義組件接收圖標時是否使用icon{SomeIcon}類型為React.ComponentType或LucideIcon而非字符串鍵查找表頁面級場景例外非 shadcn 組件內(nèi)使用圖標時尺寸與間距是否仍由你自己負責此時size-*類可用對照這三條規(guī)則與本倉庫的 packages/ui 組件實現(xiàn)、apps/app 頁面代碼你就能寫出與設計系統(tǒng)完全一致、類型安全且易于維護的 shadcn 圖標代碼。【免費下載鏈接】react-starter-kitModern React starter kit with Bun, TypeScript, Tailwind CSS, tRPC, Stripe, and Cloudflare Workers. Production-ready monorepo for building fast web apps.項目地址: https://gitcode.com/gh_mirrors/rea/react-starter-kit創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考