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

This commit is contained in:
HIsheR
2026-10-26 22:48:04 +08:00
parent 617269166a
commit 71cff84932
12 changed files with 299 additions and 12 deletions
+53 -2
View File
@@ -1,6 +1,6 @@
{
"$schema": "ui-arch-registry-index/0.1",
"generatedAt": "2026-10-26T14:26:38.557Z",
"generatedAt": "2026-10-26T14:47:27.279Z",
"repoRoot": ".",
"packages": [
{
@@ -219,7 +219,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",
@@ -4112,6 +4113,56 @@
"要区分大小写重复判断就传 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:不套多余容器,内容区独占整行"
]
}
]
},
+1 -1
View File
@@ -21,7 +21,7 @@
- `packages/core/table-core`(@ui-arch/table-core):Headless 表格逻辑内核
- `packages/core/frame`(@ui-arch/frame):signal + hyperscript 微框架
- `packages/skin/ui`(@ui-arch/ui):76 个 DOM 组件(表单 / 反馈 / 浮层 / 导航 / 表格),样式只消费令牌
- `packages/skin/ui`(@ui-arch/ui):77 个 DOM 组件(表单 / 反馈 / 浮层 / 导航 / 表格),样式只消费令牌
- `packages/design/tokens`(@ui-arch/tokens):设计令牌
- `packages/tools/cli`(@ui-arch/cli):`ua` 命令行 + MCP 注册表服务(private)
- `apps/demo`(@ui-arch/demo):交互演示,产物 apps/demo/dist/demo.html
+1 -1
View File
@@ -34,7 +34,7 @@ ui-arch-mvp/
│ │ ├── table-core/ # 表格状态内核
│ │ └── frame/ # 信号 + hyperscript 微框架
│ ├── skin/ # 皮肤层(DOM 组件,可发布)
│ │ └── ui/ # 76 个组件 + ui.css
│ │ └── ui/ # 77 个组件 + ui.css
│ ├── design/ # 资产层(可发布)
│ │ └── tokens/ # --ua-* 设计令牌
│ └── tools/ # 工程层(private,不发布)
+4 -4
View File
@@ -12,13 +12,13 @@ npm run docs # 生成人类文档站 apps/docs/index.html + Agent 全
npm run changelog # 依据 git 提交史重写 CHANGELOG.md(发版前跑;changelog:check 可查漂移)
```
## 组件(共 76 个)
## 组件(共 77 个)
<!-- ua:components -->
accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · colorPicker · commandPalette · copyButton · countdown · dataTable · datePicker · descriptions · divider · drawer · empty · floatButton · form · grid · highlight · image · inputNumber · inputTag · kbd · link · list · menu · modal · mentions · multiSelect · notification · pagination · pinInput · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · timePicker · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · virtualList · watermark
accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · colorPicker · commandPalette · copyButton · countdown · dataTable · datePicker · descriptions · divider · drawer · empty · floatButton · form · grid · highlight · image · inputNumber · inputTag · kbd · layout · link · list · menu · modal · mentions · multiSelect · notification · pagination · pinInput · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · timePicker · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · virtualList · watermark
<!-- /ua:components -->
分组:表单(button / copyButton / textField / inputNumber / inputTag / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / timePicker / pinInput / segmented / upload / form + formItem / transfer / cascader)、反馈(alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic / countdown)、浮层(tooltip / popover / popconfirm / modal / drawer / menu / commandPalette)、导航(tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor)、数据展示(dataTable / descriptions / card / list / kbd / highlight / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography / virtualList)、其他(floatButton / grid / link / space / divider / splitter / backTop / affix / tour / watermark)。
分组:表单(button / copyButton / textField / inputNumber / inputTag / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / timePicker / pinInput / segmented / upload / form + formItem / transfer / cascader)、反馈(alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic / countdown)、浮层(tooltip / popover / popconfirm / modal / drawer / menu / commandPalette)、导航(tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor)、数据展示(dataTable / descriptions / card / list / kbd / highlight / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography / virtualList)、其他(floatButton / grid / layout / link / space / divider / splitter / backTop / affix / tour / watermark)。
## 可访问性约定
@@ -33,7 +33,7 @@ accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup
|---|---|
| `packages/core/frame` | @ui-arch/frame:signal / computed / effect + hyperscript(无虚拟 DOM) |
| `packages/core/table-core` | @ui-arch/table-core:headless 表格(filter → sort → paginate 派生管线) |
| `packages/skin/ui` | @ui-arch/ui:76 个 DOM 组件 + ui.css(只消费 `--ua-*` 令牌) |
| `packages/skin/ui` | @ui-arch/ui:77 个 DOM 组件 + ui.css(只消费 `--ua-*` 令牌) |
| `packages/design/tokens` | @ui-arch/tokens:设计令牌(暗色只换值不换名) |
| `packages/tools/cli` | @ui-arch/cli:`ua` 命令行与 stdio MCP server |
| `apps/demo` | 交互演示(esbuild 打包成单文件) |
+18
View File
@@ -30,6 +30,7 @@ import {
copyButton,
countdown,
dataTable,
layout,
kbd,
highlight,
datePicker,
@@ -1705,6 +1706,23 @@ const content = h(
),
),
),
section(
'sec-layout',
'布局骨架',
'layout:页头 / 侧栏 / 内容 / 页脚一次成型,页头左侧开关可折叠侧栏;内容区自己滚动,页头能吸顶。骨架上不放圆角与投影——那是卡片的事。',
h('div', { style: 'height:280px;overflow:hidden;border-radius:var(--ua-radius-md)' },
layout(
{
header: h('strong', null, '控制台'),
sider: h('div', null, h('div', { class: 'out' }, '概览'), h('div', { class: 'out' }, '订单'), h('div', { class: 'out' }, '设置')),
footer: '© 2026 @ui-arch',
collapsible: true,
sticky: true,
},
card({ title: '内容区' }, typography({ variant: 'paragraph', type: 'secondary', content: '省略 header / sider / footer 时内容区独占整行;长内容页打开 sticky,页头随滚动留在顶部。' })),
),
),
),
);
// 悬浮按钮:fixed 定位,挂 body 不参与页面布局
+30 -1
View File
@@ -1,6 +1,6 @@
# @ui-arch 组件库 Agent 文档(无图形版)
> 自动生成于 2026-10-26T14:26:38.557Z,数据源:各包 ua.manifest.json,勿手改。人类版文档站:apps/docs/index.html。
> 自动生成于 2026-10-26T14:47:27.279Z,数据源:各包 ua.manifest.json,勿手改。人类版文档站:apps/docs/index.html。
> 组件 = 普通函数,传 props 返回 DOM;状态用 signal 双向绑定:读 signal() 写 signal(v)。
## 快速上手
@@ -2179,6 +2179,34 @@ inputTag({ value: tags, max: 5, onChange: (list) => console.log(list.length) })
现场演示:apps/docs/demo.html#sec-inputtag
### layout — 布局骨架 Layout
参数:
- header:unknown —— 页头内容(文案 / 节点);缺省不渲染页头
- sider:unknown —— 侧栏内容(通常是 menu);缺省则内容区独占整行
- footer:unknown —— 页脚内容;缺省不渲染页脚
- siderWidth:number —— 侧栏展开宽度(px);缺省 220
- collapsible:boolean —— 是否可折叠:true 时页头左侧出现折叠开关
- collapsed:Signal<boolean> —— 折叠态信号;传入则双向绑定(外部可读数),缺省内部自管
- sticky:boolean —— 页头是否吸顶;缺省 false(长内容里建议打开)
示例:
```
layout({ header: '控制台', sider: menu({ items }), footer: '© 2026', collapsible: true, sticky: true }, card({ title: '内容区' }, ...))
```
手把手:
1. 把整页交给 layout:children 就是内容区,页头 / 侧栏 / 页脚用 header / sider / footer 三个入参一次给全
2. 侧栏通常放 menu 或 anchor,宽度用 siderWidth 调(缺省 220px,够放四项中文菜单)
3. 需要折叠时传 collapsible: true,页头左侧自动出现开关;想把折叠态接到别处(比如只显示图标栏)就传 collapsed 信号读它的值
4. 长内容页面打开 sticky,页头吸顶;内容区自己滚动,不会把整页撑高
5. 只要内容不要骨架时省略 header / sider / footer:不套多余容器,内容区独占整行
现场演示:apps/docs/demo.html#sec-layout
API 速览:
- button(props):按钮,variant 三档视觉强度,disabled / loading 支持布尔或信号动态同步(loading 转圈并禁点),onClick 点击回调
@@ -2259,6 +2287,7 @@ API 速览:
- kbd(props):键盘按键标记,键帽样式展示单个按键或组合键(多键以 + 连接),用于快捷键提示
- highlight(props):关键词高亮,命中片段包 mark(大小写不敏感全部命中),text / keyword 支持信号响应式刷新
- inputTag(props):标签输入,输入后回车 / 逗号成标签、chip 可单个删除、空框退格删末个,value 信号双向绑定,max 满额自动禁输
- layout(props, ...children):布局骨架,页头 / 侧栏 / 内容 / 页脚四区一次成型,侧栏可折叠(collapsed 信号双向绑定)
一行用法:
+1
View File
@@ -125,6 +125,7 @@
- kbd(props):键盘按键标记,键帽样式展示单个按键或组合键(多键以 + 连接),用于快捷键提示
- highlight(props):关键词高亮,命中片段包 mark(大小写不敏感全部命中),text / keyword 支持信号响应式刷新
- inputTag(props):标签输入,输入后回车 / 逗号成标签、chip 可单个删除、空框退格删末个,value 信号双向绑定,max 满额自动禁输
- layout(props, ...children):布局骨架,页头 / 侧栏 / 内容 / 页脚四区一次成型,侧栏可折叠(collapsed 信号双向绑定)
- 用法: `const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')`
- 约定: 皮肤不持有业务状态,一律委托 headless 内核或调用方信号
- 约定: 表单类组件统一约定:*Props.value/checked/active 为 Signal 双向绑定,onChange/onInput 为回调
+1
View File
@@ -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';
+32
View File
@@ -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;
}
+11
View File
@@ -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(长内容里建议打开)
}
+52 -1
View File
@@ -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,6 +3984,56 @@
"要区分大小写重复判断就传 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:不套多余容器,内容区独占整行"
]
}
]
}
+94 -1
View File
@@ -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);
}