iter(g144): 新增头像组组件 avatarGroup
This commit is contained in:
HIsheR
@@ -1508,6 +1508,14 @@
|
||||
"acceptance": "tabs 新增 extra：与页签同一行、共用一条分隔线，不传时 DOM 结构不变（纯增量）；文档 props/steps 与演示同步；npm run check 全绿",
|
||||
"notes": "自补：既有组件可用性细节",
|
||||
"status": "done"
|
||||
},
|
||||
{
|
||||
"id": "g144",
|
||||
"title": "新增头像组组件 avatarGroup",
|
||||
"motivation": "协作列表 / 评论头部要展示参与人，并排 avatar 占横向空间且没有「还有 N 人」的表达；调用方各自用 margin 叠放，切口与层级都不一致",
|
||||
"acceptance": "avatarGroup 支持 items（name/src/variant）、max 折叠为 +N、size 与 avatar 对齐；整组 title 列全部姓名、+N 有可访问名；样式只消费 --ua-*；文档与演示同步；npm run check 全绿",
|
||||
"notes": "自补：组件补充方向",
|
||||
"status": "open"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
+36
-2
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"$schema": "ui-arch-registry-index/0.1",
|
||||
"generatedAt": "2026-10-26T07:38:33.907Z",
|
||||
"generatedAt": "2026-10-26T07:39:42.119Z",
|
||||
"repoRoot": ".",
|
||||
"packages": [
|
||||
{
|
||||
@@ -209,7 +209,8 @@
|
||||
"floatButton(props)：悬浮操作按钮，固定停靠左下 / 右下角，label 缺省为纯图标圆形，badge 走角标，tooltip 兼作 aria-label",
|
||||
"mentions(props)：@提及输入，textarea 内键入 @ 弹候选（名字 / 关键词过滤），↑↓ 环形移动、Enter/Tab 选中、Esc 只收本层，选中按光标替换并写回 value",
|
||||
"treeSelect(props)：树形选择，按钮触发弹层并复用 tree（搜索 / 多选 / 级联），单选选中即收起、多选保持展开，Esc 与点外收起",
|
||||
"link(props)：链接，站内跳转与站外跳转统一入口，external 自动补 ↗ 与 rel=noopener noreferrer 并给读屏播报"
|
||||
"link(props)：链接，站内跳转与站外跳转统一入口，external 自动补 ↗ 与 rel=noopener noreferrer 并给读屏播报",
|
||||
"avatarGroup(props)：头像组，横向叠放并在超出 max 时折叠成 +N，整组 title 列出全部姓名"
|
||||
],
|
||||
"keyTypes": [
|
||||
"ButtonProps",
|
||||
@@ -3492,6 +3493,39 @@
|
||||
"禁用态只是去掉 href 并保持 aria-disabled，不做视觉上的「像普通文字」处理——需要完全不可聚焦请在外层控制渲染",
|
||||
"纯样式的「看起来像链接」用 typography({ underline: true })，不要为了样式引入带 href 的 a 标签"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "avatarGroup",
|
||||
"title": "头像组 AvatarGroup",
|
||||
"demo": "sec-avatar",
|
||||
"props": [
|
||||
{
|
||||
"n": "items",
|
||||
"t": "AvatarItem[]",
|
||||
"r": 1,
|
||||
"d": "成员列表：每项含 name（姓名）、src（图片地址）、variant（首字底色语义档）"
|
||||
},
|
||||
{
|
||||
"n": "max",
|
||||
"t": "number",
|
||||
"df": "4",
|
||||
"d": "最多展示几个，超出折叠成 +N（至少展示 1 个）"
|
||||
},
|
||||
{
|
||||
"n": "size",
|
||||
"t": "number",
|
||||
"df": "32",
|
||||
"d": "头像直径像素，与 avatar 的 size 同义"
|
||||
}
|
||||
],
|
||||
"example": "avatarGroup({ items: [{ name: '张三' }, { name: '李四', variant: 'success' }, { name: '王五' }], max: 4 })",
|
||||
"steps": [
|
||||
"协作列表 / 评论头部展示参与人用它，比并排 avatar 省横向空间：叠放用负边距 + 底色描边切出入口",
|
||||
"成员多时设 max：前 max 个照常显示，其余折叠成一个 +N，悬停任意头像都能看到全部姓名",
|
||||
"只传 name 即首字占位，有图片就传 src；底色语义档用 variant（default / success / warning / danger）",
|
||||
"整组是展示型元素：要有点击行为就在外面包 button 或 link，不要给单个头像加交互",
|
||||
"size 与单个 avatar 一致，混排时把并排 avatar 与 avatarGroup 传同一个 size，视觉才对得上"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
@@ -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）：66 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌
|
||||
- `packages/skin/ui`（@ui-arch/ui）：67 个 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
@@ -34,7 +34,7 @@ ui-arch-mvp/
|
||||
│ │ ├── table-core/ # 表格状态内核
|
||||
│ │ └── frame/ # 信号 + hyperscript 微框架
|
||||
│ ├── skin/ # 皮肤层（DOM 组件，可发布）
|
||||
│ │ └── ui/ # 66 个组件 + ui.css
|
||||
│ │ └── ui/ # 67 个组件 + ui.css
|
||||
│ ├── design/ # 资产层（可发布）
|
||||
│ │ └── tokens/ # --ua-* 设计令牌
|
||||
│ └── tools/ # 工程层（private，不发布）
|
||||
|
||||
@@ -12,13 +12,13 @@ npm run docs # 生成人类文档站 apps/docs/index.html + Agent 全
|
||||
npm run changelog # 依据 git 提交史重写 CHANGELOG.md（发版前跑；changelog:check 可查漂移）
|
||||
```
|
||||
|
||||
## 组件（共 66 个）
|
||||
## 组件（共 67 个）
|
||||
|
||||
<!-- ua:components -->
|
||||
accordion · affix · alert · anchor · autoComplete · avatar · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · colorPicker · dataTable · datePicker · descriptions · divider · drawer · empty · floatButton · form · grid · image · inputNumber · link · list · menu · modal · mentions · multiSelect · notification · pagination · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · watermark
|
||||
accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · colorPicker · dataTable · datePicker · descriptions · divider · drawer · empty · floatButton · form · grid · image · inputNumber · link · list · menu · modal · mentions · multiSelect · notification · pagination · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · watermark
|
||||
<!-- /ua:components -->
|
||||
|
||||
分组：表单（button / textField / inputNumber / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic）、浮层（tooltip / popover / popconfirm / modal / drawer / menu）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor）、数据展示（dataTable / descriptions / card / list / timeline / tag / avatar / image / carousel / calendar / typography）、其他（floatButton / grid / link / space / divider / splitter / backTop / affix / tour / watermark）。
|
||||
分组：表单（button / textField / inputNumber / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic）、浮层（tooltip / popover / popconfirm / modal / drawer / menu）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor）、数据展示（dataTable / descriptions / card / list / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography）、其他（floatButton / grid / link / space / divider / splitter / backTop / affix / tour / watermark）。
|
||||
|
||||
## 可访问性约定
|
||||
|
||||
@@ -32,7 +32,7 @@ accordion · affix · alert · anchor · autoComplete · avatar · backTop · ba
|
||||
|---|---|
|
||||
| `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：66 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
|
||||
| `packages/skin/ui` | @ui-arch/ui：67 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
|
||||
| `packages/design/tokens` | @ui-arch/tokens：设计令牌（暗色只换值不换名） |
|
||||
| `packages/tools/cli` | @ui-arch/cli：`ua` 命令行与 stdio MCP server |
|
||||
| `apps/demo` | 交互演示（esbuild 打包成单文件） |
|
||||
|
||||
@@ -13,6 +13,7 @@ import {
|
||||
alert,
|
||||
anchor,
|
||||
autoComplete,
|
||||
avatarGroup,
|
||||
avatar,
|
||||
backTop,
|
||||
badge,
|
||||
@@ -408,6 +409,7 @@ const content = h(
|
||||
avatar({ name: '张三' }),
|
||||
avatar({ name: 'Alice', size: 40, variant: 'success' }),
|
||||
avatar({ name: 'Bob', size: 24, variant: 'warning' }),
|
||||
avatarGroup({ items: [{ name: '张三' }, { name: '李四', variant: 'success' }, { name: '王五', variant: 'warning' }, { name: '赵六' }, { name: '钱七' }, { name: '孙八' }], max: 4 }),
|
||||
avatar({ name: '李四', size: 36, variant: 'danger' }),
|
||||
),
|
||||
),
|
||||
|
||||
+26
-1
@@ -1,6 +1,6 @@
|
||||
# @ui-arch 组件库 Agent 文档（无图形版）
|
||||
|
||||
> 自动生成于 2026-10-26T07:38:33.907Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
|
||||
> 自动生成于 2026-10-26T07:39:42.119Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
|
||||
> 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
|
||||
|
||||
## 快速上手
|
||||
@@ -1861,6 +1861,30 @@ link({ href: '/docs', label: '查看文档' }); link({ href: 'https://example.co
|
||||
|
||||
现场演示：apps/docs/demo.html#sec-link
|
||||
|
||||
### avatarGroup — 头像组 AvatarGroup
|
||||
|
||||
参数：
|
||||
|
||||
- items（必填）：AvatarItem[] —— 成员列表：每项含 name（姓名）、src（图片地址）、variant（首字底色语义档）
|
||||
- max（默认 4）：number —— 最多展示几个，超出折叠成 +N（至少展示 1 个）
|
||||
- size（默认 32）：number —— 头像直径像素，与 avatar 的 size 同义
|
||||
|
||||
示例：
|
||||
|
||||
```
|
||||
avatarGroup({ items: [{ name: '张三' }, { name: '李四', variant: 'success' }, { name: '王五' }], max: 4 })
|
||||
```
|
||||
|
||||
手把手：
|
||||
|
||||
1. 协作列表 / 评论头部展示参与人用它，比并排 avatar 省横向空间：叠放用负边距 + 底色描边切出入口
|
||||
2. 成员多时设 max：前 max 个照常显示，其余折叠成一个 +N，悬停任意头像都能看到全部姓名
|
||||
3. 只传 name 即首字占位，有图片就传 src；底色语义档用 variant（default / success / warning / danger）
|
||||
4. 整组是展示型元素：要有点击行为就在外面包 button 或 link，不要给单个头像加交互
|
||||
5. size 与单个 avatar 一致，混排时把并排 avatar 与 avatarGroup 传同一个 size，视觉才对得上
|
||||
|
||||
现场演示：apps/docs/demo.html#sec-avatar
|
||||
|
||||
API 速览：
|
||||
|
||||
- button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用；type 缺省 button（表单内不隐式提交）
|
||||
@@ -1931,6 +1955,7 @@ API 速览：
|
||||
- mentions(props)：@提及输入，textarea 内键入 @ 弹候选（名字 / 关键词过滤），↑↓ 环形移动、Enter/Tab 选中、Esc 只收本层，选中按光标替换并写回 value
|
||||
- treeSelect(props)：树形选择，按钮触发弹层并复用 tree（搜索 / 多选 / 级联），单选选中即收起、多选保持展开，Esc 与点外收起
|
||||
- link(props)：链接，站内跳转与站外跳转统一入口，external 自动补 ↗ 与 rel=noopener noreferrer 并给读屏播报
|
||||
- avatarGroup(props)：头像组，横向叠放并在超出 max 时折叠成 +N，整组 title 列出全部姓名
|
||||
|
||||
一行用法：
|
||||
|
||||
|
||||
@@ -115,6 +115,7 @@
|
||||
- mentions(props)：@提及输入，textarea 内键入 @ 弹候选（名字 / 关键词过滤），↑↓ 环形移动、Enter/Tab 选中、Esc 只收本层，选中按光标替换并写回 value
|
||||
- treeSelect(props)：树形选择，按钮触发弹层并复用 tree（搜索 / 多选 / 级联），单选选中即收起、多选保持展开，Esc 与点外收起
|
||||
- link(props)：链接，站内跳转与站外跳转统一入口，external 自动补 ↗ 与 rel=noopener noreferrer 并给读屏播报
|
||||
- avatarGroup(props)：头像组，横向叠放并在超出 max 时折叠成 +N，整组 title 列出全部姓名
|
||||
- 用法: `const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')`
|
||||
- 约定: 皮肤不持有业务状态，一律委托 headless 内核或调用方信号
|
||||
- 约定: 表单类组件统一约定：*Props.value/checked/active 为 Signal 双向绑定，onChange/onInput 为回调
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
import { h } from '@ui-arch/frame';
|
||||
import { avatar } from './avatar.js';
|
||||
import type { AvatarGroupProps } from './types.js';
|
||||
|
||||
/*** 头像组：横向叠放（负边距 + 底色描边切口），超出 max 折叠成 +N，整组 title 列出全部姓名 ***/
|
||||
export function avatarGroup(props: AvatarGroupProps): HTMLElement {
|
||||
const size = props.size ?? 32; // 直径与单个 avatar 一致
|
||||
const max = Math.max(props.max ?? 4, 1); // 至少留一个位置，避免传 0 后只剩 +N
|
||||
const shown = props.items.slice(0, max); // 展示前 max 个
|
||||
const rest = props.items.length - shown.length;
|
||||
const group = h('div', {
|
||||
class: 'ua-avatar-group',
|
||||
title: props.items.map((item) => item.name).join('、'), // 折叠后仍能看到全部成员
|
||||
}, ...shown.map((item) => avatar({ name: item.name, src: item.src, variant: item.variant, size })));
|
||||
if (rest <= 0) return group; // 卫语句：没超上限就不渲染 +N
|
||||
group.append(h('span', {
|
||||
class: 'ua-avatar ua-avatar-more',
|
||||
style: `width:${size}px;height:${size}px;font-size:${Math.round(size * 0.38)}px`,
|
||||
'aria-label': `还有 ${rest} 人`, // 纯文本 +N 读屏会念成「加 3」，补可访问名
|
||||
}, `+${rest}`));
|
||||
return group;
|
||||
}
|
||||
@@ -66,3 +66,4 @@ export { floatButton } from './floatButton.js';
|
||||
export { mentions } from './mentions.js';
|
||||
export { treeSelect } from './treeSelect.js';
|
||||
export { link } from './link.js';
|
||||
export { avatarGroup } from './avatarGroup.js';
|
||||
|
||||
@@ -827,4 +827,18 @@ export interface LinkProps {
|
||||
onClick?: (e: Event) => void; // 点击回调（禁用时不触发）
|
||||
}
|
||||
|
||||
/*** 头像组成员项 ***/
|
||||
export interface AvatarItem {
|
||||
name: string; // 姓名：占位首字与悬停标题都用它
|
||||
src?: string; // 头像图片地址；缺省首字占位
|
||||
variant?: 'default' | 'success' | 'warning' | 'danger'; // 首字底色语义档；缺省 default
|
||||
}
|
||||
|
||||
/*** 头像组入参 ***/
|
||||
export interface AvatarGroupProps {
|
||||
items: AvatarItem[]; // 成员列表，按显示顺序排列
|
||||
max?: number; // 最多展示几个，超出折叠成 +N；缺省 4
|
||||
size?: number; // 头像直径像素；缺省 32
|
||||
}
|
||||
|
||||
export type { ColumnDef, RowKey }; // 再导出常用内核类型，方便调用方
|
||||
|
||||
@@ -80,7 +80,8 @@
|
||||
"floatButton(props)：悬浮操作按钮，固定停靠左下 / 右下角，label 缺省为纯图标圆形，badge 走角标，tooltip 兼作 aria-label",
|
||||
"mentions(props)：@提及输入，textarea 内键入 @ 弹候选（名字 / 关键词过滤），↑↓ 环形移动、Enter/Tab 选中、Esc 只收本层，选中按光标替换并写回 value",
|
||||
"treeSelect(props)：树形选择，按钮触发弹层并复用 tree（搜索 / 多选 / 级联），单选选中即收起、多选保持展开，Esc 与点外收起",
|
||||
"link(props)：链接，站内跳转与站外跳转统一入口，external 自动补 ↗ 与 rel=noopener noreferrer 并给读屏播报"
|
||||
"link(props)：链接，站内跳转与站外跳转统一入口，external 自动补 ↗ 与 rel=noopener noreferrer 并给读屏播报",
|
||||
"avatarGroup(props)：头像组，横向叠放并在超出 max 时折叠成 +N，整组 title 列出全部姓名"
|
||||
],
|
||||
"keyTypes": [
|
||||
"ButtonProps",
|
||||
@@ -3363,6 +3364,39 @@
|
||||
"禁用态只是去掉 href 并保持 aria-disabled，不做视觉上的「像普通文字」处理——需要完全不可聚焦请在外层控制渲染",
|
||||
"纯样式的「看起来像链接」用 typography({ underline: true })，不要为了样式引入带 href 的 a 标签"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "avatarGroup",
|
||||
"title": "头像组 AvatarGroup",
|
||||
"demo": "sec-avatar",
|
||||
"props": [
|
||||
{
|
||||
"n": "items",
|
||||
"t": "AvatarItem[]",
|
||||
"r": 1,
|
||||
"d": "成员列表：每项含 name（姓名）、src（图片地址）、variant（首字底色语义档）"
|
||||
},
|
||||
{
|
||||
"n": "max",
|
||||
"t": "number",
|
||||
"df": "4",
|
||||
"d": "最多展示几个，超出折叠成 +N（至少展示 1 个）"
|
||||
},
|
||||
{
|
||||
"n": "size",
|
||||
"t": "number",
|
||||
"df": "32",
|
||||
"d": "头像直径像素，与 avatar 的 size 同义"
|
||||
}
|
||||
],
|
||||
"example": "avatarGroup({ items: [{ name: '张三' }, { name: '李四', variant: 'success' }, { name: '王五' }], max: 4 })",
|
||||
"steps": [
|
||||
"协作列表 / 评论头部展示参与人用它，比并排 avatar 省横向空间：叠放用负边距 + 底色描边切出入口",
|
||||
"成员多时设 max：前 max 个照常显示，其余折叠成一个 +N，悬停任意头像都能看到全部姓名",
|
||||
"只传 name 即首字占位，有图片就传 src；底色语义档用 variant（default / success / warning / danger）",
|
||||
"整组是展示型元素：要有点击行为就在外面包 button 或 link，不要给单个头像加交互",
|
||||
"size 与单个 avatar 一致，混排时把并排 avatar 与 avatarGroup 传同一个 size，视觉才对得上"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -4439,3 +4439,25 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); }
|
||||
gap: var(--ua-space-2);
|
||||
padding-bottom: var(--ua-space-1);
|
||||
}
|
||||
|
||||
/* —— 头像组：负边距叠放，底色描边切出入口 —— */
|
||||
.ua-avatar-group {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
}
|
||||
.ua-avatar-group > .ua-avatar {
|
||||
margin-left: calc(-1 * var(--ua-space-2));
|
||||
box-shadow: 0 0 0 2px var(--ua-color-bg);
|
||||
}
|
||||
.ua-avatar-group > .ua-avatar:first-child {
|
||||
margin-left: 0;
|
||||
}
|
||||
.ua-avatar-group > .ua-avatar:hover {
|
||||
position: relative;
|
||||
z-index: 1; /* 悬停的那个压在最上面，不被后一个盖住 */
|
||||
}
|
||||
.ua-avatar-more {
|
||||
background: color-mix(in srgb, var(--ua-color-text-muted) 18%, transparent);
|
||||
color: var(--ua-color-text);
|
||||
font-weight: 500;
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user