pda-kit-mcp-server 2.0.1

package/spec-data/picker.md

@@ -0,0 +1,586 @@
+---
+id: picker
+name: 选择器
+category: "表单/Form"
+version: "1.0.0"
+source: PDAKit-业务组件
+source_url: https://mastergo.ky-tech.com.cn/goto/TZAlKGkG
+source_doc_id: 103417331857122
+---
+
+# 选择器 Picker
+
+双层选择器组件，**左侧类型切换 + 右侧单选选项**，底部操作确认。用于点部选择、分类筛选等场景。
+
+> **核心规则**：左列控制右列内容（类型联动），右侧为单选操作，底部取消/确定确认选择结果。
+> **颜色规则**：全部使用 Token（`--color-{色系}-{色阶}`），禁止 Hex。
+> **字体**：PingFang SC。
+
+---
+
+## Props
+
+### 父组件 Props（选择器面板）
+
+| Prop | 类型 | 值 | 默认 |
+|------|------|-----|------|
+| 标题 | string | 头部标题文字 | `测试组件` |
+| 显示关闭 | boolean | 是否显示右上角关闭按钮 | `true` |
+| 显示描述 | boolean | 标题下方是否显示描述文字 | `false` |
+| 描述文字 | string | 描述内容（`显示描述=true` 时生效） | — |
+| 1级选项列表 | array | 左侧分类选项数据 | `[]` |
+| 2级选项列表 | array | 右侧选项数据 | `[]` |
+| 已选项 ID | string | 当前已选中的选项 ID | `null` |
+
+### 底部按钮 Props
+
+| Prop | 类型 | 值 | 默认 |
+|------|------|-----|------|
+| 按钮类型 | enum | `两列按钮` | `两列按钮` |
+| 显示分割线 | boolean | 底部上方是否显示分割线 | `true` |
+| 左按钮文字 | string | 左侧（取消）按钮文字 | `取消` |
+| 右按钮文字 | string | 右侧（确定）按钮文字 | `确定` |
+
+### 1级选项行 Props（左列）
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| 选中状态 | enum | `选中` / `默认` |
+| 文本 | string | 分类名称 |
+
+### 2级选项行 Props（右列）
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| 选中状态 | enum | `已选` / `未选` |
+| 文本 | string | 选项名称 |
+| 二级分类 | enum | `单选`（选项互斥） |
+| 语音备注 | boolean | 是否显示语音备注功能 | `false` |
+
+---
+
+## 整体容器规格
+
+| 属性 | 值 |
+|------|------|
+| 宽度 | `480px` |
+| 高度 | `477px`（min `320px` / max `740px`） |
+| 布局 | `flex-column` |
+| 圆角（顶部） | `16px` |
+| 弹窗类型 | Bottom Sheet，由底部向上滑入，`300ms ease-in` |
+| 遮罩 | `rgba(0,0,0,0.4)`，z-index: 900 |
+| 面板 | z-index: 901 |
+
+---
+
+## 1. 头部
+
+### 规格
+
+| 属性 | 值 |
+|------|------|
+| 背景 | `--color-grey-1`（`#FFFFFF`） |
+| 上内边距 | `24px` |
+| 下内边距 | `8px` |
+| 左右内边距 | `16px` |
+| 子元素间距 | `4px`（gap） |
+| 圆角（顶部） | `16px` |
+| 宽度 | `480px` |
+
+### 内部布局
+
+```
+┌─ 480px ─────────────────────────────────┐
+│                        [×] 关闭图标        │ ← 绝对定位, right: 16px, top: 24px
+│          测试组件 (24px/600)              │ ← 标题居中
+│          描述文字 (16px #666) ← 按需      │ ← 描述居中（可选）
+└──────────────────────────────────────────┘
+```
+
+| 元素 | 样式 |
+|------|------|
+| 标题 | `24px / 36px line-height`, font-weight: `600`, color: `--color-black-6` (`#333333`), text-align: `center` |
+| 描述文字 | `16px / 22px line-height`, color: `--color-grey-6` (`#52567B`), text-align: `center` |
+| 关闭图标 | `common_ic_close_o.svg`, `24×24`, absolute, `right: 16px, top: 24px` |
+
+### CSS 示例
+
+```css
+.picker-header {
+  width: 480px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+  padding: 24px 16px 8px;
+  background: var(--color-grey-1);
+  border-top-left-radius: 16px;
+  border-top-right-radius: 16px;
+  position: relative;
+  flex-shrink: 0;
+}
+.picker-header-title {
+  color: var(--color-black-6);
+  font-size: 24px;
+  line-height: 36px;
+  font-weight: 600;
+  font-family: PingFang SC;
+  text-align: center;
+}
+.picker-header-desc {
+  color: var(--color-grey-6);
+  font-size: 16px;
+  line-height: 22px;
+  font-family: PingFang SC;
+  text-align: center;
+}
+.picker-header-close {
+  position: absolute;
+  right: 16px;
+  top: 24px;
+  width: 24px;
+  height: 24px;
+  cursor: pointer;
+}
+```
+
+---
+
+## 2. 内容区（左列 + 右列）
+
+### 容器
+
+| 属性 | 值 |
+|------|------|
+| 布局 | `flex-row` |
+| 背景 | `--color-grey-1`（`#FFFFFF`） |
+| 伸缩 | `flex: 1` |
+| 溢出 | `overflow: hidden` |
+
+### 2.1 一级选项组（左列）
+
+| 属性 | 值 |
+|------|------|
+| 布局 | `flex-column`, `flex-shrink: 0`, `align-self: stretch` |
+| 背景 | `--color-grey-2`（`#F3F4F6`） |
+| 宽度 | `120px` |
+
+#### 选项行
+
+| 属性 | 值 |
+|------|------|
+| 高度 | `70px` |
+| 内边距 | `0 16px` |
+| 布局 | `flex-column`, `justify-content: center`, `align-items: flex-start` |
+| 字体 | `18px / 25px`, `--color-black-6`（`#333333`） |
+
+#### 状态
+
+| 状态 | 背景 | 文字颜色 | 左侧指示线 |
+|------|------|---------|-----------|
+| 默认 | `--color-grey-2`（`#F3F4F6`） | `--color-black-6`（`#333333`） | 无 |
+| 选中 | `--color-grey-1`（`#FFFFFF`） | `--color-main-6`（`#6445D1`），font-weight: `600` | `4px × 28px`, `--color-main-6`, 左侧 |
+
+### CSS 示例（左列）
+
+```css
+.picker-left-panel {
+  width: 120px;
+  display: flex;
+  flex-direction: column;
+  align-self: stretch;
+  flex-shrink: 0;
+  background: var(--color-grey-2);
+  overflow-y: auto;
+}
+.picker-left-item {
+  width: 120px;
+  height: 70px;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: flex-start;
+  padding: 0 16px;
+  font-size: 18px;
+  line-height: 25px;
+  font-family: PingFang SC;
+  color: var(--color-black-6);
+  cursor: pointer;
+  position: relative;
+  flex-shrink: 0;
+}
+.picker-left-item.selected {
+  background: var(--color-grey-1);
+  color: var(--color-main-6);
+  font-weight: 600;
+}
+.picker-left-item.selected::before {
+  content: '';
+  position: absolute;
+  left: 0;
+  top: 50%;
+  transform: translateY(-50%);
+  width: 4px;
+  height: 28px;
+  background: var(--color-main-6);
+  border-radius: 2px;
+}
+```
+
+### 2.2 二级选项组（右列）
+
+| 属性 | 值 |
+|------|------|
+| 布局 | `flex-column`, `flex-shrink: 0`, `align-self: stretch`, `justify-content: center`, `align-items: center` |
+| 背景 | `--color-grey-1`（`#FFFFFF`） |
+| 宽度 | `360px`（480 - 120） |
+
+#### 选项行（单选）
+
+| 属性 | 值 |
+|------|------|
+| 高度 | `70px` |
+| 内边距 | `0 16px` |
+| 布局 | `flex-row`, `align-items: center`, `justify-content: space-between` |
+| 字体 | `18px / 25px`, `--color-black-6`（`#333333`） |
+| 行分割线 | `border-bottom: 1px solid var(--color-black-2)`，最后一行无 |
+
+#### 单选指示器
+
+| 属性 | 值 |
+|------|------|
+| 尺寸 | `24×24px` |
+| 间距（与文字） | 位于文字右侧 |
+| 未选态 | 圆形描边 `1.5px --color-black-2`（`#DDDDDD`），透明背景 |
+| 已选态 | 圆形填充 `--color-green-6`（`#03c15f`），白色 `common_ic_check_two.svg` 图标 `16×16px` |
+| 交互 | 单选互斥：同一分类下仅一项可选中 |
+
+### CSS 示例（右列）
+
+```css
+.picker-right-panel {
+  width: 360px;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  align-self: stretch;
+  flex-shrink: 0;
+  background: var(--color-grey-1);
+  overflow-y: auto;
+}
+.picker-right-item {
+  width: 100%;
+  height: 70px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0 16px;
+  font-size: 18px;
+  line-height: 25px;
+  font-family: PingFang SC;
+  color: var(--color-black-6);
+  cursor: pointer;
+  flex-shrink: 0;
+  border-bottom: 1px solid var(--color-black-2);
+}
+.picker-right-item:last-child { border-bottom: none; }
+.picker-right-item:active {
+  background: var(--color-grey-2);
+}
+.picker-radio {
+  width: 24px;
+  height: 24px;
+  flex-shrink: 0;
+  border: 1.5px solid var(--color-black-2);
+  border-radius: 50%;
+  background: transparent;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  position: relative;
+}
+.picker-radio.checked {
+  background: var(--color-green-6);
+  border-color: var(--color-green-6);
+}
+.picker-radio svg { display: none; }
+.picker-radio.checked svg {
+  display: block;
+  width: 16px;
+  height: 16px;
+}
+```
+
+---
+
+## 3. 底部操作按钮
+
+**描述**：固定底部，取消/确定双按钮确认选择结果。
+
+### 规格
+
+| 属性 | 值 |
+|------|------|
+| 分割线 | `1px`, `--color-black-2`（`#DDDDDD`）, 宽 `480px` |
+| 容器背景 | `--color-grey-1`（`#FFFFFF`） |
+| 垂直内边距 | `8px` |
+| 水平内边距 | `16px` |
+| 按钮间距 | `16px`（gap） |
+| 布局 | `flex-row`, `justify-content: center`, `align-items: center` |
+
+### 按钮规格
+
+| 属性 | 取消按钮 | 确定按钮 |
+|------|---------|---------|
+| 背景 | `--color-grey-2`（`#F3F4F6`） | `--color-main-6`（`#6445D1`） |
+| 文字颜色 | `--color-grey-6`（`#52567B`） | `--color-grey-1`（`#FFFFFF`） |
+| 文字 | `取消` | `确定` |
+| 字体 | `22px / 30px`, PingFang SC | `22px / 30px`, PingFang SC |
+| 最小宽度 | `100px` | `100px` |
+| 最大宽度 | `448px` | `448px` |
+| 高度 | `64px` | `64px` |
+| 圆角 | `8px` | `8px` |
+| 伸缩 | `flex: 1` | `flex: 1` |
+| 交互态 | `:active` → `--color-grey-3` | `:active` → `--color-main-7` |
+
+### CSS 示例
+
+```css
+.picker-bottom {
+  display: flex;
+  flex-direction: column;
+  align-self: stretch;
+  background: var(--color-grey-1);
+  flex-shrink: 0;
+}
+.picker-divider {
+  width: 480px;
+  height: 1px;
+  background: var(--color-black-2);
+}
+.picker-bottom-row {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 16px;
+  padding: 8px 16px;
+}
+.picker-btn-cancel {
+  flex: 1;
+  min-width: 100px;
+  max-width: 448px;
+  height: 64px;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  background: var(--color-grey-2);
+  border: none;
+  border-radius: 8px;
+  color: var(--color-grey-6);
+  font-size: 22px;
+  line-height: 30px;
+  font-family: PingFang SC;
+  cursor: pointer;
+}
+.picker-btn-cancel:active { background: var(--color-grey-3); }
+.picker-btn-confirm {
+  flex: 1;
+  min-width: 100px;
+  max-width: 448px;
+  height: 64px;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  background: var(--color-main-6);
+  border: none;
+  border-radius: 8px;
+  color: var(--color-grey-1);
+  font-size: 22px;
+  line-height: 30px;
+  font-family: PingFang SC;
+  cursor: pointer;
+}
+.picker-btn-confirm:active { background: var(--color-main-7); }
+```
+
+---
+
+## HTML 完整骨架
+
+```html
+<!-- 遮罩 -->
+<div class="overlay show" id="pickerOverlay" onclick="closePicker()"></div>
+
+<!-- 选择器面板 -->
+<div class="picker-panel" id="pickerPanel">
+  <!-- 头部 -->
+  <div class="picker-header">
+    <p class="picker-header-title">测试组件</p>
+    <div class="picker-header-close" onclick="closePicker()">×</div>
+  </div>
+
+  <!-- 内容区 -->
+  <div class="picker-content">
+    <div class="picker-left-panel" id="pickerLeftPanel">
+      <!-- JS 动态渲染 -->
+    </div>
+    <div class="picker-right-panel" id="pickerRightPanel">
+      <!-- JS 动态渲染 -->
+    </div>
+  </div>
+
+  <!-- 底部操作 -->
+  <div class="picker-bottom">
+    <div class="picker-divider"></div>
+    <div class="picker-bottom-row">
+      <button class="picker-btn-cancel" onclick="closePicker()">取消</button>
+      <button class="picker-btn-confirm" onclick="confirmPicker()">确定</button>
+    </div>
+  </div>
+</div>
+```
+
+---
+
+## JS 交互逻辑
+
+```javascript
+// 选择器数据
+let pickerData = {
+  leftOptions: [
+    { id: 'dest', name: '目的', selected: true },
+    { id: 'transit', name: '经停', selected: false }
+  ],
+  rightOptions: {
+    dest: [
+      { id: 'p1', name: '深圳坂田营业部' },
+      { id: 'p2', name: '广州天河营业部' },
+      { id: 'p3', name: '东莞南城营业部' },
+      { id: 'p4', name: '佛山禅城营业部' },
+      { id: 'p5', name: '珠海香洲营业部' }
+    ],
+    transit: [
+      { id: 't1', name: '北京朝阳中转场' },
+      { id: 't2', name: '上海虹桥中转场' },
+      { id: 't3', name: '成都双流中转场' }
+    ]
+  },
+  currentCategory: 'dest',
+  selectedId: null  // 单选：只存一个 ID
+};
+
+// 切换左列分类
+function switchLeftCategory(categoryId) {
+  pickerData.leftOptions.forEach(item => {
+    item.selected = (item.id === categoryId);
+  });
+  pickerData.currentCategory = categoryId;
+  pickerData.selectedId = null;  // 切换左列时清空右列选中
+  renderLeftPanel();
+  renderRightPanel();
+}
+
+// 切换右列单选
+function selectRightOption(optionId) {
+  // 单选互斥：点击同一项则取消，否则切换
+  pickerData.selectedId = (pickerData.selectedId === optionId) ? null : optionId;
+  renderRightPanel();
+}
+
+// 确定
+function confirmPicker() {
+  if (!pickerData.selectedId) {
+    showToast('请先选择一个选项');
+    return;
+  }
+  const options = pickerData.rightOptions[pickerData.currentCategory];
+  const selected = options.find(o => o.id === pickerData.selectedId);
+  if (selected) {
+    onPickerConfirm(selected);
+  }
+  closePicker();
+}
+
+// 关闭
+function closePicker() {
+  document.getElementById('pickerOverlay').classList.remove('show');
+}
+```
+
+---
+
+## ⚙️ PDA 工业场景硬性约束
+
+| # | 约束 | 值 | 原因 |
+|---|------|-----|------|
+| 1 | 最小触控热区 | 左列行高 **70px** / 右列行高 **70px** / 底部按钮 **64px** | 仓储手套操作 / 手指粗 |
+| 2 | 操作元素间距 | 按钮间距 **16px**，右列行间用 **分割线** 分隔 | 防止误触 |
+| 3 | 背景-文字对比度 | **≥ 4.5:1**（WCAG AA） | 室外强光可读 |
+| 4 | 面板最大高度 | **max-height: 740px**（默认 477px，可滚动至 740px） | 不超过屏幕 70% |
+| 5 | 禁用装饰 | ❌ 渐变 / ❌ 阴影 / ❌ 半透明叠加 | PDA 极简原则 |
+| 6 | 字体下界 | 标题 ≥ 24px，行文字 ≥ 18px | 小屏可读性底线 |
+| 7 | 左列联动 | 左列选中 → 右列内容替换 + 清空选中，不可解绑 | 选择器核心交互 |
+| 8 | 单选互斥 | 右侧同一分类下仅一项可选 | 单选行为定义 |
+| 9 | 确认提交 | 未选时点击确定 → 提示"请先选择一个选项" | 防止误操作 |
+
+---
+
+## 使用规则（AI 必读）
+
+### 第 1 层：绝对禁止（违反即错误）
+
+- ❌ 左列和右列独立渲染、不联动 → ✅ 左列切换时右列必须重新加载数据并清空选中
+- ❌ 底部按钮文本用 Hex 颜色 → ✅ `--color-grey-6` / `--color-grey-1`
+- ❌ 面板高度超过 `740px` → ✅ `max-height: 740px`
+- ❌ 右列选项行高小于 48px → ✅ `70px`
+
+### 第 2 层：状态规则
+
+- ✅ 左列必须有选中/默认两态（背景颜色 + 左侧紫色指示线 + 文字颜色）
+- ✅ 右列单选指示器必须有未选/已选两态（空心圆 / 实心圆 + 内白点）
+- ✅ 切换左列分类时右列选中自动清空
+- ✅ 取消/关闭均不保存已选结果
+
+### 第 3 层：组合规则
+
+- ✅ 默认打开时，左列第一项自动选中，右列加载对应数据
+- ✅ 单选互斥：点击已选中的项取消选中，点击未选中的项切换选中
+
+---
+
+## 🔴 常见 AI 错误 & 自检清单
+
+| # | ❌ 错误写法 | ✅ 正确写法 | 为什么 |
+|---|-----------|-----------|--------|
+| 1 | 左列和右列各自独立渲染，无联动 | 左列 `onClick` → `switchLeftCategory(id)` → 重新 `renderRightPanel()` | 选择器核心逻辑 |
+| 2 | 取消按钮未绑定 `closePicker()` | `onclick="closePicker()"` | 取消必须关闭且不保存 |
+| 3 | 单选指示器用方形复选框 | 圆形 `border-radius: 50%`，选中态绿色 `--color-green-6` + `common_ic_check_two` 图标 | 右列为单选 Radio |
+| 4 | 切换左列未清空右列选中 | `pickerData.selectedId = null` 在 `switchLeftCategory` 中 | 避免脏数据 |
+| 5 | 面板高度写死 740px | `height: 477px; max-height: 740px` | 默认 477px |
+| 6 | 多选模式（`selectedIds: []`） | 单选模式（`selectedId: null`），互斥切换 | 设计稿规定右侧为单选 |
+
+### 自检
+
+```bash
+# 1. 检查左列联动函数
+grep -n 'switchLeftCategory\|renderRightPanel' demo.html
+# ↑ 必须有这两个函数的定义
+
+# 2. 检查单选指示器（圆形，非方形）
+grep -n 'picker-radio\|border-radius.*50%' demo.html
+# ↑ 必须是 radio（圆形）
+
+# 3. 检查面板高度限制
+grep -n 'max-height.*740' demo.html
+# ↑ 必须有 max-height: 740px
+
+# 4. 检查取消按钮
+grep -n 'picker-btn-cancel' demo.html -A2 | grep 'onclick'
+# ↑ 必须绑定 closePicker()
+
+# 5. 检查切换左列时清空选中
+grep -n 'selectedId = null' demo.html
+# ↑ switchLeftCategory 中必须有此行
+```