Uniapp Page Components Skill

uniapp 常用组件化页面 Skill

定位

本 skill 是独立的 uniapp 组件化页面技能，覆盖 22 个高频组件——把最高频、结构最固定的页面抽象成可复用组件，复制进项目、往 slot 填内容即可用，自由化高、无需重写布局。

与相关 skill 的定位边界：

组合工作流（与其它 uniapp 技能配合）

本 skill 位于 uniapp 技能链路的「页面组件层」，完整组合链路：

协作要点：

1. 层级定位：uniapp-app-generate-skill 提供原子组件（AppButton / AppTab / AppInput / AppPopup / AppNavbar），本 skill 提供页面骨架组件。组件内部的基础 UI 是"默认实现"，若项目已有共享组件体系，优先用本 skill 暴露的 slot（#tab / #footer / #navbar / #plus-panel / #header 等）注入共享组件，避免重复造轮子。
2. 样式三源合一：主题变量（theme-skill CSS 变量，运行时换肤）+ SCSS token（style-skill，编译期注入）可共存；本 skill 组件只依赖前者，保证"复制即用"。桥接细节见 references/theme-integration.md §5。
3. 数据只做展示：组件的 list / messages / feedList / groups / resultList 等只接收数据；分页、加载、发送、搜索、提交、登录等副作用一律由页面层调用 request-skill 封装处理，组件只 emit 事件。
4. 命名与目录对齐：组件目录小写 kebab-case、components/<name>/<name>.vue，遵循 standard-skill 命名规范与 easycom 默认规则。

组件清单

组件模板位于本 skill 的 components/ 目录，共 22 个（6 基础 + 6 业务 + 10 页面）：

基础组件（6）

业务组件（6）—— 组合空壳组件实现，不改空壳

页面组件（10）

设计要点：

• BaseCard 是托底组件：image-card 直接继承其入参；tab-list-page / profile-page 内部引用 BaseCard，并暴露 cardProps 透传。
• 高度自由化：每个组件核心内容都由 slot 决定，内置"默认参数 + 默认数据"，可整体替换或逐项覆盖，也可给组件新增 props/emit。
• 内部依赖：user-card / comment-item / chat-page / moments-page / profile-page 依赖 base-avatar；form-page 依赖 base-navbar + base-button；home-page 依赖 base-navbar + base-tabbar；login-page 依赖 base-button；tab-list-page / profile-page / image-card 依赖 base-card；user-card 依赖 base-card + base-button；comment-item 依赖 base-card；empty / result-page 依赖 base-button。复制时连带。
• 默认数据：每个组件带贴合场景的默认数据，复制即可跑通，替换真实数据即可上线。
• 业务组件扩展机制：业务组件 = 组合空壳组件实现，不改空壳，颗粒度小于页面组件。当用户说"帮我做个 XX 卡片/列表项/状态页"等具体原型需求时，先在本技能的业务组件清单中查找；若有则生成对应组件，若无则按此模式基于空壳组合出新的业务组件（见「组件调整模式」）。

When to Use（触发词）

技能共 22 个组件，一句话描述"要做的页面/组件/操作"即可命中，不要求说组件名：

按组件触发

组件扩展机制（业务组件）

业务组件 = 组合空壳组件实现，不改空壳，颗粒度小于页面组件。当用户说"帮我做个 XX 卡片/列表项/状态页"等具体原型需求时：

1. 先在上方「按组件触发」表中查找——有则生成该业务组件；
2. 若无，按「组件调整模式」基于空壳组件（base-card / base-button / base-form-item 等）组合出新业务组件，放 components/ 下，同样 slot + TS Props + 主题变量。

参数与内容调整（任何组件）

• 调外观："卡片圆角大一点" / "按钮圆角改大" / "导航栏背景透明" / "内边距改小" / "加个阴影" / "加边框"
• 可交互："这个卡片要能点击，点击触发事件" / "按钮点击触发事件" / "菜单切换触发 tabChange"
• 填内容："在卡片里加标题/头部/底部" / "登录表单里加个密码框" / "首页加个金刚区区块"（slot）
• 透传统一调整："把列表里所有卡片的圆角/间距统一改一下"（cardProps）
• 新增参数："给组件加一个 prop XX" / "加个参数控制是否显示 XX"
• 变量化："别写死颜色，用主题变量"
• 不写死内容："卡片内容我自己填" / "表单/登录/搜索内容我自己填"

