iter(g265): 新增布局骨架组件 layout

2026-10-26 22:48:04 +08:00
parent 617269166a
commit 71cff84932
12 changed files with 299 additions and 12 deletions
@@ -76,3 +76,4 @@ export { countdown } from './countdown.js';
 export { kbd } from './kbd.js';
 export { highlight } from './highlight.js';
 export { inputTag } from './inputTag.js';
+export { layout } from './layout.js';
@@ -0,0 +1,32 @@
+import { h, signal } from '@ui-arch/frame';
+import type { LayoutProps } from './types.js';
+
+// 侧栏展开态缺省宽度（px）：够放下四个汉字的菜单项，再窄就要靠折叠态图标栏
+const SIDER_DEFAULT = 220;
+
+/*** 布局骨架：页头 / 侧栏 / 内容 / 页脚四区一次成型，侧栏可折叠（受控或自管）；只管骨架与间距，导航内容交给 menu / anchor ***/
+export function layout(props: LayoutProps, ...children: unknown[]): HTMLElement {
+  const collapsed = props.collapsed ?? signal(false); // 折叠态：外部给了信号就双向绑定，没给就内部自管
+  const width = props.siderWidth ?? SIDER_DEFAULT; // 侧栏宽度：折叠时由样式表收到 0，这里只给展开值
+  const toggle = (): void => { collapsed(!collapsed()); }; // 折叠开关：只翻信号，视觉由类名响应
+  const rootCls = ['ua-layout', props.sticky ? 'is-sticky' : ''].filter(Boolean).join(' '); // 根类名：吸顶页头是同一个容器上的修饰类
+  const header = props.header === undefined
+    ? null // 没有页头就不渲染容器，避免多一层空盒子影响 :first-child 选择器
+    : h(
+      'header',
+      { class: 'ua-layout-header' },
+      props.collapsible ? h('button', { class: 'ua-layout-toggle', type: 'button', 'aria-expanded': () => String(!collapsed()), 'aria-label': '折叠或展开侧栏', onClick: toggle }, '⟨⟩') : null,
+      props.header,
+    );
+  const sider = props.sider === undefined
+    ? null // 没有侧栏时内容区独占整行，省掉一条 220px 的空白
+    : h('aside', {
+      class: () => `ua-layout-sider${collapsed() ? ' is-collapsed' : ''}`,
+      style: `width:${width}px`, // 展开宽度内联，折叠后的收拢宽度交给类名（0 + overflow hidden）
+      'aria-hidden': () => (collapsed() ? 'true' : null), // 折叠后视觉消失，读屏也不再报里面的菜单
+    }, props.sider);
+  const content = h('main', { class: 'ua-layout-content' }, ...children);
+  const body = sider ? h('div', { class: 'ua-layout-body' }, sider, content) : content; // 无侧栏时不套 body 层
+  const footer = props.footer === undefined ? null : h('footer', { class: 'ua-layout-footer' }, props.footer);
+  return h('div', { class: rootCls }, header, body, footer) as HTMLElement;
+}
@@ -1010,3 +1010,14 @@ export interface InputTagProps {
  ariaLabel?: string;                                 // 输入框无障碍标签；缺省「标签输入」
  onChange?: (tags: string[]) => void;                // 标签集合变化回调（参数是变化后的完整集合）
 }
+
+/*** 布局骨架入参 ***/
+export interface LayoutProps {
+  header?: unknown;                // 页头内容（文案 / 节点）；缺省不渲染页头
+  sider?: unknown;                 // 侧栏内容（通常是 menu）；缺省则内容区独占整行
+  footer?: unknown;                // 页脚内容；缺省不渲染页脚
+  siderWidth?: number;             // 侧栏展开宽度（px）；缺省 220
+  collapsible?: boolean;           // 是否可折叠：true 时页头左侧出现折叠开关
+  collapsed?: Signal<boolean>;     // 折叠态信号；传入则双向绑定（外部可读数），缺省内部自管
+  sticky?: boolean;                // 页头是否吸顶；缺省 false（长内容里建议打开）
+}
@@ -90,7 +90,8 @@
      "countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset",
      "kbd(props)：键盘按键标记，键帽样式展示单个按键或组合键（多键以 + 连接），用于快捷键提示",
      "highlight(props)：关键词高亮，命中片段包 mark（大小写不敏感全部命中），text / keyword 支持信号响应式刷新",
-      "inputTag(props)：标签输入，输入后回车 / 逗号成标签、chip 可单个删除、空框退格删末个，value 信号双向绑定，max 满额自动禁输"
+      "inputTag(props)：标签输入，输入后回车 / 逗号成标签、chip 可单个删除、空框退格删末个，value 信号双向绑定，max 满额自动禁输",
+      "layout(props, ...children)：布局骨架，页头 / 侧栏 / 内容 / 页脚四区一次成型，侧栏可折叠（collapsed 信号双向绑定）"
    ],
    "keyTypes": [
      "ButtonProps",
@@ -3983,7 +3984,57 @@
          "要区分大小写重复判断就传 allowDuplicate: true；默认按原样去重",
          "样式复用输入组与标签：外框聚焦光环、chip 圆角与语义色都跟既有组件一致，无新增视觉字面量"
        ]
