aurora-admin/.design_library/kole-ui-mobile/components/mobile-sticky.json

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "specSection": "39 · 吸顶容器 Sticky",
  "confidence": "high",
  "slug": "mobile-sticky",
  "name": "吸顶容器 Sticky",
  "semanticTypeCandidates": [
    "sticky",
    "affix",
    "section-header"
  ],
  "variantDimensions": [
    {
      "name": "position",
      "values": [
        "top",
        "bottom"
      ]
    },
    {
      "name": "safeArea",
      "values": [
        "false",
        "true"
      ]
    },
    {
      "name": "shadow",
      "values": [
        "false",
        "true"
      ]
    }
  ],
  "representativeVariants": [
    {
      "position": "top",
      "safeArea": "false",
      "shadow": "false",
      "label": "基础吸顶（列表标题条）"
    },
    {
      "position": "top",
      "safeArea": "false",
      "shadow": "true",
      "label": "吸顶后出阴影（与内容分层）"
    },
    {
      "position": "top",
      "safeArea": "true",
      "shadow": "false",
      "label": "安全区叠加（刘海屏）"
    },
    {
      "position": "bottom",
      "safeArea": "false",
      "shadow": "true",
      "label": "贴底吸顶（合计条）"
    }
  ],
  "anatomy": {
    "sticky": "根元素，就是滚动内容流里的那一行（sticky 不脱离文档流，因此不需要占位元素）",
    "title": "标题文字，单行省略，占满剩余宽度",
    "extra": "右侧附加说明（数量、合计等），可选",
    "action": "右侧动作按钮（原生 button，热区 44px），可选"
  },
  "structurePatterns": {
    "position": "top 贴顶（最常用）/ bottom 贴底（合计条一类）",
    "safeArea": "false 只用偏移量 / true 再叠加刘海或底部横条安全区",
    "shadow": "false 恒定无投影 / true 仅吸顶后才有投影",
    "状态类": "is-stuck 已贴合边缘（由宿主按滚动位置切换）"
  },
  "usageHints": [
    "让一段内容在滚动时贴住滚动容器的边缘保持可见（列表标题、分组、购物车合计条）",
    "用 CSS 原生 position: sticky —— 触屏惯性滚动下 JS 的 fixed 方案会抖动，且脱离文档流后要补占位元素",
    "贴合位置由组件级变量 --kole-m-sticky-offset 决定，默认等于导航栏高度",
    "组件本身不监听滚动：is-stuck 由宿主按滚动位置切换",
    "吸顶不改变文档顺序：读屏与键盘的遍历顺序与未吸顶时完全一致"
  ],
  "doNotInvent": [
    "吸顶触发的位移/缩放动画（规格只定义了贴合，没有定义形态演变）",
    "多个吸顶条的层叠顺序与相互推挤（层叠上下文规则由宿主决定）",
    "进入/离开视口时的埋点事件与曝光统计",
    "拖拽排序与吸附"
  ],
  "unknowns": [
    "吸顶判定是否应由组件内部提供一个可选的滚动监听辅助（当前完全交给宿主）",
    "是否需要在吸顶时自动隐藏相邻内容（当前不做，靠宿主布局）",
    "贴底形态在内容不足一屏时是否应始终贴底"
  ],
  "interaction": [
    "贴合位置由组件级变量 --kole-m-sticky-offset 决定，业务侧覆盖它即可适配自有导航",
    "safeArea=true 时偏移叠加 --kole-m-safe-top / --kole-m-safe-bottom；env() 不可用时为 0px",
    "组件本身不监听滚动：is-stuck 由宿主按滚动位置切换",
    "触屏热区：整条高度 ≥ 44px；右侧动作按钮自身撑满 44px",
    "position=bottom 时吸顶后的描边换到上边"
  ],
  "accessibility": [
    "根是普通容器，标题文字正常参与读屏朗读；is-stuck 是纯视觉增强，不添加任何 aria-*",
    "右侧动作是原生 button，名称由可见文字承担；装饰性图形必须 aria-hidden=\"true\"",
    "吸顶不改变文档顺序：读屏与键盘的遍历顺序与未吸顶时完全一致",
    "prefers-reduced-motion 下不引入任何过渡"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "position",
        "type": "'top' | 'bottom'",
        "default": "'top'",
        "desc": "变体 position：贴顶还是贴底（规格 §39.3）",
        "required": false
      },
      {
        "name": "safeArea",
        "type": "boolean",
        "default": "false",
        "desc": "变体 safeArea：偏移叠加刘海 / 底部横条安全区（规格 §39.3）",
        "required": false
      },
      {
        "name": "shadow",
        "type": "boolean",
        "default": "false",
        "desc": "变体 shadow：仅吸顶后才有投影（规格 §39.3）",
        "required": false
      },
      {
        "name": "stuck",
        "type": "boolean",
        "default": "false",
        "desc": "状态 stuck：是否已贴合边缘，由宿主按滚动位置传入（规格 §39.4）",
        "required": false
      },
      {
        "name": "title",
        "type": "string",
        "default": "''",
        "desc": "标题文字，单行省略（规格 §39.2 title）",
        "required": false
      },
      {
        "name": "actionText",
        "type": "string",
        "default": "''",
        "desc": "右侧动作按钮文字；为空时不渲染按钮（规格 §39.2 action）",
        "required": false
      }
    ],
    "events": [
      {
        "name": "action",
        "params": "—",
        "desc": "点击右侧动作按钮时触发（规格 §39.5）"
      }
    ],
    "slots": [
      {
        "name": "default",
        "desc": "额外的栏内内容（放在标题与动作之间）"
      }
    ]
  },
  "variantClasses": {
    "position": {
      "top": [
        ".kole-m-sticky--top"
      ],
      "bottom": [
        ".kole-m-sticky--bottom"
      ]
    },
    "safeArea": {
      "false": [],
      "true": [
        ".kole-m-sticky--safe"
      ]
    },
    "shadow": {
      "false": [],
      "true": [
        ".kole-m-sticky--shadow"
      ]
    }
  },
  "demos": [
    {
      "id": "basic",
      "group": "01 组件类型",
      "title": "基础吸顶",
      "desc": "position: sticky 的默认形态：在框内向下滚动时标题条贴住框顶，不脱离文档流因此无需补占位元素。",
      "variant": "position=top"
    },
    {
      "id": "shadow",
      "group": "01 组件类型",
      "title": "吸顶后出阴影",
      "desc": "shadow=true：未吸顶时与内容齐平，贴合后才出现投影，用形态而不是颜色表达「已经贴住了」。",
      "variant": "shadow=true"
    },
    {
      "id": "safe-area",
      "group": "01 组件类型",
      "title": "安全区叠加",
      "desc": "safeArea=true：偏移量再叠加刘海高度；无刘海设备上安全区为 0px，表现与不带 safe 一致。",
      "variant": "safeArea=true"
    },
    {
      "id": "bottom",
      "group": "02 组件状态",
      "title": "贴底吸顶",
      "desc": "position=bottom：内容不足一屏时贴住容器底，常用于订单合计条；吸顶后描边换到上边。",
      "variant": "position=bottom"
    },
    {
      "id": "action",
      "group": "02 组件状态",
      "title": "带动作",
      "desc": "右侧动作是原生 button、热区 44px；点击回传 action，具体做什么由宿主决定。",
      "variant": "actionText 非空"
    }
  ],
  "related": [
    {
      "slug": "navbar",
      "why": "页面级固定导航用导航栏（fixed 且带安全区与返回），区块内的贴合才用吸顶容器"
    },
    {
      "slug": "cell",
      "why": "吸顶条下面承载的列表项用单元格，吸顶容器只负责那一行的贴合行为"
    },
    {
      "slug": "mobile-list",
      "why": "需要分组标题列表时用列表组件，而不是给每一行都套一个吸顶容器"
    }
  ]
}