通用触发

• "生成页面组件 / 组件化页面"
• "用主题系统给这些页面配色 / 换肤"
• "我项目里没这些页面，帮我生成几个常用的"
• "用自定义底部菜单替换现有 tabBar" / "tab 页面换自定义头部菜单"
• "加基础组件：按钮、导航栏、底部菜单、表单"

工作流程

Step 1：确认目标与自动检测主题系统

1. 与用户确认要生成哪些组件（可多选，共 22 个）。
2. 自动检测项目主题系统并自动对齐颜色/尺寸（完整流程见 references/theme-detect.md）：
   • 定位变量文件：扫描 App.vue 的 <style>、src/styles/、static/css/、uni.scss，找到主题变量定义位置；
   • 识别命名风格：CSS 变量（--color-primary/--primary-500/--brand-*）还是 SCSS（$primary）/ LESS（@primary）；
   • 读取值：主色值、语义色体系、尺寸单位（rpx/px/rem）、间距/圆角阶梯、是否支持 data-theme 深色切换；
   • 三场景自动对齐：

     检测结果	处理方式
     命名风格一致	组件原样复制，零改动
     命名风格不同	在项目生成桥接文件（项目变量 → 组件语义变量），不改组件内部
     无主题系统	自动提取项目高频品牌色生成变量组（或先跑 uniapp-theme-skill 初始化，推荐）

   • 检测结果输出给用户确认后进入下一步。
3. 状态栏提示：base-navbar（及引用它的 form-page / home-page）默认 statusBarHeight=0；小程序端建议在 App.vue 定义 --status-bar-height: 44px，否则导航栏贴顶。

Step 2：复制组件进项目

把选中的组件目录复制到项目 src/components/ 下（保持 <组件名>/<组件名>.vue 结构）。注意内部依赖：

Step 3：注册组件

本模块的页面组件目录为 components/<组件名>/<组件名>.vue，满足 uni-app Vue3 easycom 默认规则， { "easycom": { "autoscan": true } } 即可直接使用 <chat-page>、<search-page> 等标签。

但 base- 容器/组件不满足默认规则*（容器在 containers/<name>/index.vue， 内置组件在 components/<category>/<name>/index.vue），必须额外注册 custom 规则， 否则 <base-card> / <base-button> 扫不到，页面直接空白：

jsonCopy code
// pages.json
{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^base-card$": "@/containers/base-card/index.vue",
      "^base-button$": "@/components/form/base-button/index.vue"
    }
  }
}

完整规则由 uniapp-base-skill 的 node scripts/gen-easycom.js 从注册表生成 （产物 easycom.json），以 base-skill 生成的为准，不要手写维护。 若项目未开启 autoscan，则全部改用手动 import（参考 references/theme-integration.md §3）。

Step 4：生成使用示例

按 references/page-specs.md 中对应组件的「完整页面示例」为用户生成可运行的 page 落地（含 mock 数据 + 交互），并给出该组件的 Props/Slots/Emits 速查表。用户确认后可在示例页基础上替换真实数据。

Step 5：验证

• 检查组件是否使用了主题变量而非裸值（见红线 R01）；
• 检查 <image> 是否带 mode + error 兜底、可点击区域是否 ≥ 88rpx；
• 确认内部依赖组件已一并复制；
• 确认 easycom 注册与页面引用路径正确；
• 提示用户运行编译确认。

组件调整模式

当用户说"卡片圆角改大"、"给组件加个参数"、"表单内容我自己填"等时，按以下规则响应（不要重写组件）：

调整完成后必须复查红线 R01（无新硬编码）、R03（新参数有默认值）、R10（保留扩展口）。

自动替换现有导航栏 / TabBar（重要能力）

当用户说"用自定义底部菜单替换现有 tabBar"、"tab 页面换自定义头部菜单"时，按下面流程自动更新页面，无需手动逐个改：

1. 底部菜单：读 pages.json 的 tabBar → 生成 base-tabbar

读取项目 pages.json 的 tabBar.list（pagePath / text / iconPath / selectedIconPath），自动转换为 base-tabbar 的 items：

