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

iter(g139): 提示气泡支持左右方位

Browse Source
This commit is contained in:
HIsheR
2026-10-26 15:32:47 +08:00
parent a3db5e66fc
commit 08ceb8f127
9 changed files with 62 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.ua/backlog.json
+8
View File
@@ -1468,6 +1468,14 @@
"acceptance": "datePicker 新增 range/end/onRangeChange：首点定起点不收弹层、次点定终点并排序，区间内部有底色；文档 props/steps 与演示同步；npm run check 全绿",
"notes": "自补：既有组件可用性细节",
"status": "done"
},
{
"id": "g139",
"title": "提示气泡支持左右方位",
"motivation": "tooltip 只有上下两向：竖排工具栏、贴右边的内容只能硬翻，left/right 全靠调用方自己补样式；position.ts 的 flip 也只认上下",
"acceptance": "position 新增 flipSide（四向判定，水平按宽度算左右空间），tooltip placement 支持 left/right 并复用自动翻转；CSS 四向定位 + 出场位移分离；文档 props/steps 与演示同步；npm run check 全绿",
"notes": "自补：既有组件可用性细节",
"status": "open"
}
]
}
.ua/index.json
+5 -4
View File
@@ -1,6 +1,6 @@
{
"$schema": "ui-arch-registry-index/0.1",
"generatedAt": "2026-10-26T07:31:10.742Z",
"generatedAt": "2026-10-26T07:32:30.909Z",
"repoRoot": ".",
"packages": [
{
@@ -1211,8 +1211,8 @@
},
{
"n": "placement",
"t": "'top' | 'bottom'",
"d": "气泡方位；缺省 top（触发器上方）",
"t": "'top' | 'bottom' | 'left' | 'right'",
"d": "气泡方位；缺省 top，出场时按视口剩余空间自动翻到对侧（水平方位按宽度判左右）",
"df": "top"
},
{
@@ -1233,7 +1233,8 @@
"把提示要挂在的元素作为第二个参数传入，返回的包裹节点替换原位置（气泡绝对定位，不占布局）",
"鼠标悬停或键盘聚焦后延迟 delay 毫秒出场，移出 / 失焦 / Esc 收起；空间不足时自动翻到另一侧",
"触摸屏没有 hover：手指按下即出场，抬手后停留 1.2 秒再收起，免得手指正挡着就消失",
"气泡设了 pointer-events: none，不会挡住下面的点击；aria-describedby 已关联，读屏能念出提示文案"
"气泡设了 pointer-events: none，不会挡住下面的点击；aria-describedby 已关联，读屏能念出提示文案",
"方位支持上下左右四向：贴边或工具栏竖排时用 left / right，出场时按该方向剩余空间自动翻到对侧"
]
},
{
apps/demo/main.ts
+3 -1
View File
@@ -464,13 +464,15 @@ const content = h(
section(
'sec-tooltip',
'悬浮提示',
'tooltip 包裹触发器：hover / 聚焦延迟 150ms 出场，移出、失焦或 Esc 收起，气泡不抢指针；视口一侧空间不足时气泡自动翻到另一侧。',
'tooltip 包裹触发器：hover / 聚焦延迟 150ms 出场，移出、失焦或 Esc 收起，气泡不抢指针；方位支持上下左右四向，视口该侧空间不足时自动翻到对侧。',
h(
'div',
{ class: 'row' },
tooltip({ content: '保存后立即生效' }, button({ label: '保存' })),
tooltip({ content: '该操作不可撤销', placement: 'bottom' }, button({ label: '删除', variant: 'danger' })),
tooltip({ content: '聚焦输入框同样会显示' }, textField({ placeholder: '聚焦我…' })),
tooltip({ content: '左侧方位：竖排工具栏常用', placement: 'left' }, button({ label: '左侧气泡', variant: 'ghost' })),
tooltip({ content: '右侧方位，贴右边时自动翻回左侧', placement: 'right' }, button({ label: '右侧气泡', variant: 'ghost' })),
),
),
section(
llms-full.txt
+3 -2
View File
@@ -1,6 +1,6 @@
# @ui-arch 组件库 Agent 文档（无图形版）
> 自动生成于 2026-10-26T07:31:10.742Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
> 自动生成于 2026-10-26T07:32:30.909Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
> 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
## 快速上手
@@ -588,7 +588,7 @@ toast.success('保存成功'); toast.error('网络请求失败', 5000)
参数：
- content（必填）：string —— 提示文案（纯文本）
- placement（默认 top）：'top' | 'bottom' —— 气泡方位；缺省 top（触发器上方）
- placement（默认 top）：'top' | 'bottom' | 'left' | 'right' —— 气泡方位；缺省 top，出场时按视口剩余空间自动翻到对侧（水平方位按宽度判左右）
- delay（默认 150）：number —— 出场延迟毫秒；缺省 150，传 0 立即显示
- trigger（必填）：HTMLElement —— 第二个参数：被包裹的触发器元素（按钮 / 输入框等任意 DOM）
@@ -604,6 +604,7 @@ tooltip({ content: '保存后立即生效' }, button({ label: '保存', onClick:
2. 鼠标悬停或键盘聚焦后延迟 delay 毫秒出场，移出 / 失焦 / Esc 收起；空间不足时自动翻到另一侧
3. 触摸屏没有 hover：手指按下即出场，抬手后停留 1.2 秒再收起，免得手指正挡着就消失
4. 气泡设了 pointer-events: none，不会挡住下面的点击；aria-describedby 已关联，读屏能念出提示文案
5. 方位支持上下左右四向：贴边或工具栏竖排时用 left / right，出场时按该方向剩余空间自动翻到对侧
现场演示：apps/docs/demo.html#sec-tooltip
packages/skin/ui/src/position.ts
+13
View File
@@ -9,3 +9,16 @@ export function flip(trigger: HTMLElement, panel: HTMLElement, preferred: 'top'
if (preferred === 'top') return up >= h + GAP || up >= down ? 'top' : 'bottom'; // 首选上方：放得下、或不比下方更局促就保持
return down >= h + GAP || down >= up ? 'bottom' : 'top'; // 首选下方：对称判定
}
/*** 浮层方位判定（四向）：水平方向按宽度判左右空间，垂直方向复用 flip 的上下一套逻辑 ***/
export function flipSide(trigger: HTMLElement, panel: HTMLElement, preferred: 'top' | 'bottom' | 'left' | 'right'): 'top' | 'bottom' | 'left' | 'right' {
const GAP = 8; // 与样式表预留的间距一致
const MIN = 24; // 兜底：面板尚未量出宽度时按最小可读宽度估算
if (preferred === 'top' || preferred === 'bottom') return flip(trigger, panel, preferred); // 垂直交回原判定
const t = trigger.getBoundingClientRect();
const w = panel.offsetWidth || MIN;
const left = t.left; // 触发器左侧可用空间
const right = window.innerWidth - t.right; // 触发器右侧可用空间
if (preferred === 'left') return left >= w + GAP || left >= right ? 'left' : 'right'; // 对称判定
return right >= w + GAP || right >= left ? 'right' : 'left';
}
packages/skin/ui/src/tooltip.ts
+3 -3
View File
@@ -1,6 +1,6 @@
import { effect, h, signal } from '@ui-arch/frame';
import type { TooltipProps } from './types.js';
import { flip } from './position.js';
import { flipSide } from './position.js';
let seq = 0; // 全局自增序号：保证每个气泡 id 唯一，供 aria-describedby 关联
@@ -8,7 +8,7 @@ let seq = 0; // 全局自增序号：保证每个气泡 id 唯一，供 aria-des
export function tooltip(props: TooltipProps, trigger: HTMLElement): HTMLElement {
// —— 状态集中声明 ——
const open = signal(false); // 气泡显隐
const place = signal(props.placement ?? 'top'); // 实际生效方位：出场时按视口空间自动翻转
const place = signal<'top' | 'bottom' | 'left' | 'right'>(props.placement ?? 'top'); // 实际生效方位：出场时按视口空间自动翻转
const id = `ua-tip-${++seq}`; // 气泡唯一 id
const delay = props.delay ?? 150; // 出场延迟毫秒；<=0 视为立即显示
let timer: number | null = null; // 出场延迟计时器句柄
@@ -64,7 +64,7 @@ export function tooltip(props: TooltipProps, trigger: HTMLElement): HTMLElement
// —— 触摸屏：没有 hover，改点按。按下即出（不等 150ms），抬手留 1.2s 再收，否则手指正挡着气泡就没了 ——
root.addEventListener('pointerdown', (e: PointerEvent) => { if (e.pointerType === 'touch') show(); });
root.addEventListener('pointerup', (e: PointerEvent) => { if (e.pointerType === 'touch') hideLater(); });
effect(() => { if (open()) place(flip(trigger, bubble, props.placement ?? 'top')); }); // 每次出场重算方位：空间不足自动翻转
effect(() => { if (open()) place(flipSide(trigger, bubble, props.placement ?? 'top')); }); // 每次出场重算方位：空间不足自动翻转
root.addEventListener('keydown', (e: KeyboardEvent) => {
if (e.key === 'Escape') { e.stopPropagation(); hide(); } // Esc 立即收起且不影响外层弹层
});
packages/skin/ui/src/types.ts
+1 -1
View File
@@ -4,7 +4,7 @@ import type { Signal } from '@ui-arch/frame';
/*** 悬浮提示入参 ***/
export interface TooltipProps {
content: string; // 提示文案（纯文本）
placement?: 'top' | 'bottom'; // 气泡方位；缺省 top（触发器上方）
placement?: 'top' | 'bottom' | 'left' | 'right'; // 气泡方位；缺省 top，空间不足自动翻到对侧
delay?: number; // 出场延迟毫秒；缺省 150，传 0 立即显示
}
packages/skin/ui/ua.manifest.json
+4 -3
View File
@@ -1082,8 +1082,8 @@
},
{
"n": "placement",
"t": "'top' | 'bottom'",
"d": "气泡方位；缺省 top（触发器上方）",
"t": "'top' | 'bottom' | 'left' | 'right'",
"d": "气泡方位；缺省 top，出场时按视口剩余空间自动翻到对侧（水平方位按宽度判左右）",
"df": "top"
},
{
@@ -1104,7 +1104,8 @@
"把提示要挂在的元素作为第二个参数传入，返回的包裹节点替换原位置（气泡绝对定位，不占布局）",
"鼠标悬停或键盘聚焦后延迟 delay 毫秒出场，移出 / 失焦 / Esc 收起；空间不足时自动翻到另一侧",
"触摸屏没有 hover：手指按下即出场，抬手后停留 1.2 秒再收起，免得手指正挡着就消失",
"气泡设了 pointer-events: none，不会挡住下面的点击；aria-describedby 已关联，读屏能念出提示文案"
"气泡设了 pointer-events: none，不会挡住下面的点击；aria-describedby 已关联，读屏能念出提示文案",
"方位支持上下左右四向：贴边或工具栏竖排时用 left / right，出场时按该方向剩余空间自动翻到对侧"
]
},
{
packages/skin/ui/ui.css
+22 -4
View File
@@ -1790,7 +1790,6 @@ button.ua-step-dot:hover {
}
.ua-tip {
position: absolute;
left: 50%;
z-index: 30;
max-width: 220px;
padding: var(--ua-space-1) var(--ua-space-2);
@@ -1804,16 +1803,35 @@ button.ua-step-dot:hover {
transition: opacity 0.16s ease-out, transform 0.16s ease-out;
}
.ua-tip-top {
left: 50%;
bottom: calc(100% + 6px);
transform: translateX(-50%) translateY(3px);
transform: translate(-50%, 3px);
}
.ua-tip-bottom {
left: 50%;
top: calc(100% + 6px);
transform: translateX(-50%) translateY(-3px);
transform: translate(-50%, -3px);
}
.ua-tip-left {
right: calc(100% + 6px);
top: 50%;
transform: translate(3px, -50%);
}
.ua-tip-right {
left: calc(100% + 6px);
top: 50%;
transform: translate(-3px, -50%);
}
.ua-tip.ua-open {
opacity: 1;
transform: translateX(-50%) translateY(0);
}
.ua-tip-top.ua-open,
.ua-tip-bottom.ua-open {
transform: translate(-50%, 0);
}
.ua-tip-left.ua-open,
.ua-tip-right.ua-open {
transform: translate(0, -50%);
}
/* —— 通用禁用态：置灰 + 禁用光标 —— */