shadcn/ui 遷移參考Radix 到 Base UI 的 Disclosure 與 Toggle 組件族 Props 映射全解【免費下載鏈接】uiA set of beautifully-designed, accessible components and a code distribution platform. Works with your favorite frameworks. Open Source. Open Code.項目地址: https://gitcode.com/GitHub_Trending/ui/ui本篇指南基于 shadcn/ui 倉庫內(nèi)置的遷移技能文檔 disclosure.md系統(tǒng)講解 accordion、collapsible、tabs、toggle、toggle-group、toolbar 六個組件從 Radix UI 遷移到base-ui/react時的部件改名、Props 簽名變化、data 屬性與 CSS 變量改寫規(guī)則。讀完本文你可以對照倉庫中的 registry 金標實現(xiàn)golden pair逐行完成一個項目里全部可折疊/可切換類組件的遷移并正確重寫配套樣式而不會遺漏行為差異。這份文檔在遷移體系中的位置shadcn/ui 倉庫在 skills/migrate-radix-to-base/ 目錄下內(nèi)置了一套遷移知識庫供遷移 Agent 與開發(fā)者共同使用SKILL.md定義遷移流程preflight 檢查、golden pair 策略、漸進/整項目兩種模式、硬規(guī)則、.migration/component.md報告格式disclosure.md本文主體disclosure toggle 組件族的 Props 映射表accordion、collapsible、tabs、toggle、toggle-group、toolbarclass-mapping.mdclassName / cva / cn 中的 data 選擇器與 CSS 變量機械改寫表universal-patterns.md導入改寫、asChild→render通用模式、部件改名速查表consumer-props.md應(yīng)用側(cè)調(diào)用點consumerProps 改寫清單。disclosure.md的映射依據(jù)是 Radix 官方 primitives 文檔與 Base UI 官方.md文檔的交叉核對并對照已安裝的base-ui/react1.6.0的.d.ts文件進行了校驗原文注明Base UI 官方 accordion 文檔頁面有滯后此處以類型聲明為準。因此本文所有結(jié)論的適用前提是Base UI 1.6.0。倉庫內(nèi)apps/v4/registry/bases/{base,radix}/ui/下成對存放的組件實現(xiàn)如 base/ui/accordion.tsx 與 radix/ui/accordion.tsx正是這些映射關(guān)系的可驗證實現(xiàn)證據(jù)。全組件通用約定以下五條約定適用于后文所有組件遷移時先整體過一遍asChildboolean默認false→render。類型從boolean變?yōu)镽eactElement | (props: HTMLProps, state) ReactElement。簽名變了不再是包裹一個子元素而是把元素直接傳給renderBase UI 會把 props 合并到該元素上。渲染為按鈕的部件還額外接受nativeButton默認true當render產(chǎn)出的不是button元素時設(shè)為false。className和style支持函數(shù)式取值(state) value。Radix 的data-[state...]值屬性變?yōu)?Base UI 的存在性屬性data-open、data-closed、data-pressed、data-active——狀態(tài)由屬性是否存在表達而非屬性值。Base UI 所有 change 回調(diào)都新增了第二個eventDetails參數(shù){ reason, event, cancel(), ... }可用于阻止狀態(tài)變更。Radix 的dirprop 全部移除Base UI 從 DOMdir屬性或DirectionProvider讀取方向。accordion部件映射Root → Root、Item → Item、Header → Header、Trigger → Trigger、Content → Panel。Accordion.Root → Accordion.RootRadix prop類型 / 默認值Base UI 對應(yīng)遷移說明asChildboolean/falserender簽名變更。把元素傳給render而不是包裹子元素。type必填single \| multiple/ —multiple簽名變更。typemultiple→multipleboolean默認falsetypesingle→ 省略。valuestringsingle或string[]multiple/ —value簽名變更。Base UI 永遠是數(shù)組Value[]Value anysingle 模式也不例外valuea→value{[a]}。defaultValuestring或string[]/ —defaultValue與value相同的數(shù)組注意事項。onValueChange(value: string) void或(value: string[]) void/ —onValueChange簽名變更(value: Value[], eventDetails: Accordion.Root.ChangeEventDetails) void。永遠收到數(shù)組single 模式需value[0]解包。collapsibleboolean/false— 移除Base UI single 模式永遠可折疊。若要禁止關(guān)閉最后一個打開項即 Radixcollapsible{false}的默認行為需控制value并忽略數(shù)組為空的更新或在value.length 0時調(diào)用eventDetails.cancel()。disabledboolean/falsedisabled默認false相同。dirltr \| rtl/ltr— 移除用 DOMdir屬性 /DirectionProvider。orientationvertical \| horizontal/vertical— 移除prop 存在但已廢棄為空操作Base UI 遵循 APG 指引更新移除了 roving 方向鍵焦點orientation及l(fā)oopFocus不再影響鍵盤行為。不要帶過去。Accordion.Item → Accordion.ItemRadix prop類型 / 默認值Base UI 對應(yīng)遷移說明asChildboolean/falserender簽名變更。value必填string/ —value約束變化Base UI 的value是any且可選省略時按索引自動生成。為保持一致性建議繼續(xù)傳字符串。disabledboolean/falsedisabled默認false相同。Accordion.Header → Accordion.HeaderRadix prop類型 / 默認值Base UI 對應(yīng)遷移說明asChildboolean/falserender簽名變更。兩者默認都渲染h3。Accordion.Trigger → Accordion.TriggerRadix prop類型 / 默認值Base UI 對應(yīng)遷移說明asChildboolean/falserender另有nativeButton默認true簽名變更。Accordion.Content → Accordion.PanelRadix prop類型 / 默認值Base UI 對應(yīng)遷移說明asChildboolean/falserender簽名變更。forceMounttrue \| undefined/ —keepMountedboolean默認false改名。forceMount→keepMounted關(guān)閉的面板保留在 DOM 中但隱藏。Root上也有同名 prop可一次性作用于所有面板。Base UI 獨有、值得知道的 propsRoot.hiddenUntilFound/Panel.hiddenUntilFound默認false使用hiddenuntil-found讓瀏覽器頁內(nèi)查找能展開面板會覆蓋keepMounted。Radix 無對應(yīng)物。Root.keepMounted按面板keepMounted的根級版本。Item.onOpenChange(open: boolean, eventDetails: Accordion.Item.ChangeEventDetails) void逐項的展開回調(diào)。Radix 無對應(yīng)物。Trigger.nativeButton默認true。所有部件的className/style狀態(tài)函數(shù)形式。data 屬性映射accordionRadixBase UI備注Item/Header/Content [data-stateopen \| closed]Item、Headerdata-open存在性Paneldata-open存在性accordion 部件沒有data-closed與 collapsible 不同關(guān)閉態(tài)樣式按缺少data-open書寫。Trigger [data-stateopen]Trigger [data-panel-open]改名。Trigger 專用于data-panel-open而不是data-open。[data-disabled][data-disabled]相同Root、Item、Header、Trigger、Panel。[data-orientation]所有部件Root、Paneldata-orientation隨 orientation 一起廢棄避免依賴?！狪tem/Header/Panel [data-index]Base UI 獨有數(shù)字項索引?！狿anel [data-starting-style]、[data-ending-style]Base UI 獨有CSS transition 動畫鉤子替代 Radix 的掛載/卸載動畫模式。CSS 變量映射accordionRadixBase UI--radix-accordion-content-height--accordion-panel-height--radix-accordion-content-width--accordion-panel-width倉庫實現(xiàn)證據(jù)registry 中的 accordion 金標對對比 radix/ui/accordion.tsx 與 base/ui/accordion.tsx上述規(guī)則逐條落地導入與類型import { Accordion as AccordionPrimitive } from radix-uiReact.ComponentPropstypeof AccordionPrimitive.Root→import { Accordion as AccordionPrimitive } from base-ui/react/accordionAccordionPrimitive.Root.Props子路徑導入、類型寫法變化見 universal-patterns.mdAccordionPrimitive.Content→AccordionPrimitive.Panel類型AccordionPrimitive.Panel.PropsTrigger 類名中 Radix 版的disabled:pointer-events-none disabled:opacity-50變?yōu)?Base UI 版的aria-disabled:pointer-events-none aria-disabled:opacity-50——這與 class-mapping.md 的禁用態(tài)鉤子規(guī)則一致accordion trigger 在 Base UI 中用aria-disabled表達禁用而非disabled屬性disabled:*類在此處成為死代碼需替換為aria-disabled:*面板內(nèi)部高度動畫Radix 版寫h-(--radix-accordion-content-height)Base UI 版寫h-(--accordion-panel-height) contenteditable="false">【免費下載鏈接】uiA set of beautifully-designed, accessible components and a code distribution platform. Works with your favorite frameworks. Open Source. Open Code.項目地址: https://gitcode.com/GitHub_Trending/ui/ui創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考