# 移动端组件 · 子任务共享约定（S7-P23 批次 A 起）

> **给子 agent 的硬约束。开工前逐条读完，任何一条不满足即视为未完成。**
> 本文件与 `.design_library/kole-ui-mobile/spec/移动端规格.md`（冻结规格）、
> `.design_library/kole-ui-mobile/components/<slug>.json`（既有 18 份契约）一起构成工作依据。
> 权威文档：仓库根 `PLATFORMS.md`（平台 × 端两轴 + 隔离规则）。

---

## 一 · 你要产出什么（6 个文件 + 1 段规格 + 1 份契约）

工作目录：`C:\Users\12914\Desktop\组件规范第一套`

| # | 路径 | 说明 |
|---|---|---|
| 1 | `frameworks-mobile/<Prefix>.css` | 样式。**只引用 `--kole-*` 或 `--kole-m-*` 令牌，不得出现硬编码 hex**；类名只能是 `kole-m-<name>` 或状态类 `is-<state>` |
| 2 | `frameworks-mobile/<Prefix>.html` | 演示页。必须含 `.demo` 容器；每个演示块包成 `<section class="demo-block" data-demo="<id>">`；文件末尾必须带 `?demo=<id>` 单块过滤脚本（照抄既有演示页的写法） |
| 3 | `frameworks-mobile/<Prefix>.jsx` | React 端。`export default function X({...})`，形参即 props |
| 4 | `frameworks-mobile/<Prefix>.vue3.vue` | Vue 3 端，`<script setup>` + `defineProps({...})` + `defineEmits([...])`，样式 `<style src="./<Prefix>.css"></style>` |
| 5 | `frameworks-mobile/<Prefix>.vue2.vue` | Vue 2 端，`props: {...}` + `$emit`，`name: 'KoleM<Prefix>'` |
| 6 | `frameworks-mobile/<Prefix>.uniapp.vue` | uni-app 端。**只能用 uni 基础组件**（`view`/`text`/`input`/`scroll-view`/`image`…）+ `@tap` / `@touch*`；**禁止** `document` / `window` / `PointerEvent` / `addEventListener('pointer…')`；尺寸用 **rpx**（750rpx = 视口宽度，88rpx = 44px @375pt）；样式里必须出现 `--kole-m-` 令牌覆盖 |
| 7 | `.design_library/kole-ui-mobile/spec/parts/<slug>.md` | 规格片段（见第二节格式）。**只写你这几个组件的节**，不要动 `移动端规格.md` |
| 8 | `.design_library/kole-ui-mobile/components/<slug>.json` | 契约（见第三节字段表）。文件名用 **你被分配的 slug**，一字不改 |

**不要**改 `index.json`（索引由主 agent 统一合并）、不要改 `site/m/**`、`tests/mobile/**`（生成物，由 `node tools/build-mobile.mjs` 产出）、不要改其它组件的任何文件。

---

## 二 · 规格片段格式（逐字照此结构，一节一个组件）

```markdown
## <编号> · <中文名> <English>

### <编号>.1 用途
<一句话：这个组件解决什么问题；移动端场景下与桌面端的差别>

### <编号>.2 结构（anatomy）
- `字段名`：说明
（4~6 条，字段名用反引号，是后面契约 anatomy 的来源）

### <编号>.3 变体维度
- `维度名`：`取值1` / `取值2` / `取值3`
（2~3 个维度，取值必须与实现里的类名一一对应）

### <编号>.4 状态
- default：常态
- <其它状态>：说明

### <编号>.5 交互与触控
- <点击/滑动手势、热区尺寸、动效时值等，逐条可验证>

### <编号>.6 无障碍
- <语义角色、aria-*、键盘/读屏行为>

### <编号>.7 doNotInvent
- <明确不许发明的部分，2~4 条>

### <编号>.8 unknowns
- <规格未定项，2~3 条>
```

编号从 **19** 开始连续（现有规格到 §18），主 agent 会把你的片段按编号拼进 `移动端规格.md`。

---

## 三 · 契约字段（缺一个字段，门禁就红）

```json
{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "specSection": "<编号> · <中文名> <English>",
  "confidence": "high",
  "slug": "<分配的 slug>",
  "name": "<中文名> <English>",
  "semanticTypeCandidates": ["…", "…"],
  "variantDimensions": [{ "name": "…", "values": ["…"] }],
  "representativeVariants": [{ "<维度名>": "<取值>", "label": "<中文标签>" }],
  "anatomy": { "字段名": "说明" },
  "structurePatterns": { "维度名": "取值说明" },
  "usageHints": ["…（逐字取自规格 §x.1~§x.5，5 条左右）"],
  "doNotInvent": ["…"],
  "unknowns": ["…"],
  "interaction": ["…（逐字取自规格 §x.5）"],
  "accessibility": ["…（逐字取自规格 §x.6）"],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [{ "name": "…", "type": "…", "default": "…", "desc": "…（规格 §x.y）", "required": false }],
    "events": [{ "name": "…", "params": "…", "desc": "…" }],
    "slots": [{ "name": "default", "desc": "…" }]
  },
  "variantClasses": { "<维度名>": { "<取值>": [".kole-m-xxx--yyy"] } },
  "demos": [{ "id": "…", "group": "01 组件类型", "title": "…", "desc": "…", "variant": "…" }],
  "related": [{ "slug": "<真实存在的 slug>", "why": "<何时用它而不是本组件>" }]
}
```

