From 08ceb8f127f800a204783c2e52072e6c90730b75 Mon Sep 17 00:00:00 2001 From: HIsheR Date: Mon, 26 Oct 2026 15:32:47 +0800 Subject: [PATCH] =?UTF-8?q?iter(g139):=20=E6=8F=90=E7=A4=BA=E6=B0=94?= =?UTF-8?q?=E6=B3=A1=E6=94=AF=E6=8C=81=E5=B7=A6=E5=8F=B3=E6=96=B9=E4=BD=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .ua/backlog.json | 8 ++++++++ .ua/index.json | 9 +++++---- apps/demo/main.ts | 4 +++- llms-full.txt | 5 +++-- packages/skin/ui/src/position.ts | 13 +++++++++++++ packages/skin/ui/src/tooltip.ts | 6 +++--- packages/skin/ui/src/types.ts | 2 +- packages/skin/ui/ua.manifest.json | 7 ++++--- packages/skin/ui/ui.css | 26 ++++++++++++++++++++++---- 9 files changed, 62 insertions(+), 18 deletions(-) diff --git a/.ua/backlog.json b/.ua/backlog.json index 11ccc01..e7e808e 100644 --- a/.ua/backlog.json +++ b/.ua/backlog.json @@ -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" } ] } diff --git a/.ua/index.json b/.ua/index.json index 5543757..5674175 100644 --- a/.ua/index.json +++ b/.ua/index.json @@ -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，出场时按该方向剩余空间自动翻到对侧" ] }, { diff --git a/apps/demo/main.ts b/apps/demo/main.ts index 1a55e66..c39b155 100644 --- a/apps/demo/main.ts +++ b/apps/demo/main.ts @@ -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( diff --git a/llms-full.txt b/llms-full.txt index ab9a7bc..ebe30bf 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -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 diff --git a/packages/skin/ui/src/position.ts b/packages/skin/ui/src/position.ts index 22e08ac..3f3f0f4 100644 --- a/packages/skin/ui/src/position.ts +++ b/packages/skin/ui/src/position.ts @@ -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'; +} diff --git a/packages/skin/ui/src/tooltip.ts b/packages/skin/ui/src/tooltip.ts index d24f409..5a3617f 100644 --- a/packages/skin/ui/src/tooltip.ts +++ b/packages/skin/ui/src/tooltip.ts @@ -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 立即收起且不影响外层弹层 }); diff --git a/packages/skin/ui/src/types.ts b/packages/skin/ui/src/types.ts index 514a7b9..862a417 100644 --- a/packages/skin/ui/src/types.ts +++ b/packages/skin/ui/src/types.ts @@ -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 立即显示 } diff --git a/packages/skin/ui/ua.manifest.json b/packages/skin/ui/ua.manifest.json index f3bb3bb..edeb1a8 100644 --- a/packages/skin/ui/ua.manifest.json +++ b/packages/skin/ui/ua.manifest.json @@ -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，出场时按该方向剩余空间自动翻到对侧" ] }, { diff --git a/packages/skin/ui/ui.css b/packages/skin/ui/ui.css index c908d0a..4a77ba6 100644 --- a/packages/skin/ui/ui.css +++ b/packages/skin/ui/ui.css @@ -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%); } /* —— 通用禁用态：置灰 + 禁用光标 —— */