iter(g131): 新增悬浮操作按钮 floatButton

packages/skin/ui/src/floatButton.ts

@@ -0,0 +1,22 @@
+import { h } from '@ui-arch/frame';
+import type { FloatButtonProps } from './types.js';
+
+/*** 悬浮操作按钮：固定停靠左下 / 右下角，label 缺省为纯图标圆形；返回 fixed 包裹层，挂 body 才不被父级 overflow 裁剪 ***/
+export function floatButton(props: FloatButtonProps): HTMLElement {
+  const cls = ['ua-fab', props.label ? 'has-label' : ''].filter(Boolean).join(' ');
+  const btn = h('button', {
+    class: cls,
+    type: 'button',
+    'aria-label': props.tooltip ?? props.label ?? '快捷操作', // 纯图标时必须有可读名称
+    title: props.tooltip ?? null,
+  },
+  props.icon ? h('span', { class: 'ua-fab-icon', 'aria-hidden': 'true' }, props.icon) : null,
+  props.label ? h('span', { class: 'ua-fab-label' }, props.label) : null,
+  props.badge != null ? h('span', { class: 'ua-fab-badge' }, String(props.badge)) : null);
+  if (props.onClick) btn.addEventListener('click', props.onClick);
+  const offset = `${props.offset ?? 24}px`; // 缺省离边 24px，与常见浮动件手感一致
+  return h('div', {
+    class: `ua-fab-wrap is-${props.position ?? 'right-bottom'}`,
+    style: `--ua-fab-offset:${offset}`,
+  }, btn);
+}

packages/skin/ui/src/index.ts

@@ -62,3 +62,4 @@ export { popconfirm } from './popconfirm.js';
 export { calendar } from './calendar.js';
 export { typography } from './typography.js';
 export { grid } from './grid.js';
+export { floatButton } from './floatButton.js';

packages/skin/ui/src/types.ts

@@ -766,4 +766,15 @@ export interface GridProps {
   dense?: boolean;                  // 紧凑填充：小项回填空洞（瀑布式排布）；缺省 false
 }
 
+/*** 悬浮操作按钮入参 ***/
+export interface FloatButtonProps {
+  icon?: string | Node;      // 图标：字符串按字符（emoji / 符号）渲染，传 DOM 原样插入
+  label?: string;            // 文字标签；给了就出「图标 + 文字」胶囊，缺省纯图标圆形
+  badge?: string | number;   // 角标数字或短文案（如 3 / '新'）；缺省不渲染
+  tooltip?: string;          // 悬停提示，同时用作 aria-label；缺省取 label
+  position?: 'right-bottom' | 'left-bottom'; // 停靠角落；缺省右下
+  offset?: number;           // 距边距离（px）；缺省 24
+  onClick?: () => void;      // 点击回调
+}
+
 export type { ColumnDef, RowKey }; // 再导出常用内核类型，方便调用方

packages/skin/ui/ua.manifest.json

@@ -76,7 +76,8 @@
       "popconfirm(props, trigger)：二次确认气泡，挂在任意触发器上，就地确认危险操作；确定后先收起再回调，取消 / 点外部 / Esc 走 onCancel，展开即聚焦「取消」",
       "calendar(props)：月历，整月网格内嵌页面（排期 / 值班 / 日程），每日可带 marker 标记文案，方向键漫游 + Enter 选中，翻月走 onMonthChange",
       "typography(props)：排版文本，variant 决定语义（标题出 h1-h5 / 段落出 p / 行内出 span），支持语义色、装饰位、对齐、多行截断与复制按钮",
-      "grid(props, ...children)：栅格容器，columns 固定列数或 min 走 auto-fit 自适应列宽，gutter 统一列间距，窄屏自动降为单列"
+      "grid(props, ...children)：栅格容器，columns 固定列数或 min 走 auto-fit 自适应列宽，gutter 统一列间距，窄屏自动降为单列",
+      "floatButton(props)：悬浮操作按钮，固定停靠左下 / 右下角，label 缺省为纯图标圆形，badge 走角标，tooltip 兼作 aria-label"
     ],
     "keyTypes": [
       "ButtonProps",
@@ -3078,6 +3079,60 @@
           "子项必须是单个元素（card / div / 自定义块），grid 只负责排布且已对子项设 min-width: 0，长文本不会撑破列宽",
           "只要横向一排展示且元素不等宽，用 space 更轻；grid 面向二维对齐"
         ]