**会被门禁逐条核对的四件事（写错必红）**：

1. `variantClasses` 里数组中的每个 `.kole-m-xxx` 类名、每个 `--kole-m-xxx` 变量，**必须在你写的 `<Prefix>.css` 里真实出现**（类名按 `.name` 精确匹配；变量要写成 `--name:` 定义）。
2. `api.props` 的每个 `name` 必须在你写的 **jsx / vue3 / vue2 / uniapp** 四端源码里都能提取到；反过来，源码里多出来的形参也必须在契约里登记。
   - React 端：`events` 按 `onXxx` 形式出现在形参里（如事件 `click` → 形参 `onClick`）；`slots.default` → `children`；具名插槽 → 同名形参（如 `actions`）。
   - `required: true` 的 prop **必须**在四端实现里都没有默认值；`required: false` 的**必须**都有默认值。拿不准就一律 `required: false` 并给默认值。
3. `demos[].id` 必须与演示页里的 `data-demo="<id>"` **双向一致**（契约有的演示页要有，演示页有的契约要登记），且每个演示的代码块非空。
4. `related[].slug` 必须是**真实存在的组件**：现有 18 个 slug 是
   `navbar` `tabbar` `actionsheet` `pullrefresh` `swipecell` `mobile-button` `cell` `mobile-divider` `mobile-badge` `mobile-tag` `mobile-popup` `mobile-toast` `mobile-dialog` `mobile-grid` `mobile-steps` `mobile-noticebar` `mobile-numberkeyboard` `mobile-datepicker`；
   你可以引用**同批次**其它组件的 slug（见你的派单）。

**演示页可分块预览**：每个 `data-demo` 块在文档站会被单独渲染成 375 宽的预览帧，所以每块要能**独立成立**（不要依赖前一块的 DOM 或上一个演示留下的状态）。

---

## 四 · 提交前必须自己跑（把输出原样贴进报告）

```bash
cd "C:/Users/12914/Desktop/组件规范第一套"
# 1) 语法：脚本与三端 SFC
node --check tools/build-mobile.mjs
node -e "for (const f of ['<Prefix>.jsx','<Prefix>.vue2.vue','<Prefix>.vue3.vue','<Prefix>.uniapp.vue']) { const s=require('fs').readFileSync('frameworks-mobile/'+f,'utf8'); const m=s.match(/<script[^>]*>([\s\S]*?)<\/script>/); if(!m) { console.log(f+': 无 script 段'); continue; } require('fs').writeFileSync('/tmp/_x.mjs', m[1]); require('child_process').execFileSync(process.execPath,['--check','/tmp/_x.mjs']); console.log(f+': script OK'); }"

# 2) uni-app 静态门禁（会检查你那一端：SFC 三段 / 禁 DOM / 手势必须 touch / rpx / 前缀）
node tools/verify-uniapp.mjs

# 3) 演示页结构自检（section 配平 + data-demo 与契约一致 + 过滤脚本在）
node -e "
const fs=require('fs');
const ct=JSON.parse(fs.readFileSync('.design_library/kole-ui-mobile/components/<slug>.json','utf8'));
const h=fs.readFileSync('frameworks-mobile/<Prefix>.html','utf8');
const ids=[...h.matchAll(/data-demo=\"([a-z0-9-]+)\"/g)].map(m=>m[1]);
console.log('演示页 data-demo:', ids.join(','));
console.log('契约 demos:', ct.demos.map(d=>d.id).join(','));
console.log('过滤脚本:', h.includes('demo-single') ? 'OK' : '缺');
"
```

**注意**：`verify-mobile-docs.mjs`（契约 API ↔ 源码逐名一致）与 `build-mobile.mjs` 由**主 agent**在合并索引后统一跑；你只要保证上面三步通过，并把 `api.props` 与四端源码逐名对齐。

---

## 五 · 报告格式（三分型，不要模糊表述）

```
DONE | PARTIAL | BLOCKED
- 产出文件（逐条列绝对路径 + 行数）
- 上表 4 条硬约束的**自检输出原样粘贴**
- 未做 / 未验证的部分（写明原因）
- 发现的仓库问题（不要在任务里顺手修，报给我）
```

**禁止**：写 `已完成` 而不给自检输出；把「没跑」说成「应该没问题」；改本约定文件或 `index.json`。