pda-kit-mcp-server 2.0.1

package/spec-data/navbar.md

@@ -0,0 +1,482 @@
+---
+id: navbar
+name: 导航栏
+category: "导航/Navigation"
+version: "1.0.0"
+source: PDAKit-基础组件
+source_url: https://mastergo.ky-tech.com.cn/goto/TXmPayyL
+source_doc_id: 103417331857122
+component_count: 8
+---
+
+> **🧠 AI 指令 — 强制 CSS（MANDATORY，逐字复制，禁止修改）**
+>
+> ```css
+> .navbar {
+>   display: flex; align-items: center; position: relative;
+>   width: 480px; height: 56px;     /* ⛔ 不是 48px */
+>   padding: 0 16px;
+>   background: var(--color-grey-2); /* ⛔ 不是 --color-grey-1 */
+>   flex-shrink: 0;
+> }
+> .navbar-back {
+>   width: 40px; height: 40px;      /* ⛔ 不是 48px */
+>   display: flex; align-items: center; justify-content: center;
+>   color: var(--color-black-6);
+> }
+> .navbar-title {
+>   position: absolute; left: 64px;  /* ⛔ 不是 left: 16px */
+>   font: 600 24px/36px "PingFang SC", -apple-system, sans-serif;
+>   color: var(--color-black-6);
+> }
+> .navbar-more {
+>   width: 40px; height: 40px;      /* ⛔ 必须有更多图标 */
+>   margin-left: auto;
+>   display: flex; align-items: center; justify-content: center;
+>   color: var(--color-black-6);
+> }
+> ```
+> ⛔ navbar 必须同时包含：返回图标 + 标题 + 更多图标。
+> ⛔ 标题用 `position: absolute; left: 64px`，不可用 `justify-content: center`。
+
+# 导航栏 Navigation
+
+PDAKit 导航栏体系：**顶部导航 6 变体 + 搜索栏 2 状态 + 底部标签栏 5 项 × 2 状态 + 组合**。
+
+> **状态命名统一**：底部标签 `on`（选中）/ `off`（未选中）；搜索 `default`（默认）/ `typed`（已输入）。
+> **颜色规则**：全部使用 Token（`--color-{色系}-{色阶}`），禁止 Hex。Token 定义见文末 [附录 A](#附录-a颜色-token)。
+
+---
+
+## 组件总览
+
+| 组件 | Key | 变体数 |
+|------|-----|--------|
+| 导航栏类型 | `013-导航栏类型` | 6 变体 |
+| 导航栏/搜索 | `017-导航栏-搜索` | 2 状态 |
+| 导航栏组合 | `016-导航栏组合` | 1（系统bar + 导航栏） |
+| 底部标签栏导航/组合 | `028-底部标签栏导航-组合` | 1（4 项组合） |
+| 底部标签栏导航/首页 | `026-底部标签栏导航-首页` | 2 状态 (on/off) |
+| 底部标签栏导航/任务 | `027-底部标签栏导航-任务` | 2 状态 (on/off) |
+| 底部标签栏导航/营地 | `023-底部标签栏导航-营地` | 2 状态 (on/off) |
+| 底部标签栏导航/我的 | `025-底部标签栏导航-我的` | 2 状态 (on/off) |
+
+> 导航栏组合 = 系统bar(56px, 仅浅色底) + 导航栏类型(56px)。底部标签栏整体高度 71px。
+
+---
+
+## 1. 导航栏类型（顶部导航）
+
+**描述**: 全局通用顶部导航，6 种标题类型可切换。高度固定 56px，背景 `--color-grey-2`。
+
+### Props
+
+| Prop | 类型 | 值 |
+|------|------|-----|
+| 导航栏类型 | enum | `默认标题` / `标签页-圆角` / `标签页-下划线` / `头部作业人` / `头部搜索` / `右侧按钮+菜单` |
+| 显示菜单 | boolean | 是否显示右侧「更多」图标（`40×40`，`icons/assets/common_ic_more_o.svg`）。`true` 时图标可见，点击必然唤起 [更多操作弹窗](more-actions.md)。除 `头部搜索` 外，其余变体默认 `true` |
+| 模块名称 | string | 任意 |
+
+### 尺寸规格
+
+| 属性 | 值 |
+|------|------|
+| 高度 | `56px` |
+| 背景 | `--color-grey-2`（`#F3F4F6`） |
+| 内边距 | 默认：无（子元素定位）；标签页类：t/b `7px`, l/r `12px`；作业人：t/b `6px`, l/r `12px`；搜索：t/b `8px`, l/r `12px` |
+| 返回图标 | `40×40`，`icons/assets/common_ic_arrow_two_left_o.svg`，颜色 `--color-black-6`（`#333333`） |
+| 更多图标 | `40×40`，`icons/assets/common_ic_more_o.svg`，颜色 `--color-black-6`（`#333333`） |
+
+---
+
+## 更多按钮与更多操作弹窗（强绑定）
+
+> **核心规则：导航栏右上角「更多」图标与 [更多操作弹窗](more-actions.md) 是强绑定关系。只要导航栏存在「更多」按钮，点击必然唤起更多操作弹窗，不可替换为其他行为。**
+
+### 绑定关系
+
+| 规则 | 说明 |
+|------|------|
+| **一对一绑定** | 导航栏的「更多」图标（`common_ic_more_o.svg`）→ 点击 → 唯一响应：底部弹出 [更多操作弹窗](more-actions.md) |
+| **不可解耦** | 「更多」按钮的行为固定为唤起更多操作弹窗。AI 生成代码时，不得将「更多」按钮绑定到其他页面、跳转或操作 |
+| **条件显隐** | 通过 `显示菜单` Props 控制「更多」图标是否渲染。`显示菜单=false` → 不渲染图标；`显示菜单=true` → 渲染图标且点击行为固定 |
+| **弹窗触发方式** | 底部 Sheet 由下向上滑入，`300ms ease-in`，详见 [more-actions.md](more-actions.md) |
+
+### 各变体「更多」按钮对照表
+
+| 导航栏类型 | 是否有「更多」 | 图标位置 | `显示菜单` 默认值 |
+|-----------|:---:|------|:---:|
+| `默认标题` | ✅ 有 | 最右侧 | `true` |
+| `标签页-圆角` | ✅ 有 | 最右侧 | `true` |
+| `标签页-下划线` | ✅ 有 | 最右侧 | `true` |
+| `头部作业人` | ✅ 有 | 右侧（作业人胶囊后） | `true` |
+| `头部搜索` | ❌ 无 | — | `false`（强制） |
+| `右侧按钮+菜单` | ✅ 有 | 最右侧（文字按钮后） | `true` |
+
+> **头部搜索**变体不含「更多」图标，因此不会触发更多操作弹窗。其余 5 个变体均含。
+
+### HTML 交互示例
+
+```html
+<!-- 导航栏 默认标题 + 更多按钮 → 唤起 more-actions -->
+<div class="navbar">
+  <img src="icons/assets/common_ic_arrow_two_left_o.svg" class="navbar-back" alt="返回" />
+  <span class="navbar-title">模块名称</span>
+  <!-- 更多按钮：点击唤起更多操作弹窗（强绑定，不可改为其他行为） -->
+  <img src="icons/assets/common_ic_more_o.svg" class="navbar-more"
+       onclick="openMoreActionsPanel()" alt="更多" />
+</div>
+
+<!-- 更多操作弹窗（受 navbar 强绑定调用） -->
+<div class="more-actions-panel" id="moreActionsPanel" style="display:none">
+  <!-- 见 more-actions.md 完整结构 -->
+</div>
+```
+
+### JS 交互示例
+
+```javascript
+// 打开更多操作弹窗（navbar 更多按钮强绑定）
+function openMoreActionsPanel() {
+  const panel = document.getElementById('moreActionsPanel');
+  panel.style.display = 'flex';
+  // 动画 class 由 more-actions.md 规范控制：slideUp 300ms ease-in
+  panel.classList.add('animate-slide-up');
+}
+
+// 关闭更多操作弹窗
+function closeMoreActionsPanel() {
+  const panel = document.getElementById('moreActionsPanel');
+  panel.classList.remove('animate-slide-up');
+  panel.style.display = 'none';
+}
+```
+
+---
+
+### 按变体
+
+#### 默认标题
+| 属性 | 值 |
+|------|------|
+| 标题字体 | `24px / 36px`，PingFang SC Semibold |
+| 标题颜色 | `--color-black-6` |
+| 标题位置 | 左侧偏移 64px，垂直居中 |
+
+> **更多按钮**：✅ 有（右侧）。点击 → [更多操作弹窗](more-actions.md)。
+
+#### 标签页-圆角
+| 属性 | 值 |
+|------|------|
+| 标签容器 | 按钮组合（两列），`--radius-12` |
+| 标签数量 | 2 个 |
+
+> **更多按钮**：✅ 有（右侧）。点击 → [更多操作弹窗](more-actions.md)。
+
+#### 标签页-下划线
+| 属性 | 值 |
+|------|------|
+| 标签容器 | 3 个 TAB 标签，间距 `24px`，居中 |
+
+> **更多按钮**：✅ 有（右侧）。点击 → [更多操作弹窗](more-actions.md)。
+
+#### 头部作业人
+| 属性 | 值 |
+|------|------|
+| 左侧 | 返回图标 + 标题（24/36/Semibold） |
+| 右侧 | 作业人胶囊 + 更多图标，间距 `--spacing-16` |
+
+> **更多按钮**：✅ 有（右侧，作业人胶囊后）。点击 → [更多操作弹窗](more-actions.md)。
+
+**作业人胶囊**（组件 Key: `015-作业人右侧置顶`）:
+
+| 属性 | 值 |
+|------|------|
+| 背景 | `--color-grey-1` |
+| 边框 | `1px --color-grey-3` |
+| 圆角 | `99px`（胶囊） |
+| 内边距 | t/b `2px`, l `2px`, r `16px` |
+| 头像尺寸 | `40×40`，圆形，带 2px 白边（描边） |
+| 头像堆叠 | `-16px` 正向堆叠（后一层覆盖前一层 16px），最多展示 10 个 |
+| 人数 | `24/36/Semibold`，`--color-black-6`，与头像间距 `--spacing-8` |
+
+#### 头部搜索
+| 属性 | 值 |
+|------|------|
+| 左侧 | 返回图标 |
+| 中间 | 搜索栏（flex-1） |
+| 右侧 | 文字按钮/主要 |
+| 元素间距 | `12px` |
+
+> **更多按钮**：❌ 无。此变体不含「更多」图标，不会触发更多操作弹窗。
+
+#### 右侧按钮+菜单
+| 属性 | 值 |
+|------|------|
+| 左侧 | 返回 + 标题（24/36/Semibold） |
+| 右侧 | 文字按钮 + 更多图标，间距 `--spacing-16`，右偏移 `16px` |
+
+> **更多按钮**：✅ 有（右侧，文字按钮后）。点击 → [更多操作弹窗](more-actions.md)。
+
+### CSS 示例
+
+```css
+/* 导航栏 默认标题 */
+.navbar {
+  width: 100%;
+  height: 56px;
+  display: flex;
+  align-items: center;
+  background: var(--color-grey-2);
+  position: relative;
+}
+.navbar-back {
+  width: 40px;
+  height: 40px;
+  flex-shrink: 0;
+}
+.navbar-title {
+  position: absolute;
+  left: 64px;
+  color: var(--color-black-6);
+  font-size: 24px;
+  line-height: 36px;
+  font-weight: 600;
+  font-family: PingFang SC;
+}
+.navbar-more {
+  width: 40px;
+  height: 40px;
+  flex-shrink: 0;
+  margin-left: auto;
+  cursor: pointer;
+}
+
+/* 导航栏 头部作业人 */
+.navbar-operator .operator-pill {
+  display: flex;
+  justify-content: flex-end;
+  align-items: center;
+  gap: var(--spacing-8);
+  padding: 2px 16px 2px 2px;
+  background: var(--color-grey-1);
+  border: 1px solid var(--color-grey-3);
+  border-radius: 99px;
+}
+.navbar-operator .avatar-stack {
+  position: relative;
+  /* 宽度 = 头像数 × 24px 露出 + 16px 余量 */
+  width: 136px;
+  height: 40px;
+}
+.navbar-operator .avatar {
+  width: 40px;
+  height: 40px;
+  border-radius: 50%;
+  border: 2px solid var(--color-grey-1);
+  flex-shrink: 0;
+}
+/* 头像堆叠：absolute 定位，每个错开 24px（40px - 16px 重叠） */
+.navbar-operator .avatar,
+.navbar-operator .avatar-more {
+  position: absolute;
+  top: 0;
+}
+.navbar-operator .avatar:nth-child(1) { left: 0px; }
+.navbar-operator .avatar:nth-child(2) { left: 24px; }
+.navbar-operator .avatar:nth-child(3) { left: 48px; }
+.navbar-operator .avatar:nth-child(4) { left: 72px; }
+.navbar-operator .avatar:nth-child(5) { left: 96px; }
+.navbar-operator .avatar-more {
+  /* 溢出头像显示 +N */
+  width: 40px;
+  height: 40px;
+  border-radius: 50%;
+  background: var(--color-grey-4);
+  border: 2px solid var(--color-grey-1);
+  color: var(--color-grey-1);
+  font-size: 12px;
+  line-height: 16px;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  left: 72px;
+}
+.navbar-operator .operator-count {
+  color: var(--color-black-6);
+  font-size: 24px;
+  line-height: 36px;
+  font-weight: 600;
+}
+
+/* 导航栏 头部搜索 */
+.navbar-search {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 8px 12px;
+  background: var(--color-grey-2);
+}
+.navbar-search .search-box {
+  flex: 1;
+}
+.navbar-search .btn-right {
+  flex-shrink: 0;
+}
+```
+
+---
+
+## 2. 导航栏/搜索
+
+**描述**: 搜索输入栏，顶部导航中嵌入使用。含默认/已输入两态。
+
+### Props
+
+| Prop | 类型 | 值 |
+|------|------|-----|
+| 搜索内容 | string | 任意（默认 `请输入`） |
+| 类型 | enum | `默认` / `已输入` |
+| 输入中 | boolean | — |
+
+### 规格
+
+| 属性 | 值 |
+|------|------|
+| 背景 | `--color-grey-1` |
+| 圆角 | `8px` |
+| 内边距 | t/b `6px`, l/r `8px` |
+| 默认文字色 | `--color-black-3` |
+| 已输入文字色 | `--color-black-6` |
+| 文字字体 | `20px / 28px`，PingFang SC Regular |
+| 清空图标 | `20×20` |
+
+### 颜色
+
+| state | text | icon |
+|-------|------|------|
+| default | `--color-black-3` | — |
+| typed | `--color-black-6` | 清空按钮（20×20） |
+
+### CSS 示例
+
+```css
+/* 搜索栏 默认 */
+.search-bar {
+  display: flex;
+  align-items: center;
+  padding: 6px 8px;
+  background: var(--color-grey-1);
+  border-radius: 8px;
+  overflow: hidden;
+}
+.search-placeholder {
+  color: var(--color-black-3);
+  font-size: 20px;
+  line-height: 28px;
+  font-family: PingFang SC;
+}
+.search-text {
+  color: var(--color-black-6);
+  font-size: 20px;
+  line-height: 28px;
+  font-family: PingFang SC;
+}
+
+/* 已输入态 */
+.search-bar-typed {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+.search-clear {
+  width: 20px;
+  height: 20px;
+  flex-shrink: 0;
+}
+```
+
+---
+
+## 3. 底部标签栏导航（TabBar）
+
+> 底部标签栏为独立业务组件，详见 [tab-bar.md](tab-bar.md)。本节仅保留与导航栏体系的关联说明。
+
+| 属性 | 值 |
+|------|------|
+| 栏目 | 首页 / 任务 / 营地 / 我的（4 项固定） |
+| 高度 | `71px` |
+| 背景 | `--color-grey-1` |
+| 图标 | `32×32`，`icons-标签栏/` |
+| 选中 | `--color-main-6` |
+| 未选 | `--color-black-5` |
+
+---
+
+## 4. 导航栏组合
+
+**描述**: StatusBar（系统状态栏） + 导航栏类型的纵向组合，整体高度 112px。
+
+| 属性 | 值 |
+|------|------|
+| 背景 | `--color-grey-2` |
+| StatusBar | `56px`，系统自带（时间/信号/WiFi/电量），非 PDAKit 组件 |
+| 导航栏 | 内嵌导航栏类型组件，`56px` |
+
+> StatusBar 是 OS 级元素，不属于 PDAKit 设计组件。此处仅标注其占位高度用于布局计算，不展开样式描述。
+
+---
+
+## 附录 A：颜色 Token
+
+| Token | 色值 | 使用场景 |
+|-------|------|---------|
+| `--color-grey-1` | `#ffffff` | 搜索栏背景；底部标签栏背景 |
+| `--color-grey-2` | `#f3f4f6` | 导航栏背景；导航栏组合背景 |
+| `--color-main-6` | `#6445d1` | 底部标签选中态文字/图标 |
+| `--color-black-3` | `#bbbbbb` | 搜索栏默认占位文字 |
+| `--color-black-5` | `#666666` | 底部标签未选中态文字 |
+| `--color-black-6` | `#333333` | 导航栏标题；搜索已输入文字 |
+
+> 详见 [tokens/colors.md](../tokens/colors.md)
+
+---
+
+## 附录 B：字体 Token
+
+| 字体规格 | 字号 | 行高 | 字重 | 适用组件 |
+|---------|------|------|------|---------|
+| 标题文本/【24】Title_Bold_L | 24px | 36px | Semibold | 导航栏标题 |
+| 20px/28px | 20px | 28px | Regular | 搜索栏文字 |
+| 辅助文本/【14】Auxiliary_Bold_S | 14px | 20px | Semibold | 底部标签文字 |
+
+> 字体统一 PingFang SC。详见 [tokens/typography.md](../tokens/typography.md)
+
+---
+
+## 使用规则（AI 必读）
+
+1. **颜色用 Token**：禁止裸 Hex，全部用 `--color-*` 引用
+2. **更多按钮强绑定**（⚠️ 最高优先级）：
+   - 导航栏「更多」图标（`common_ic_more_o.svg`）与 [更多操作弹窗](more-actions.md) 是**一对一强绑定**
+   - **只要导航栏渲染了「更多」图标，点击行为唯一且固定：唤起[更多操作弹窗](more-actions.md)**
+   - AI 生成代码时，**绝对禁止**将「更多」按钮绑定到其他页面、路由跳转、或其他非 more-actions 行为
+   - `显示菜单=false` 时隐藏「更多」图标，此时不触发弹窗；`显示菜单=true` 时渲染图标且行为固定
+   - 6 个变体中仅 `头部搜索` 不含「更多」图标，其余 5 个默认均含
+3. **导航栏选型**：
+   | 场景 | 变体 |
+   |------|------|
+   | 单页面标题 | 默认标题 |
+   | 分类内容切换 | 标签页-圆角 / 标签页-下划线 |
+   | 展示作业人信息 | 头部作业人 |
+   | 全局搜索 | 头部搜索 |
+   | 操作入口 | 右侧按钮+菜单 |
+4. **底部标签**：必须覆盖 `on`/`off` 两态，选中态用 `--color-main-6`，未选中用 `--color-black-5`
+5. **搜索栏**：默认态占位文字用 `--color-black-3`，已输入态用 `--color-black-6`
+6. **图标**：返回/更多图标 40×40；底部标签图标 32×32；清空图标 20×20，从 [icons/icons.md](../icons/icons.md) 清单选择
+7. **引用命名**：使用 `❖PDAKit™：导航栏类型` 格式
+8. **更多按钮默认必显**（⚠️ 高优先级）：
+   - **没有特殊要求时，导航栏右侧必须显示「更多」图标按钮**
+   - 仅当用户明确说「不需要更多按钮」「隐藏更多」等特殊指令时，才设置 `显示菜单=false` 隐藏
+   - AI 生成页面时，若未收到特殊要求，`显示菜单` 默认值必须为 `true`，即右侧必须渲染更多图标
+9. **导航图标颜色**：导航栏内所有图标（返回/更多）颜色统一为 `--color-black-6`（`#333333`），不要使用其他颜色