+      },
+      {
+        "id": "layout",
+        "title": "布局骨架 Layout",
+        "demo": "sec-layout",
+        "props": [
+          {
+            "n": "header",
+            "t": "unknown",
+            "d": "页头内容（文案 / 节点）；缺省不渲染页头"
+          },
+          {
+            "n": "sider",
+            "t": "unknown",
+            "d": "侧栏内容（通常是 menu）；缺省则内容区独占整行"
+          },
+          {
+            "n": "footer",
+            "t": "unknown",
+            "d": "页脚内容；缺省不渲染页脚"
+          },
+          {
+            "n": "siderWidth",
+            "t": "number",
+            "d": "侧栏展开宽度（px）；缺省 220"
+          },
+          {
+            "n": "collapsible",
+            "t": "boolean",
+            "d": "是否可折叠：true 时页头左侧出现折叠开关"
+          },
+          {
+            "n": "collapsed",
+            "t": "Signal<boolean>",
+            "d": "折叠态信号；传入则双向绑定（外部可读数），缺省内部自管"
+          },
+          {
+            "n": "sticky",
+            "t": "boolean",
+            "d": "页头是否吸顶；缺省 false（长内容里建议打开）"
+          }
+        ],
+        "example": "layout({ header: '控制台', sider: menu({ items }), footer: '© 2026', collapsible: true, sticky: true }, card({ title: '内容区' }, ...))",
+        "steps": [
+          "把整页交给 layout：children 就是内容区，页头 / 侧栏 / 页脚用 header / sider / footer 三个入参一次给全",
+          "侧栏通常放 menu 或 anchor，宽度用 siderWidth 调（缺省 220px，够放四项中文菜单）",
+          "需要折叠时传 collapsible: true，页头左侧自动出现开关；想把折叠态接到别处（比如只显示图标栏）就传 collapsed 信号读它的值",
+          "长内容页面打开 sticky，页头吸顶；内容区自己滚动，不会把整页撑高",
+          "只要内容不要骨架时省略 header / sider / footer：不套多余容器，内容区独占整行"
+        ]
      }
    ]
  }
-}
+}
@@ -4992,7 +4992,8 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); }
 .ua-treeselect-pop,
 .ua-vlist,
 .ua-cmdk-list,
-.ua-timepicker-col {
+.ua-timepicker-col,
+.ua-layout-content {
  scrollbar-width: thin; /* 标准属性：Firefox / Chromium 121+ 生效，细条不挤内容 */
  scrollbar-color: var(--ua-color-scrollbar) transparent; /* 拇指走令牌、轨道透明，避免画出方块底 */
 }
@@ -5314,3 +5315,95 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); }
    translate: none !important; /* 少数组件用独立 translate 属性做位移，一并归零 */
  }
 }
+
+/* ---- 布局骨架：只管四区位置与间距，颜色一律走表面 / 描边令牌 ----
+   骨架不带圆角与投影：它是页面容器而非卡片，浮起感应留给内容里的 card / modal */
+.ua-layout {
+  display: flex;
+  flex-direction: column;
+  min-height: 100%;
+  background: var(--ua-color-bg);
+  color: var(--ua-color-text);
+}
+
+.ua-layout-header {
+  display: flex;
+  flex: 0 0 auto;
+  align-items: center;
+  gap: var(--ua-space-3);
+  padding: var(--ua-space-3) var(--ua-space-4);
+  background: var(--ua-color-surface);
+  box-shadow: var(--ua-shadow-hairline); /* 页头与内容之间只留一道细线，不叠边框 */
+  font-size: var(--ua-font-size-md);
+}
+
+/* 吸顶：长内容里页头随滚动留在顶部，层级与其它吸顶件同档 */
+.ua-layout.is-sticky .ua-layout-header {
+  position: sticky;
+  top: 0;
+  z-index: var(--ua-z-sticky);
+}
+
+/* 折叠开关：方形小按钮，只放符号，所以宽度直接锁控件高度档位 */
+.ua-layout-toggle {
+  display: inline-flex;
+  flex: 0 0 auto;
+  align-items: center;
+  justify-content: center;
+  width: var(--ua-control-h-sm);
+  height: var(--ua-control-h-sm);
+  padding: 0;
+  border: 1px solid var(--ua-color-border);
+  border-radius: var(--ua-radius-sm);
+  background: transparent;
+  color: var(--ua-color-text-muted);
+  font-size: var(--ua-font-size-sm);
+  cursor: pointer;
+  transition: background var(--ua-duration-fast) var(--ua-ease), color var(--ua-duration-fast) var(--ua-ease);
+}
+
+.ua-layout-toggle:hover {
+  background: var(--ua-color-tint-accent-weak);
+  color: var(--ua-color-accent);
+}
+
+.ua-layout-toggle:focus-visible {
+  outline: none;
+  box-shadow: var(--ua-focus-ring);
+}
+
+.ua-layout-body {
+  display: flex;
+  flex: 1 1 auto;
+  min-height: 0; /* 允许内部内容区自己滚动，而不是把整页撑高 */
+}
+
+/* 侧栏：宽度由内联的展开值给，折叠时收成 0 并由 overflow 裁掉内容 */
+.ua-layout-sider {
+  flex: 0 0 auto;
+  overflow: hidden;
+  padding: var(--ua-space-3);
+  border-right: 1px solid var(--ua-color-border);
+  background: var(--ua-color-surface);
+  transition: width var(--ua-duration-base) var(--ua-ease), padding var(--ua-duration-base) var(--ua-ease);
+}
+
+.ua-layout-sider.is-collapsed {
+  width: 0 !important; /* 压过内联展开宽度：折叠态是唯一的宽度来源，避免两处各写一份 */
+  padding-inline: 0;
+}
+
+.ua-layout-content {
+  flex: 1 1 auto;
+  min-width: 0; /* 内容区允许被压缩：否则宽表格会把侧栏挤回去 */
+  padding: var(--ua-space-4);
+  overflow: auto;
+}
+
+.ua-layout-footer {
+  flex: 0 0 auto;
+  padding: var(--ua-space-3) var(--ua-space-4);
+  border-top: 1px solid var(--ua-color-border);
+  color: var(--ua-color-text-muted);
+  font-size: var(--ua-font-size-sm);
+}