fmode-app/ui-kit

ui-kit 使用说明(官方 UI 组件底座 · 最小可复用集)

本目录是官方 UI 组件库的最小可复用集(复制自官方组件底座仓库),随本规范包一起分发。组件库版规范下,业务项目的 UI 组件一律从这里复制使用,禁止另造轮子、禁止引入第三方 UI 库。

⚠️ 本目录是生成物,禁止就地手改(v1.2 起)

本目录是仓库内工作副本 packages/ui-kit/(ng-packagr 打包、被 apps 实际消费的那份)的 单向快照。两份必须一致,否则母版就是一份过期快照 —— 别的项目照母版复制, 拿到的组件和我们跑通的不是同一个东西。

• 改组件:一律改 packages/ui-kit/src/lib/**,然后 pnpm sync:uikit-master 回写本目录。
• 校验是否漂移:pnpm check:uikit-master(有漂移则退出码 1,可挂 CI)。
• 同步只做目录前缀平移(src/lib/** → src/app/ui/**),其余按 README 的复制步骤原样保留; 本目录独有的文件脚本不删,只列出来交人判断(删文件不可逆,不该由脚本替人决定)。

目录内容

ui-kit/
├─ src/
│  ├─ app/ui/                  ← 全部可复用组件(必须整目录复制,见「连带说明」)
│  │  ├─ components/           桌面组件 75 个(button/badge/icon/modal/drawer/table/data-table/form/…)
│  │  │  └─ index.ts           桌面 barrel(75 条 export + ToastService 命名导出)
│  │  ├─ mobile/components/    移动端组件 62 个(选择器前缀 ui-m-*,44px 触控目标)
│  │  │  └─ index.ts           移动 barrel(62 条 export)
│  │  ├─ theme/                theme.service.ts(明暗/主题色)+ overlay-stack.service.ts(弹层堆叠)+ floating-panel.ts(浮层 fixed 定位控制器)+ floating-position.ts(定位纯函数)
│  │  └─ index.ts              ui/ 顶层 barrel
│  ├─ styles.css               全部语义 token(明暗两套 + 6 个 data-accent 主题色 + z-index 十级)+ @tailwind 指令
│  └─ styles.scss              ui-* 动画关键帧 + .animate-* 工具类 + prefers-reduced-motion
├─ tailwind.config.js          theme.extend.colors 把 token 映射成工具类(bg-surface/text-ink/…) + boxShadow 四级
└─ postcss.config.json         tailwindcss + autoprefixer

复制到业务项目(步骤)

1. 复制组件目录:ui-kit/src/app/ui/** → 项目 src/app/ui/(必须整目录,含 components/mobile/theme/index.ts)。
2. 复制样式入口:ui-kit/src/styles.css、ui-kit/src/styles.scss → 项目 src/。
3. 合并 Tailwind 配置:把 ui-kit/tailwind.config.js 的 theme.extend.colors 与 boxShadow 合并进项目 tailwind.config.js(宿主已是 3.x 的 content 需含 ./src/**/*.{html,ts})。
4. 引入 FontAwesome:angular.json 的 styles 加入 node_modules/@fortawesome/fontawesome-free/css/all.min.css;按 rules/04-技术栈规范.md 维护图标白名单,禁止全量 import。

依赖清单(宿主项目必须满足)

依赖	版本约束	说明
@angular/common / compiler / core / forms / platform-browser / router	20.3.x	前端框架
@fortawesome/fontawesome-free	^7.3.1	免费 solid 图标,经 Icon 组件或 fa-solid 类使用
rxjs	~7.8.0
tslib	^2.3.0
tailwindcss	^3.4.x	必须 3.x,勿混用 Tailwind 4 语法与 @tailwindcss/postcss(规范 rules/04 锁定 3.x)
autoprefixer / postcss	任意 3.x 配套	postcss 插件:tailwindcss + autoprefixer

