temp/UI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

iter(g58): 新增 affix 固钉组件

Browse Source
This commit is contained in:
HIsheR
2026-10-26 12:23:25 +08:00
parent 89cddada21
commit 7684ae2b10
12 changed files with 166 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.ua/index.json
+32 -2
View File
@@ -1,6 +1,6 @@
{
"$schema": "ui-arch-registry-index/0.1",
"generatedAt": "2026-10-26T04:21:58.071Z",
"generatedAt": "2026-10-26T04:23:09.567Z",
"repoRoot": ".",
"packages": [
{
@@ -197,7 +197,8 @@
"colorPicker(props)：颜色选择，预设色板（缺省语义令牌色）+ 原生取色器 + 手输 CSS 颜色串，value 为颜色串信号",
"tour(props)：引导漫游，返回 { el, start, close } 句柄；聚光框按 target 选择器定位，卡片自动选方位，Esc / 跳过走 onClose",
"watermark(props, ...children)：内容容器 + 平铺水印覆盖层，canvas 生成单元、颜色取自令牌，覆盖层不挡交互",
"checkboxGroup(props)：多选组，value 为数组信号，min/max 用禁用边界项实现（不抛错），checkAll 支持半选且只统计未禁用项"
"checkboxGroup(props)：多选组，value 为数组信号，min/max 用禁用边界项实现（不抛错），checkAll 支持半选且只统计未禁用项",
"affix(props, ...children)：固钉，滚过 offset 后内容转 fixed 贴顶、外层保留占位高度，固定后宽度随容器自适应"
],
"keyTypes": [
"ButtonProps",
@@ -2519,6 +2520,35 @@
"checkAll 行的选中/半选只统计未禁用项，禁用项不计入基数",
"direction 传 vertical 改为纵向排列；disabled 支持信号，整组响应式禁用"
]
},
{
"id": "affix",
"title": "固钉 Affix",
"demo": "sec-affix",
"props": [
{
"n": "offset",
"t": "number",
"d": "距视口顶部多少像素后转为固定；缺省 0"
},
{
"n": "target",
"t": "HTMLElement | Window",
"d": "监听的滚动容器；缺省 window（整页）"
},
{
"n": "children",
"t": "...unknown[]",
"d": "被固定的内容，作为第二个及之后的实参传入"
}
],
"example": "affix({ offset: 8 }, card({ title: '滚动时我会贴顶' }, h('p', null, '正文')))",
"steps": [
"把要贴住的内容作为实参传入；组件内部包两层：外层占位、内层负责 fixed",
"滚动到 offset 以内（默认贴视口顶）时内层转 fixed，外层同步撑出等高占位，页面不会塌跳",
"固定期间宽度与横向位置跟随占位容器，窗口缩放或父容器变宽都自动贴合",
"内滚容器场景把该元素传给 target，判定改为基于它的滚动位置"
]
}
]
},
AGENTS.md
+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）：54 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌
- `packages/skin/ui`（@ui-arch/ui）：55 个 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
ARCHITECTURE.md
+1 -1
View File
@@ -34,7 +34,7 @@ ui-arch-mvp/
│ │ ├── table-core/ # 表格状态内核
│ │ └── frame/ # 信号 + hyperscript 微框架
│ ├── skin/ # 皮肤层（DOM 组件，可发布）
│ │ └── ui/ # 54 个组件 + ui.css
│ │ └── ui/ # 55 个组件 + ui.css
│ ├── design/ # 资产层（可发布）
│ │ └── tokens/ # --ua-* 设计令牌
│ └── tools/ # 工程层（private，不发布）
README.md
+4 -4
View File
@@ -11,13 +11,13 @@ npm run demo # 打开演示：apps/demo/dist/demo.html
npm run docs # 生成人类文档站 apps/docs/index.html + Agent 全量文档 llms-full.txt
```
## 组件（共 54 个）
## 组件（共 55 个）
<!-- ua:components -->
accordion · alert · autoComplete · avatar · backTop · badge · breadcrumb · button · carousel · card · cascader · checkbox · checkboxGroup · colorPicker · dataTable · datePicker · descriptions · divider · drawer · empty · form · image · inputNumber · list · menu · modal · notification · pagination · popover · progress · radioGroup · rate · result · segmented · select · skeleton · slider · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · toast · tooltip · tour · transfer · tree · upload · watermark
accordion · affix · alert · autoComplete · avatar · backTop · badge · breadcrumb · button · carousel · card · cascader · checkbox · checkboxGroup · colorPicker · dataTable · datePicker · descriptions · divider · drawer · empty · form · image · inputNumber · list · menu · modal · notification · pagination · popover · progress · radioGroup · rate · result · segmented · select · skeleton · slider · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · toast · tooltip · tour · transfer · tree · upload · watermark
<!-- /ua:components -->
分组：表单（button / textField / inputNumber / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / radioGroup / slider / rate / autoComplete / datePicker / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic）、浮层（tooltip / popover / modal / drawer / menu）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree）、数据展示（dataTable / descriptions / card / list / timeline / tag / avatar / image / carousel）、其他（divider / splitter / backTop / tour / watermark）。
分组：表单（button / textField / inputNumber / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / radioGroup / slider / rate / autoComplete / datePicker / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic）、浮层（tooltip / popover / modal / drawer / menu）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree）、数据展示（dataTable / descriptions / card / list / timeline / tag / avatar / image / carousel）、其他（divider / splitter / backTop / affix / tour / watermark）。
## 可访问性约定
@@ -31,7 +31,7 @@ accordion · alert · autoComplete · avatar · backTop · badge · breadcrumb
|---|---|
| `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：54 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
| `packages/skin/ui` | @ui-arch/ui：55 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
| `packages/design/tokens` | @ui-arch/tokens：设计令牌（暗色只换值不换名） |
| `packages/tools/cli` | @ui-arch/cli：`ua` 命令行与 stdio MCP server |
| `apps/demo` | 交互演示（esbuild 打包成单文件） |
apps/demo/main.ts
+14
View File
@@ -9,6 +9,7 @@ const IMG_DEMO = 'data:image/svg+xml;utf8,' + encodeURIComponent(
);
import {
accordion,
affix,
alert,
autoComplete,
avatar,
@@ -763,6 +764,19 @@ const content = h(
h('span', { class: 'ua-colorpicker-swatch', style: () => `background:${colorVal()}` }),
),
),
section(
'sec-affix',
'固钉',
'affix：内容滚过阈值后转 fixed 贴顶，外层保留占位高度不塌陷；固定后宽度随容器自适应。',
h(
'div',
{ class: 'row' },
h('div', { style: 'flex:1;min-height:320px;display:flex;gap:16px' },
affix({ offset: 8 }, card({ title: '滚动时我会贴顶' }, h('p', { class: 'desc' }, '向下滚动本页，这块卡片会固定在视口顶部（距顶 8px），左侧占位不会塌。'))),
h('div', { class: 'desc', style: 'flex:1' }, '右侧是普通内容，用来撑高这一行，方便观察固钉效果。'.repeat(6)),
),
),
),
section(
'sec-backtop',
'返回顶部',
llms-full.txt
+25 -1
View File
@@ -1,6 +1,6 @@
# @ui-arch 组件库 Agent 文档（无图形版）
> 自动生成于 2026-10-26T04:21:58.071Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
> 自动生成于 2026-10-26T04:23:09.567Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
> 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
## 快速上手
@@ -1442,6 +1442,29 @@ checkboxGroup({ value: permPick, min: 1, max: 3, checkAll: true, options: [{ val
现场演示：apps/docs/demo.html#sec-checkgroup
### affix — 固钉 Affix
参数：
- offset：number —— 距视口顶部多少像素后转为固定；缺省 0
- target：HTMLElement | Window —— 监听的滚动容器；缺省 window（整页）
- children：...unknown[] —— 被固定的内容，作为第二个及之后的实参传入
示例：
```
affix({ offset: 8 }, card({ title: '滚动时我会贴顶' }, h('p', null, '正文')))
```
手把手：
1. 把要贴住的内容作为实参传入；组件内部包两层：外层占位、内层负责 fixed
2. 滚动到 offset 以内（默认贴视口顶）时内层转 fixed，外层同步撑出等高占位，页面不会塌跳
3. 固定期间宽度与横向位置跟随占位容器，窗口缩放或父容器变宽都自动贴合
4. 内滚容器场景把该元素传给 target，判定改为基于它的滚动位置
现场演示：apps/docs/demo.html#sec-affix
API 速览：
- button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用；type 缺省 button（表单内不隐式提交）
@@ -1500,6 +1523,7 @@ API 速览：
- tour(props)：引导漫游，返回 { el, start, close } 句柄；聚光框按 target 选择器定位，卡片自动选方位，Esc / 跳过走 onClose
- watermark(props, ...children)：内容容器 + 平铺水印覆盖层，canvas 生成单元、颜色取自令牌，覆盖层不挡交互
- checkboxGroup(props)：多选组，value 为数组信号，min/max 用禁用边界项实现（不抛错），checkAll 支持半选且只统计未禁用项
- affix(props, ...children)：固钉，滚过 offset 后内容转 fixed 贴顶、外层保留占位高度，固定后宽度随容器自适应
一行用法：
llms.txt
+1
View File
@@ -103,6 +103,7 @@
- tour(props)：引导漫游，返回 { el, start, close } 句柄；聚光框按 target 选择器定位，卡片自动选方位，Esc / 跳过走 onClose
- watermark(props, ...children)：内容容器 + 平铺水印覆盖层，canvas 生成单元、颜色取自令牌，覆盖层不挡交互
- checkboxGroup(props)：多选组，value 为数组信号，min/max 用禁用边界项实现（不抛错），checkAll 支持半选且只统计未禁用项
- affix(props, ...children)：固钉，滚过 offset 后内容转 fixed 贴顶、外层保留占位高度，固定后宽度随容器自适应
- 用法: `const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')`
- 约定: 皮肤不持有业务状态，一律委托 headless 内核或调用方信号
- 约定: 表单类组件统一约定：*Props.value/checked/active 为 Signal 双向绑定，onChange/onInput 为回调
packages/skin/ui/src/affix.ts
+43
View File
@@ -0,0 +1,43 @@
import { h } from '@ui-arch/frame';
import type { AffixProps } from './types.js';
/*** 固钉：内容滚动越过阈值后转 fixed 贴住视口顶部，外层保留占位高度避免布局跳动 ***/
export function affix(props: AffixProps, ...children: unknown[]): HTMLElement {
// —— 状态集中声明 ——
const offset = props.offset ?? 0; // 触发固定的阈值
const scroller = props.target ?? window; // 滚动容器
const inner = h('div', { class: 'ua-affix-inner' }, ...children) as HTMLElement; // 真正会被固定的内容
const wrap = h('div', { class: 'ua-affix' }, inner) as HTMLElement; // 占位容器，固定时撑住原位
let fixed = false; // 当前是否已固定，避免每次滚动都重写样式
/*** 同步固定态：越过阈值即 fixed + 撑占位高度，回到阈值以上就还原 ***/
const sync = (): void => {
const box = wrap.getBoundingClientRect(); // 占位容器几何：left / width 决定固定后的横向位置
const should = box.top <= offset; // 已滚到阈值之上
if (should === fixed) {
if (fixed) { // 固定中：宽度与横向位置跟随容器（窗口缩放 / 父容器变宽）
inner.style.width = `${box.width}px`;
inner.style.left = `${box.left}px`;
}
return; // 卫语句：状态未变不重写其余样式
}
fixed = should;
if (fixed) {
wrap.style.height = `${inner.offsetHeight}px`; // 先撑住占位，再让 inner 脱离文档流
inner.classList.add('is-fixed');
inner.style.top = `${offset}px`;
inner.style.left = `${box.left}px`;
inner.style.width = `${box.width}px`;
} else {
inner.classList.remove('is-fixed');
inner.style.top = '';
inner.style.width = '';
wrap.style.height = '';
}
};
scroller.addEventListener('scroll', sync, { passive: true }); // 被动监听，不阻塞滚动
window.addEventListener('resize', sync); // 视口变化会改判定与宽度
sync(); // 首屏同步一次：刷新时若已滚动到位，直接进入固定态
return wrap;
}
packages/skin/ui/src/index.ts
+1
View File
@@ -54,3 +54,4 @@ export { backTop } from './backTop.js';
export { colorPicker } from './colorPicker.js';
export { tour } from './tour.js';
export { watermark } from './watermark.js';
export { affix } from './affix.js';
packages/skin/ui/src/types.ts
+6
View File
@@ -620,4 +620,10 @@ export interface CheckboxGroupProps {
onChange?: (values: string[]) => void; // 变更回调（传副本）
}
/*** 固钉入参 ***/
export interface AffixProps {
offset?: number; // 距视口顶部多少像素后转为固定；缺省 0
target?: HTMLElement | Window; // 监听的滚动容器；缺省 window
}
export type { ColumnDef, RowKey }; // 再导出常用内核类型，方便调用方
packages/skin/ui/ua.manifest.json
+31 -1
View File
@@ -68,7 +68,8 @@
"colorPicker(props)：颜色选择，预设色板（缺省语义令牌色）+ 原生取色器 + 手输 CSS 颜色串，value 为颜色串信号",
"tour(props)：引导漫游，返回 { el, start, close } 句柄；聚光框按 target 选择器定位，卡片自动选方位，Esc / 跳过走 onClose",
"watermark(props, ...children)：内容容器 + 平铺水印覆盖层，canvas 生成单元、颜色取自令牌，覆盖层不挡交互",
"checkboxGroup(props)：多选组，value 为数组信号，min/max 用禁用边界项实现（不抛错），checkAll 支持半选且只统计未禁用项"
"checkboxGroup(props)：多选组，value 为数组信号，min/max 用禁用边界项实现（不抛错），checkAll 支持半选且只统计未禁用项",
"affix(props, ...children)：固钉，滚过 offset 后内容转 fixed 贴顶、外层保留占位高度，固定后宽度随容器自适应"
],
"keyTypes": [
"ButtonProps",
@@ -2390,6 +2391,35 @@
"checkAll 行的选中/半选只统计未禁用项，禁用项不计入基数",
"direction 传 vertical 改为纵向排列；disabled 支持信号，整组响应式禁用"
]
},
{
"id": "affix",
"title": "固钉 Affix",
"demo": "sec-affix",
"props": [
{
"n": "offset",
"t": "number",
"d": "距视口顶部多少像素后转为固定；缺省 0"
},
{
"n": "target",
"t": "HTMLElement | Window",
"d": "监听的滚动容器；缺省 window（整页）"
},
{
"n": "children",
"t": "...unknown[]",
"d": "被固定的内容，作为第二个及之后的实参传入"
}
],
"example": "affix({ offset: 8 }, card({ title: '滚动时我会贴顶' }, h('p', null, '正文')))",
"steps": [
"把要贴住的内容作为实参传入；组件内部包两层：外层占位、内层负责 fixed",
"滚动到 offset 以内（默认贴视口顶）时内层转 fixed，外层同步撑出等高占位，页面不会塌跳",
"固定期间宽度与横向位置跟随占位容器，窗口缩放或父容器变宽都自动贴合",
"内滚容器场景把该元素传给 target，判定改为基于它的滚动位置"
]
}
]
}
packages/skin/ui/ui.css
+7
View File
@@ -3250,3 +3250,10 @@ button.ua-step-dot:hover {
align-items: flex-start;
gap: var(--ua-space-1);
}
.ua-affix {
position: relative;
}
.ua-affix-inner.is-fixed {
position: fixed;
z-index: 50;
}