+      },
+      {
+        "id": "floatButton",
+        "title": "悬浮操作按钮 FloatButton",
+        "demo": "sec-floatbutton",
+        "props": [
+          {
+            "n": "icon",
+            "t": "string | Node",
+            "d": "图标：字符串按字符（emoji / 符号）渲染，传 DOM 原样插入"
+          },
+          {
+            "n": "label",
+            "t": "string",
+            "d": "文字标签；给了就出「图标 + 文字」胶囊，缺省为纯图标圆形"
+          },
+          {
+            "n": "badge",
+            "t": "string | number",
+            "d": "角标（数字或短文案，如 3 / '新'）；缺省不渲染"
+          },
+          {
+            "n": "tooltip",
+            "t": "string",
+            "d": "悬停提示，同时用作 aria-label；纯图标时必传，否则读屏听到默认「快捷操作」"
+          },
+          {
+            "n": "position",
+            "t": "'right-bottom' | 'left-bottom'",
+            "df": "right-bottom",
+            "d": "停靠角落；右下与 backTop 同侧，需同时出现时错开一左一右"
+          },
+          {
+            "n": "offset",
+            "t": "number",
+            "df": "24",
+            "d": "距边距离（px）；同角落堆叠多个时按倍数递增"
+          },
+          {
+            "n": "onClick",
+            "t": "() => void",
+            "k": 1,
+            "d": "点击回调"
+          }
+        ],
+        "example": "document.body.append(floatButton({ icon: '+', label: '新建工单', position: 'left-bottom', onClick: () => toast.success('已新建') })); document.body.append(floatButton({ icon: '?', tooltip: '帮助中心', badge: 3 }))",
+        "steps": [
+          "把返回节点挂到 document.body（不是页面容器内）：它是 fixed 定位，挂在容器里会被 overflow: hidden 裁剪",
+          "只有图标时务必传 tooltip：它同时是 aria-label，读屏用户靠它知道按钮干什么；有 label 时 tooltip 可省",
+          "label 存在即「图标 + 文字」胶囊，只有图标即 44px 圆形；两种形态都保证触摸目标不小于 44px",
+          "同一角落要放多个按钮时递增 offset（如 24 / 80），或把它们并进同一个 flex 容器统一排布——组件自身不做堆叠计算",
+          "右下角已被 backTop 占用，页面同时有返回顶部时用 position: 'left-bottom'",
+          "纯展示 + 单回调，没有选中态与开合状态；需要多级操作请用 menu / popover 挂在 onClick 上"
+        ]
       }
     ]
   }

packages/skin/ui/ui.css

@@ -4066,3 +4066,88 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); }
     grid-template-columns: 1fr;
   }
 }
+
+/* —— 悬浮操作按钮：fixed 停靠角落，hover 上浮 + 按压回缩 —— */
+.ua-fab-wrap {
+  position: fixed;
+  z-index: 40; /* 低于弹层（60+），高于正文 */
+  display: flex;
+  gap: var(--ua-space-2);
+}
+.ua-fab-wrap.is-right-bottom {
+  right: var(--ua-fab-offset, 24px);
+  bottom: var(--ua-fab-offset, 24px);
+}
+.ua-fab-wrap.is-left-bottom {
+  left: var(--ua-fab-offset, 24px);
+  bottom: var(--ua-fab-offset, 24px);
+}
+.ua-fab {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--ua-space-1);
+  min-width: 44px;
+  min-height: 44px; /* 触摸目标不小于 44px */
+  padding: 0;
+  border: 1px solid var(--ua-color-border);
+  border-radius: 50%;
+  background: var(--ua-color-surface);
+  color: var(--ua-color-text);
+  font: inherit;
+  font-size: var(--ua-font-size-md);
+  cursor: pointer;
+  box-shadow: 0 6px 20px color-mix(in srgb, var(--ua-color-text) 16%, transparent);
+  transition: transform 0.15s ease, box-shadow 0.15s ease, color 0.15s ease, border-color 0.15s ease;
+}
+.ua-fab.has-label {
+  padding: 0 var(--ua-space-3);
+  border-radius: 999px;
+}
+.ua-fab:hover {
+  color: var(--ua-color-accent);
+  border-color: var(--ua-color-accent);
+  transform: translateY(-2px);
+  box-shadow: 0 10px 26px color-mix(in srgb, var(--ua-color-text) 22%, transparent);
+}
+.ua-fab:active {
+  transform: translateY(0) scale(0.97);
+}
+.ua-fab:focus-visible {
+  outline: 2px solid var(--ua-color-accent);
+  outline-offset: 2px;
+}
+.ua-fab-icon {
+  display: inline-flex;
+  align-items: center;
+  line-height: 1;
+}
+.ua-fab-label {
+  font-size: var(--ua-font-size-sm);
+  white-space: nowrap;
+}
+.ua-fab-badge {
+  position: absolute;
+  top: -4px;
+  right: -4px;
+  min-width: 18px;
+  height: 18px;
+  padding: 0 4px;
+  border-radius: 999px;
+  background: var(--ua-color-danger);
+  color: var(--ua-color-accent-contrast);
+  font-size: 10px;
+  line-height: 18px;
+  text-align: center;
+  box-shadow: 0 0 0 2px var(--ua-color-bg); /* 与页面底色断开，避免和按钮边缘糊在一起 */
+}
+@media (prefers-reduced-motion: reduce) {
+  .ua-fab {
+    transition: none;
+  }
+  .ua-fab:hover,
+  .ua-fab:active {
+    transform: none;
+  }
+}