注:本目录不含 package.json/angular.json——那是整库应用清单,业务项目无需照搬;以上依赖清单以本文件为准。

连带说明(为什么必须整目录复制)

部分组件非自包含,引用了同目录其他组件或服务,只拷单个组件会断链:

• modal.ts、drawer.ts → ../../theme/overlay-stack.service(多弹层 z-index 堆叠)
• select.ts、autocomplete.ts、cascader.ts、date-picker.ts、dropdown.ts、time-picker.ts、popover.ts、tooltip.ts、popconfirm.ts、data-table.ts → ../../theme/floating-panel + ../../theme/floating-position(浮层面板统一 fixed + FloatingPanelController 定位,必须随行)
• coupon.ts、upload-avatar.ts、sku-selector.ts → ../button/button
• form.ts → input/select/textarea/button
• 移动端:coupon → UiMButton;cart-cell → checkbox/stepper/button;goods-card → tag/price;sku → price/button/stepper

因此:一律整目录复制 src/app/ui/**,不要按需挑文件夹。

学员端(D11 移动端)新增组件 · v1.2 起

随"通用 AI 陪练基座"学员端落地补入,均为移动端骨架件,选择器 ui-m-*:

组件	用途	必须知道的约束
ui-m-icon-btn	页头图标按钮	触控目标 ≥44px;[dot] 为未读红点;ariaLabel 必填
ui-m-chip	筛选胶囊	命中态 [on];热区靠 ::after 撑到 44px,不改视觉高度
ui-m-section-header	区块标题 + 右侧动作 + 计数	右侧动作走 (action) 输出,不是路由跳转
ui-m-task-item	任务条	[tagText]/[tagTone] 与尾部箭头互斥:给了标签就不渲染箭头
ui-m-scene-card	练习场景卡	难度徽标 + 目标 + 客户开场白 + 主按钮
ui-m-fixlist	实测定高内滚容器	见下

ui-m-fixlist 口径(实测定高内滚,UI 规范 §4.9.2)

不是"给个 max-height 就完事":容器渲染后实测前 N 个可见项的 offsetHeight 与间距, 再注入 max-height = N 项高 + (N-1) × gap;项数 ≤ N 时不设固定高度(否则底部留一条空白)。

• 禁止用 overscroll-behavior: contain 阻断滚动链 —— 内滚到底后用户手势应当接力给页面, 否则在手机上表现为"卡住不动"。
• [resetKey] 变化时归零 scrollTop。键只放筛选条件,不要放数据数组: 放进数组引用会让每次刷新数据都把用户弹回顶部。

规范引用

• 组件复用纪律、令牌同源、扩展回写:见 rules/18-UI设计规范.md。
• 依赖与版本基线:见 rules/04-技术栈规范.md。
• 组件实时预览:官方底座仓库自带 showcase 应用(pnpm start 后访问本地开发服务器),本包不携带展示应用。

组件数说明

桌面 75 个、移动 62 个(含 calendar/sku/watermark/trend/count-up/year-month-picker 等未在旧文档列出的组件),以本目录 components/ 实数为准。

本次计数口径:桌面 75 个组件目录 / 75 条 barrel 导出(+ ToastService 命名导出共 76 行 export); 移动 62 个(原 56 个 + 学员端 D11 新增 6 个:icon-btn / chip / section-header / task-item / scene-card / fixlist)。旧文档记的 74 / 56 是上一版快照的数字。

浮层面板定位模式(v1.1 起)

底座浮层面板统一 fixed + FloatingPanelController 定位(见 theme/floating-panel.ts + theme/floating-position.ts 纯函数):面板按视口坐标钉在触发元素旁,监听 scroll(capture)/resize/ResizeObserver 重算,解决「下拉在滚动容器、overflow-hidden 卡片内被裁剪」。新开发组件禁止再写 absolute + mt-* 的旧式面板定位;改动浮层组件一律照抄现有固定模式(见 select.ts 的 #trigger/#panel + panelPos + attachPanel 写法)。