文章目录前言一、ArkTS 模块依赖单向是铁律1.1 模块图1.2 与 TypeScript 的差异1.3 高发场景二、坑自定义组件传参为何容易成环2.1 误解「传组件」在 ArkTS 里是什么2.2 典型错误链路2.3 复制类型的「伪解法」三、解法一接口抽离Contracts 层—— 最推荐3.1 思路3.2 Demo 契约层3.3 子组件只 import 契约3.4 父组件import 契约 子组件3.5 命名与放置建议四、解法二import type —— 打断运行时环4.1 import vs import type4.2 适用场景4.3 Demo 实现4.4 注意事项五、解法三BuilderParam —— 插槽彻底解耦5.1 思路5.2 DemoSlotContainer5.3 页面层组装5.4 与 Vue/React 插槽的对应六、三种方案对照总表七、选型决策树八、多模块工程的额外建议8.1 common_har 放契约feature 放 UI8.2 禁止的依赖方向8.3 排查工具九、系统性排查流程十、Demo 体验指南十一、生产环境 Checklist十二、总结附录快速参考卡前言项目越做越大组件拆分越来越细开发者常会遇到这样的场景父组件OrderList要渲染子组件OrderFooter并把自己的meta数据传下去OrderFooter的Prop类型又定义在OrderList里于是也import了OrderList。两边文件互相import编译器直接报错Circular dependency detected有人尝试把类型复制一份到子组件——能编过但类型两份、改一处漏一处。有人想把组件类当参数传——ArkTS 里根本不支持这种写法反而更容易绕进环里。ArkTS 在编译期禁止模块循环依赖这不是警告是硬错误。根因通常不在「组件传参」本身而在import 方向设计错误父子为了共享类型或引用组件形成了 A→B→A 的闭环。本文结合项目 Demo从循环依赖成因、ArkTS 模块规范、三种破局方案接口抽离、import type、BuilderParam到选型决策做一次完整拆解。读完后你应该能回答为什么「传个 Props 类型」就会触发循环依赖import type和import有什么本质区别容器组件如何在不 import 子组件的前提下完成组装一、ArkTS 模块依赖单向是铁律1.1 模块图每个.ets文件是一个模块。import语句建立有向依赖边A.ets ──import── B.ets ──import── C.ets ✅ 链式无环 A.ets ──import── B.ets ↑ │ └────import──────────┘ ❌ 环编译失败HarmonyOS ArkTS 编译器在构建依赖图时检测环路一旦发现即报Circular dependency。1.2 与 TypeScript 的差异TypeScript 对循环依赖有时能「侥幸编过」运行时靠加载顺序碰运气。ArkTS 更严格特性ArkTS循环依赖编译期拒绝组件传参传数据或Builder不传组件类引用类型导入支持import type编译后擦除多模块工程common_har契约层尤为重要1.3 高发场景场景典型写法为何成环父子互引类型父 export interface子 import 父取类型父又 import 子组件兄弟组件互引A 引用 B 的 PropsB 引用 A 的回调类型双向 importFeature 互引模块 A 页面用模块 B 组件反之亦然跨模块环把组件当参数容器 import 子组件 AA 又 import 容器配置配置与渲染绑死Demo 中的错误模式OrderList.ets ──import── OrderFooter.ets ^ │ └────────import─────────────┘ 报错Circular dependency detected// OrderList.etsimport{OrderFooter}from./OrderFooterexportinterfaceOrderListMeta{total:number}// OrderFooter.etsimport{OrderListMeta}from./OrderList// ← 形成环Componentstruct OrderFooter{Propmeta:OrderListMeta}二、坑自定义组件传参为何容易成环2.1 误解「传组件」在 ArkTS 里是什么ArkUI没有React 式的「把组件类当变量传递」// ❌ ArkTS 不支持container.render(ChildComponent)正确做法是传数据Prop/Link传 interface 对象传 BuilderBuilderParam传 UI 构建函数直接组合父build()里写ChildComponent({ ... })。成环往往发生在第 1 种父定义了interface子要引用这个 interface 的类型于是import了父模块父模块又import了子组件——环闭合。2.2 典型错误链路① OrderListPanel 需要渲染 OrderFooter ↓ ② OrderListPanel.ets 添加import { OrderFooter } from ./OrderFooter ↓ ③ OrderFooter 的 Prop meta 类型是 OrderListPanelMeta ↓ ④ OrderFooter.ets 添加import { OrderListPanelMeta } from ./OrderListPanel ↓ ⑤ 编译器A→B→A报错2.3 复制类型的「伪解法」把OrderListPanelMeta在OrderFooter.ets里再定义一遍能消除 import 环但两份类型易漂移字段增删时两边手动同步维护灾难不符合 DRY不适合生产。正解是把类型抽到第三方或import type打断运行时环。三、解法一接口抽离Contracts 层—— 最推荐3.1 思路把所有跨组件共享的interface、type、常量抽到独立契约文件父子只依赖契约不互相依赖CyclicDepContracts.ets (ProductItem, ShelfLayoutMetrics) ↑ ↑ ProductShelf.ets ProductBadge.ets └────import───┘ 单向Shelf → Badge契约层无环3.2 Demo 契约层CyclicDepContracts.etsexportinterfaceProductItem{id:stringtitle:stringprice:numbertag:string}exportinterfaceShelfLayoutMetrics{columnCount:numberitemHeight:number}exportinterfaceBadgeStyleOptions{accentColor:stringcompact:boolean}3.3 子组件只 import 契约ProductBadge.etsimport{BadgeStyleOptions,ProductItem,ShelfLayoutMetrics}from./CyclicDepContractsComponentexportstruct ProductBadge{Propitem:ProductItemProplayout:ShelfLayoutMetricsPropstyle:BadgeStyleOptions// ...}不 importProductShelf。3.4 父组件import 契约 子组件ProductShelf.etsimport{ProductItem,ShelfLayoutMetrics,...}from./CyclicDepContractsimport{ProductBadge}from./ProductBadgeComponentexportstruct ProductShelf{Propitems:ProductItem[]build(){ForEach(this.items,(item:ProductItem){ProductBadge({item:item,layout:this.layout,style:this.badgeStyle})})}}依赖方向ProductShelf → ProductBadge → ContractsProductBadge不回头引ProductShelf。无环。3.5 命名与放置建议建议说明文件名*Contracts.ets、*Types.ets、*Models.ets放置位置多模块时放common_har各 feature 共同引用内容仅 interface / type / 常量不放 Component原则契约层不 import 任何 UI 组件四、解法二import type—— 打断运行时环4.1importvsimport type// 运行时 import会建立模块依赖边import{OrderListPanelMeta,createOrderListMeta}from./OrderListPanel// 类型 import仅编译期使用编译后擦除不建立运行时依赖importtype{OrderListPanelMeta}from./OrderListPanel维度importimport type运行时依赖✅ 建立❌ 不建立可导入值/函数✅❌ 仅类型打断循环依赖不能单独解决双向 import可打断单向类型回引4.2 适用场景子组件只需要父组件导出的类型不需要父组件的运行时值函数、组件实例时用import type。4.3 Demo 实现OrderListPanel.ets父runtime import 子import{OrderFooter}from./OrderFooterexportinterfaceOrderListPanelMeta{totalCount:numberselectedId:stringlistTitle:string}Componentexportstruct OrderListPanel{Statemeta:OrderListPanelMetacreateOrderListMeta()build(){OrderFooter({meta:this.meta})}}OrderFooter.ets子仅 type import 父importtype{OrderListPanelMeta}from./OrderListPanelconstDEFAULT_ORDER_META:OrderListPanelMeta{totalCount:3,selectedId:o2,listTitle:订单列表}Componentexportstruct OrderFooter{Propmeta:OrderListPanelMetaDEFAULT_ORDER_META// ...}依赖图OrderListPanel.ets ──runtime import── OrderFooter.ets ↑ │ └──── import type only (擦除) ─────────┘ 运行时单向类型双向环被打断4.4 注意事项要点说明默认值不能import { createOrderListMeta }若会形成 runtime 环可内联常量或抽到 Contracts仅 type 不够时若子组件还需父组件的函数/组件改用具抽离导出位置类型可与组件同文件 export配合import type使用五、解法三BuilderParam—— 插槽彻底解耦5.1 思路容器组件不 import 任何具体子组件只声明一个 Builder 插槽由页面层注入 UICatalogPage.ets ├─ import SlotContainer └─ import ProductBadge SlotContainer 不 import ProductBadge → 无环5.2 DemoSlotContainerimport{ProductItem}from./CyclicDepContractsComponentexportstruct SlotContainer{Propitems:ProductItem[]BuilderParamitemBuilder:(item:ProductItem)voidthis.defaultItemBuilderBuilderdefaultItemBuilder(item:ProductItem){Text(item.title)}build(){ForEach(this.items,(item:ProductItem){this.itemBuilder(item)})}}SlotContainer只知道ProductItem数据结构来自 Contracts不知道ProductBadge的存在。5.3 页面层组装CyclicDepPitfallDemo.etsBuilderbadgeSlotBuilder(item:ProductItem){ProductBadge({item:item})}build(){SlotContainer({title:Catalog 组装,itemBuilder:this.badgeSlotBuilder})}依赖方向Page → SlotContainer Page → ProductBadge SlotContainer → Contracts仅数据容器与子组件互不 import环不可能产生。5.4 与 Vue/React 插槽的对应概念ArkUI默认插槽BuilderParam content: () void作用域插槽BuilderParam itemBuilder: (item: T) void组装位置页面 / 父级组件的Builder方法项目里DSCard、ErrorBoundary已用BuilderParam content模式循环依赖场景可推广为带参数的 Builder。六、三种方案对照总表方案核心手段依赖结构适用场景❌ 互相 import无A ↔ B编译失败✅ 接口抽离*Contracts.etsA → C, B → C, A → B通用首选多模块共享类型✅ import type类型擦除A → BB -/type→ A子仅需父类型无需父运行时✅ BuilderParam插槽注入Page → A, Page → B容器与渲染组件完全解耦七、选型决策树组件传参导致循环依赖 │ ├─ 多个组件共享同一套 Props / 数据模型 │ └─ 是 → 抽到 *Contracts.ets推荐 │ ├─ 子组件仅需父组件的 interface不需父的值/组件 │ └─ 是 → import type { XxxMeta } from ./Parent │ ├─ 容器不应感知具体子 UI列表项、卡片样式多变 │ └─ 是 → BuilderParam 由页面注入 │ ├─ feature 模块互相引用 │ └─ 契约放 common_harUI 各自单向依赖 │ └─ 仍成环 └─ 画依赖图找回路中最弱的一边用 type import 或抽离打断八、多模块工程的额外建议8.1 common_har 放契约feature 放 UIcommon_har/ └── OrderContracts.ets ← interface、enum、常量 entry / feature_hsp/ └── OrderListPanel.ets ← Componentimport common_har └── OrderFooter.ets规则common_har永远不 importfeature里的组件。8.2 禁止的依赖方向feature_A ── feature_B ── feature_A ❌ common_har ── feature_A ❌契约层不应依赖 UI8.3 排查工具DevEco依赖分析/ 模块图全局搜索import { Xxx } from梳理双向边新建文件前自问「这个 import 会不会让 B 也 import 我」九、系统性排查流程读报错定位涉及的两个或多个文件路径画依赖图列出每个文件的import目标找环A→B→…→A 的闭合路径分类需求共享的是类型、组件还是UI 片段选策略类型 → 抽离或import typeUI →BuilderParam验证全量编译确认无 Circular dependency防复发新组件默认依赖 Contracts不跨级互引。十、Demo 体验指南路径entry/src/main/ets/cyclicdep/文件职责CyclicDepTypes.ets方案枚举、依赖图、代码片段CyclicDepContracts.ets契约层接口抽离ProductShelf.ets/ProductBadge.ets接口抽离 live demoOrderListPanel.ets/OrderFooter.etsimport type live demoSlotContainer.etsBuilderParam live demoCyclicDepPitfallDemo.ets主页面建议操作选❌ 互相 import阅读依赖图与「无法编译」说明打开解法对比依次看三种可运行预览切到✅ import type对照OrderFooter.ets仅import type的写法切到✅ BuilderParam看页面如何注入badgeSlotBuilder阅读底部「要点速记」。十一、生产环境 Checklist共享 interface 抽到*Contracts.ets或common_har子组件避免 runtimeimport父组件文件仅需类型时使用import type容器组件优先BuilderParam不 import 具体子 UI不在契约层写Componentfeature 模块间通过 common 层通信不直接互引新增 import 前检查是否形成 A→B→ACI 全量编译循环依赖零容忍十二、总结自定义组件传参触发循环依赖不是 ArkTS 故意刁难而是模块必须单向依赖的工程约束。核心结论说明报错根因父子或兄弟模块双向import形成环不推荐复制类型、强行 any、绕过编译首选接口抽离到*Contracts.ets轻量打断import type消除运行时回引UI 解耦BuilderParam页面层组装传参本质传数据 / Builder不传组件类记住一句话类型往上抽到契约层UI 往下交给 Builderimport 只许单向不许回头。附录快速参考卡// ❌ 形成环// OrderList.etsimport{OrderFooter}from./OrderFooterexportinterfaceOrderListMeta{...}// OrderFooter.etsimport{OrderListMeta}from./OrderList// ✅ 接口抽离// Contracts.etsexportinterfaceProductItem{id:string;title:string}// Shelf.ets Badge.ets 都只 import Contracts// ✅ import typeimporttype{OrderListPanelMeta}from./OrderListPanel// 不要import { createOrderListMeta } from ./OrderListPanel// ✅ BuilderParamBuilderParamitemBuilder:(item:ProductItem)void// Page: SlotContainer({ itemBuilder: this.badgeSlotBuilder })
文章目录前言一、ArkTS 模块依赖单向是铁律1.1 模块图1.2 与 TypeScript 的差异1.3 高发场景二、坑自定义组件传参为何容易成环2.1 误解「传组件」在 ArkTS 里是什么2.2 典型错误链路2.3 复制类型的「伪解法」三、解法一接口抽离Contracts 层—— 最推荐3.1 思路3.2 Demo 契约层3.3 子组件只 import 契约3.4 父组件import 契约 子组件3.5 命名与放置建议四、解法二import type —— 打断运行时环4.1 import vs import type4.2 适用场景4.3 Demo 实现4.4 注意事项五、解法三BuilderParam —— 插槽彻底解耦5.1 思路5.2 DemoSlotContainer5.3 页面层组装5.4 与 Vue/React 插槽的对应六、三种方案对照总表七、选型决策树八、多模块工程的额外建议8.1 common_har 放契约feature 放 UI8.2 禁止的依赖方向8.3 排查工具九、系统性排查流程十、Demo 体验指南十一、生产环境 Checklist十二、总结附录快速参考卡前言项目越做越大组件拆分越来越细开发者常会遇到这样的场景父组件OrderList要渲染子组件OrderFooter并把自己的meta数据传下去OrderFooter的Prop类型又定义在OrderList里于是也import了OrderList。两边文件互相import编译器直接报错Circular dependency detected有人尝试把类型复制一份到子组件——能编过但类型两份、改一处漏一处。有人想把组件类当参数传——ArkTS 里根本不支持这种写法反而更容易绕进环里。ArkTS 在编译期禁止模块循环依赖这不是警告是硬错误。根因通常不在「组件传参」本身而在import 方向设计错误父子为了共享类型或引用组件形成了 A→B→A 的闭环。本文结合项目 Demo从循环依赖成因、ArkTS 模块规范、三种破局方案接口抽离、import type、BuilderParam到选型决策做一次完整拆解。读完后你应该能回答为什么「传个 Props 类型」就会触发循环依赖import type和import有什么本质区别容器组件如何在不 import 子组件的前提下完成组装一、ArkTS 模块依赖单向是铁律1.1 模块图每个.ets文件是一个模块。import语句建立有向依赖边A.ets ──import── B.ets ──import── C.ets ✅ 链式无环 A.ets ──import── B.ets ↑ │ └────import──────────┘ ❌ 环编译失败HarmonyOS ArkTS 编译器在构建依赖图时检测环路一旦发现即报Circular dependency。1.2 与 TypeScript 的差异TypeScript 对循环依赖有时能「侥幸编过」运行时靠加载顺序碰运气。ArkTS 更严格特性ArkTS循环依赖编译期拒绝组件传参传数据或Builder不传组件类引用类型导入支持import type编译后擦除多模块工程common_har契约层尤为重要1.3 高发场景场景典型写法为何成环父子互引类型父 export interface子 import 父取类型父又 import 子组件兄弟组件互引A 引用 B 的 PropsB 引用 A 的回调类型双向 importFeature 互引模块 A 页面用模块 B 组件反之亦然跨模块环把组件当参数容器 import 子组件 AA 又 import 容器配置配置与渲染绑死Demo 中的错误模式OrderList.ets ──import── OrderFooter.ets ^ │ └────────import─────────────┘ 报错Circular dependency detected// OrderList.etsimport{OrderFooter}from./OrderFooterexportinterfaceOrderListMeta{total:number}// OrderFooter.etsimport{OrderListMeta}from./OrderList// ← 形成环Componentstruct OrderFooter{Propmeta:OrderListMeta}二、坑自定义组件传参为何容易成环2.1 误解「传组件」在 ArkTS 里是什么ArkUI没有React 式的「把组件类当变量传递」// ❌ ArkTS 不支持container.render(ChildComponent)正确做法是传数据Prop/Link传 interface 对象传 BuilderBuilderParam传 UI 构建函数直接组合父build()里写ChildComponent({ ... })。成环往往发生在第 1 种父定义了interface子要引用这个 interface 的类型于是import了父模块父模块又import了子组件——环闭合。2.2 典型错误链路① OrderListPanel 需要渲染 OrderFooter ↓ ② OrderListPanel.ets 添加import { OrderFooter } from ./OrderFooter ↓ ③ OrderFooter 的 Prop meta 类型是 OrderListPanelMeta ↓ ④ OrderFooter.ets 添加import { OrderListPanelMeta } from ./OrderListPanel ↓ ⑤ 编译器A→B→A报错2.3 复制类型的「伪解法」把OrderListPanelMeta在OrderFooter.ets里再定义一遍能消除 import 环但两份类型易漂移字段增删时两边手动同步维护灾难不符合 DRY不适合生产。正解是把类型抽到第三方或import type打断运行时环。三、解法一接口抽离Contracts 层—— 最推荐3.1 思路把所有跨组件共享的interface、type、常量抽到独立契约文件父子只依赖契约不互相依赖CyclicDepContracts.ets (ProductItem, ShelfLayoutMetrics) ↑ ↑ ProductShelf.ets ProductBadge.ets └────import───┘ 单向Shelf → Badge契约层无环3.2 Demo 契约层CyclicDepContracts.etsexportinterfaceProductItem{id:stringtitle:stringprice:numbertag:string}exportinterfaceShelfLayoutMetrics{columnCount:numberitemHeight:number}exportinterfaceBadgeStyleOptions{accentColor:stringcompact:boolean}3.3 子组件只 import 契约ProductBadge.etsimport{BadgeStyleOptions,ProductItem,ShelfLayoutMetrics}from./CyclicDepContractsComponentexportstruct ProductBadge{Propitem:ProductItemProplayout:ShelfLayoutMetricsPropstyle:BadgeStyleOptions// ...}不 importProductShelf。3.4 父组件import 契约 子组件ProductShelf.etsimport{ProductItem,ShelfLayoutMetrics,...}from./CyclicDepContractsimport{ProductBadge}from./ProductBadgeComponentexportstruct ProductShelf{Propitems:ProductItem[]build(){ForEach(this.items,(item:ProductItem){ProductBadge({item:item,layout:this.layout,style:this.badgeStyle})})}}依赖方向ProductShelf → ProductBadge → ContractsProductBadge不回头引ProductShelf。无环。3.5 命名与放置建议建议说明文件名*Contracts.ets、*Types.ets、*Models.ets放置位置多模块时放common_har各 feature 共同引用内容仅 interface / type / 常量不放 Component原则契约层不 import 任何 UI 组件四、解法二import type—— 打断运行时环4.1importvsimport type// 运行时 import会建立模块依赖边import{OrderListPanelMeta,createOrderListMeta}from./OrderListPanel// 类型 import仅编译期使用编译后擦除不建立运行时依赖importtype{OrderListPanelMeta}from./OrderListPanel维度importimport type运行时依赖✅ 建立❌ 不建立可导入值/函数✅❌ 仅类型打断循环依赖不能单独解决双向 import可打断单向类型回引4.2 适用场景子组件只需要父组件导出的类型不需要父组件的运行时值函数、组件实例时用import type。4.3 Demo 实现OrderListPanel.ets父runtime import 子import{OrderFooter}from./OrderFooterexportinterfaceOrderListPanelMeta{totalCount:numberselectedId:stringlistTitle:string}Componentexportstruct OrderListPanel{Statemeta:OrderListPanelMetacreateOrderListMeta()build(){OrderFooter({meta:this.meta})}}OrderFooter.ets子仅 type import 父importtype{OrderListPanelMeta}from./OrderListPanelconstDEFAULT_ORDER_META:OrderListPanelMeta{totalCount:3,selectedId:o2,listTitle:订单列表}Componentexportstruct OrderFooter{Propmeta:OrderListPanelMetaDEFAULT_ORDER_META// ...}依赖图OrderListPanel.ets ──runtime import── OrderFooter.ets ↑ │ └──── import type only (擦除) ─────────┘ 运行时单向类型双向环被打断4.4 注意事项要点说明默认值不能import { createOrderListMeta }若会形成 runtime 环可内联常量或抽到 Contracts仅 type 不够时若子组件还需父组件的函数/组件改用具抽离导出位置类型可与组件同文件 export配合import type使用五、解法三BuilderParam—— 插槽彻底解耦5.1 思路容器组件不 import 任何具体子组件只声明一个 Builder 插槽由页面层注入 UICatalogPage.ets ├─ import SlotContainer └─ import ProductBadge SlotContainer 不 import ProductBadge → 无环5.2 DemoSlotContainerimport{ProductItem}from./CyclicDepContractsComponentexportstruct SlotContainer{Propitems:ProductItem[]BuilderParamitemBuilder:(item:ProductItem)voidthis.defaultItemBuilderBuilderdefaultItemBuilder(item:ProductItem){Text(item.title)}build(){ForEach(this.items,(item:ProductItem){this.itemBuilder(item)})}}SlotContainer只知道ProductItem数据结构来自 Contracts不知道ProductBadge的存在。5.3 页面层组装CyclicDepPitfallDemo.etsBuilderbadgeSlotBuilder(item:ProductItem){ProductBadge({item:item})}build(){SlotContainer({title:Catalog 组装,itemBuilder:this.badgeSlotBuilder})}依赖方向Page → SlotContainer Page → ProductBadge SlotContainer → Contracts仅数据容器与子组件互不 import环不可能产生。5.4 与 Vue/React 插槽的对应概念ArkUI默认插槽BuilderParam content: () void作用域插槽BuilderParam itemBuilder: (item: T) void组装位置页面 / 父级组件的Builder方法项目里DSCard、ErrorBoundary已用BuilderParam content模式循环依赖场景可推广为带参数的 Builder。六、三种方案对照总表方案核心手段依赖结构适用场景❌ 互相 import无A ↔ B编译失败✅ 接口抽离*Contracts.etsA → C, B → C, A → B通用首选多模块共享类型✅ import type类型擦除A → BB -/type→ A子仅需父类型无需父运行时✅ BuilderParam插槽注入Page → A, Page → B容器与渲染组件完全解耦七、选型决策树组件传参导致循环依赖 │ ├─ 多个组件共享同一套 Props / 数据模型 │ └─ 是 → 抽到 *Contracts.ets推荐 │ ├─ 子组件仅需父组件的 interface不需父的值/组件 │ └─ 是 → import type { XxxMeta } from ./Parent │ ├─ 容器不应感知具体子 UI列表项、卡片样式多变 │ └─ 是 → BuilderParam 由页面注入 │ ├─ feature 模块互相引用 │ └─ 契约放 common_harUI 各自单向依赖 │ └─ 仍成环 └─ 画依赖图找回路中最弱的一边用 type import 或抽离打断八、多模块工程的额外建议8.1 common_har 放契约feature 放 UIcommon_har/ └── OrderContracts.ets ← interface、enum、常量 entry / feature_hsp/ └── OrderListPanel.ets ← Componentimport common_har └── OrderFooter.ets规则common_har永远不 importfeature里的组件。8.2 禁止的依赖方向feature_A ── feature_B ── feature_A ❌ common_har ── feature_A ❌契约层不应依赖 UI8.3 排查工具DevEco依赖分析/ 模块图全局搜索import { Xxx } from梳理双向边新建文件前自问「这个 import 会不会让 B 也 import 我」九、系统性排查流程读报错定位涉及的两个或多个文件路径画依赖图列出每个文件的import目标找环A→B→…→A 的闭合路径分类需求共享的是类型、组件还是UI 片段选策略类型 → 抽离或import typeUI →BuilderParam验证全量编译确认无 Circular dependency防复发新组件默认依赖 Contracts不跨级互引。十、Demo 体验指南路径entry/src/main/ets/cyclicdep/文件职责CyclicDepTypes.ets方案枚举、依赖图、代码片段CyclicDepContracts.ets契约层接口抽离ProductShelf.ets/ProductBadge.ets接口抽离 live demoOrderListPanel.ets/OrderFooter.etsimport type live demoSlotContainer.etsBuilderParam live demoCyclicDepPitfallDemo.ets主页面建议操作选❌ 互相 import阅读依赖图与「无法编译」说明打开解法对比依次看三种可运行预览切到✅ import type对照OrderFooter.ets仅import type的写法切到✅ BuilderParam看页面如何注入badgeSlotBuilder阅读底部「要点速记」。十一、生产环境 Checklist共享 interface 抽到*Contracts.ets或common_har子组件避免 runtimeimport父组件文件仅需类型时使用import type容器组件优先BuilderParam不 import 具体子 UI不在契约层写Componentfeature 模块间通过 common 层通信不直接互引新增 import 前检查是否形成 A→B→ACI 全量编译循环依赖零容忍十二、总结自定义组件传参触发循环依赖不是 ArkTS 故意刁难而是模块必须单向依赖的工程约束。核心结论说明报错根因父子或兄弟模块双向import形成环不推荐复制类型、强行 any、绕过编译首选接口抽离到*Contracts.ets轻量打断import type消除运行时回引UI 解耦BuilderParam页面层组装传参本质传数据 / Builder不传组件类记住一句话类型往上抽到契约层UI 往下交给 Builderimport 只许单向不许回头。附录快速参考卡// ❌ 形成环// OrderList.etsimport{OrderFooter}from./OrderFooterexportinterfaceOrderListMeta{...}// OrderFooter.etsimport{OrderListMeta}from./OrderList// ✅ 接口抽离// Contracts.etsexportinterfaceProductItem{id:string;title:string}// Shelf.ets Badge.ets 都只 import Contracts// ✅ import typeimporttype{OrderListPanelMeta}from./OrderListPanel// 不要import { createOrderListMeta } from ./OrderListPanel// ✅ BuilderParamBuilderParamitemBuilder:(item:ProductItem)void// Page: SlotContainer({ itemBuilder: this.badgeSlotBuilder })
 到 Curl_pgrs_now() 的演进与实现)