替换步骤：

1. 新建 src/custom-tab-bar/index.vue（微信自定义 tabBar 官方方案），内部渲染 base-tabbar；onChange 里 uni.switchTab({ url: '/' + item.key })。
2. 项目 pages.json 的 tabBar 增加 "custom": true（保留 list 作占位，原生 tabBar 不渲染）。
3. 每个 tab 页面 onShow 时同步当前激活 selected（base-tabbar 以 v-model 接收当前 key）。

不依赖微信官方 custom-tab-bar 也可：把 base-tabbar 直接放进各 tab 页面底部（页面根 height:100vh，内容区 padding-bottom 留出 tabbar 高度），change 事件由页面 uni.switchTab。推荐前者（一处维护）。

2. 头部菜单：只替换 tab 页面的导航栏

1. 仅对 tabBar 页面 生效，pages.json 对应页面设置 "navigationStyle": "custom"（普通详情页等非 tab 页不改）。
2. 每个 tab 页面模板顶部加：

vueCopy code
<template>
  <view class="page">
    <base-navbar
      :title="'首页'"            <!-- 取 pages.json 对应页 navigationBarTitleText -->
      :show-back="false"          <!-- tab 页无返回 -->
      :fixed="true"
      :placeholder="true"
      status-bar-height="var(--status-bar-height)"
    />
    <view class="page__content"><!-- 原页面内容 --></view>
  </view>
</template>

3. App.vue 定义 --status-bar-height（uni.getSystemInfoSync().statusBarHeight），否则导航栏贴顶。

3. 迁移注意

• 原生 tabBar 与自定义 tabBar 二选一；图标资源沿用现有 iconPath/selectedIconPath，零新增素材。
• 替换后必须验证：tab 切换高亮正确、首页无返回键、非 tab 页返回键正常、safe-area 底部间距正确。
• 改完后用 uniapp-code-audit-skill 复检跨端（小程序/H5/App）表现一致。

主题系统绑定规则

所有组件默认依赖 uniapp-theme-skill 主题变量，遵循"禁止写死"。

完整清单与无主题系统 fallback 表见 references/theme-integration.md；自动检测对齐流程见 references/theme-detect.md。

使用前提（重要）

1. 自定义导航栏：chat-page / product-detail-page / form-page / home-page 内置的是简化版导航栏（固定高度，未做状态栏高度适配与胶囊按钮对齐，微信小程序下会与默认导航栏叠加）。使用含导航栏的组件时，页面 pages.json 需设 "navigationStyle": "custom"；正式项目建议用项目已有 NavBar 替换，或通过对应 slot 传入项目导航栏。
2. 状态栏适配：base-navbar 使用小程序自定义导航时，需在 App.vue 定义 --status-bar-height（如 44px）或传入 status-bar-height prop；胶囊对齐属 app-generate AppNavbar 强约束场景，本技能导航栏为简易通用版。APP 端（Android/iOS）必须运行时动态获取状态栏高度（uni.getSystemInfoSync().statusBarHeight），详见 references/platform-app.md。login-page 无导航栏，无需处理。product-detail-page / chat-page 内置简化导航栏同理。
3. 容器高度：tab-list-page / chat-page / product-detail-page / search-page / form-page / home-page 根容器为 height: 100%，使用页面需给确定高度（如页面根 view 设 height: 100vh）。
4. 内部依赖：form-page / home-page / login-page / tab-list-page / profile-page / image-card 依赖基础组件，复制时连带复制（见 Step 2 表）。
5. 页面背景：各页面组件自带页面级背景（--bg-page），外层无需再包容器。

红线规则

本技能组件强制遵循以下红线：

References

• references/page-specs.md — 各组件 API 速查（Props / Slots / Emits / 默认数据 / mock 数据 / 完整页面示例 / 扩展建议）
• references/theme-integration.md — 主题变量清单、无主题系统 fallback 表、easycom 注册、状态栏适配
• references/theme-detect.md — 主题系统自动检测与对齐（变量定位、命名风格识别、三场景处理）
• references/platform-app.md — APP 端（Android/iOS）使用指南：状态栏动态适配、安全区、键盘、原生导航栏冲突
• components/ — 22 个组件模板（6 基础 + 6 业务 + 10 页面）