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

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "confidence": "high",
  "specSection": "11 · 弹出层 Popup",
  "slug": "mobile-popup",
  "name": "弹出层 Popup",
  "semanticTypeCandidates": [
    "popup",
    "overlay",
    "layer"
  ],
  "variantDimensions": [
    {
      "name": "placement",
      "values": [
        "center",
        "bottom",
        "top",
        "left",
        "right"
      ]
    },
    {
      "name": "round",
      "values": [
        "false",
        "true"
      ]
    }
  ],
  "representativeVariants": [
    {
      "placement": "center",
      "round": "true",
      "label": "居中弹窗"
    },
    {
      "placement": "bottom",
      "round": "true",
      "label": "底部弹出（最常用）"
    },
    {
      "placement": "top",
      "round": "true",
      "label": "顶部弹出"
    },
    {
      "placement": "right",
      "round": "true",
      "label": "右侧滑出"
    }
  ],
  "anatomy": {
    "mask": "遮罩，点击关闭（可关）",
    "popup": "浮层容器，按方向定位",
    "header": "可选标题区",
    "body": "内容区，可滚动",
    "close": "可选关闭按钮"
  },
  "structurePatterns": {
    "placement": "center / bottom / top / left / right",
    "round": "false / true（贴边方向在靠内容一侧切圆角）"
  },
  "usageHints": [
    "从指定方向弹出的浮层基座，承载面板、抽屉、动作列表等内容",
    "遮罩点击关闭；closeOnMask=false 时不关闭",
    "滑入动画 240ms，缓动 cubic-bezier(.32,.72,0,1)",
    "内容超出时 body 内部滚动，遮罩不滚动",
    "浮层 role=\"dialog\" + aria-modal=\"true\"",
    "关闭按钮为原生 button 并带 aria-label"
  ],
  "doNotInvent": [
    "多浮层堆叠的层级规则",
    "手势下滑关闭的阈值"
  ],
  "unknowns": [
    "各方向的内容最大尺寸",
    "是否需要焦点陷阱（focus trap）"
  ],
  "interaction": [
    "遮罩点击关闭；closeOnMask=false 时不关闭",
    "滑入动画 240ms，缓动 cubic-bezier(.32,.72,0,1)",
    "内容超出时 body 内部滚动，遮罩不滚动"
  ],
  "accessibility": [
    "浮层 role=\"dialog\" + aria-modal=\"true\"",
    "遮罩 aria-hidden=\"true\"（纯装饰）",
    "关闭按钮为原生 button 并带 aria-label"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "placement",
        "type": "'center' | 'bottom' | 'top' | 'left' | 'right'",
        "default": "'bottom'",
        "desc": "变体 placement：弹出方向（规格 §11.3）",
        "required": false
      },
      {
        "name": "round",
        "type": "boolean",
        "default": "false",
        "desc": "变体 round：贴边方向在靠内容一侧切圆角（规格 §11.3）",
        "required": false
      },
      {
        "name": "open",
        "type": "boolean",
        "default": "false",
        "desc": "状态 open：展开且遮罩可见（规格 §11.4）",
        "required": false
      },
      {
        "name": "closeOnMask",
        "type": "boolean",
        "default": "true",
        "desc": "遮罩点击是否关闭浮层；表单类内容通常设为 false（规格 §11.5）",
        "required": false
      },
      {
        "name": "title",
        "type": "string",
        "default": "''",
        "desc": "标题区文字，同时作为关闭按钮 aria-label 的一部分（规格 §11.2 header）",
        "required": false
      }
    ],
    "events": [
      {
        "name": "close",
        "params": "—",
        "desc": "点击遮罩（closeOnMask=true 时）或关闭按钮时触发（规格 §11.5）"
      }
    ],
    "slots": [
      {
        "name": "default",
        "desc": "内容区，可滚动；超出时在内部滚动而遮罩不滚动（规格 §11.2 body）"
      }
    ]
  },
  "variantClasses": {
    "placement": {
      "center": [
        ".kole-m-popup--center"
      ],
      "bottom": [
        ".kole-m-popup--bottom"
      ],
      "top": [
        ".kole-m-popup--top"
      ],
      "left": [
        ".kole-m-popup--left"
      ],
      "right": [
        ".kole-m-popup--right"
      ]
    },
    "round": {
      "false": [],
      "true": [
        ".kole-m-popup--round"
      ]
    }
  },
  "demos": [
    {
      "id": "center",
      "group": "01 组件类型",
      "title": "居中弹窗",
      "desc": "居中浮层用缩放淡入而不是位移，避免在窄屏上「从某一边冒出来」的错觉。",
      "variant": "placement=center"
    },
    {
      "id": "bottom",
      "group": "01 组件类型",
      "title": "底部弹出",
      "desc": "移动端最常用的形态：拇指可达且不遮挡上下文；round=true 时靠内容一侧切圆角。",
      "variant": "placement=bottom"
    },
    {
      "id": "top",
      "group": "01 组件类型",
      "title": "顶部弹出",
      "desc": "从屏幕上方滑入，适合「一次性选择后立即关闭」的地址选择与全局提示条。",
      "variant": "placement=top"
    },
    {
      "id": "sides",
      "group": "02 组件状态",
      "title": "左右侧滑",
      "desc": "高度铺满、宽度受限（不超过 80%），用于次级导航或详情；默认展开以便对照。",
      "variant": "placement=left|right"
    },
    {
      "id": "keep-open",
      "group": "02 组件状态",
      "title": "遮罩不关闭",
      "desc": "closeOnMask=false：误触遮罩不关闭浮层，表单类内容不该因为一次误触就丢弃已填数据。",
      "variant": "closeOnMask=false"
    },
    {
      "id": "scroll",
      "group": "02 组件状态",
      "title": "内容超长",
      "desc": "高度上限为屏幕的 80%，超出部分在内容区内部滚动，头部与关闭按钮固定不动。",
      "variant": "状态 scroll"
    }
  ],
  "related": [
    {
      "slug": "actionsheet",
      "why": "固定从底部弹出的操作列表用动作面板，需要其它方向或自定义内容时才用弹出层"
    },
    {
      "slug": "mobile-divider",
      "why": "浮层内的分区用分割线，而不是靠留白或额外容器表达"
    },
    {
      "slug": "cell",
      "why": "浮层里列选项用单元格，不要用带指针悬浮态的桌面式列表"
    }
  ]
}