u
This commit is contained in:
oneao committed
1 parent
e99a9fb274
commit
0be0b0767a
788 files changed
+112023
-14941
No files matched your search
@@ -0,0 +1,128 @@
|
||||
---
|
||||
title: Message 轻提示
|
||||
description: 命令式轻提示：info / success / warning / error
|
||||
---
|
||||
|
||||
# Message 轻提示
|
||||
|
||||
`Message` 用于给用户一个**不打断操作**的反馈：保存成功、校验失败、复制完成。
|
||||
|
||||
## 何时使用
|
||||
|
||||
- 操作结果反馈（成功 / 失败 / 警告）时；
|
||||
- 需要用户**确认**或做选择时，用 [Modal.confirm](/ui/overlay/modal)；
|
||||
- 需要承载标题 + 描述、停留更久时，用 [Notification](/ui/feedback/notification)。
|
||||
|
||||
## 基础用法
|
||||
|
||||
`G3Message` 是一个对象，直接调用即可——它会自己挂载容器到 `body`，无需在模板里写组件。
|
||||
|
||||
<demo vue="message/basic.vue" />
|
||||
|
||||
```ts
|
||||
import { G3Message } from '@g3soft/ui'
|
||||
|
||||
G3Message.info('普通提示')
|
||||
G3Message.success('保存成功')
|
||||
G3Message.warning('磁盘空间不足')
|
||||
G3Message.error('保存失败，请重试')
|
||||
```
|
||||
|
||||
## 选项与句柄
|
||||
|
||||
第二个参数是选项对象；调用返回 `{ close }` 句柄，可以提前关闭。
|
||||
|
||||
<demo vue="message/options.vue" />
|
||||
|
||||
| 选项 | 类型 | 默认值 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `duration` | `number` | `3000` | 自动关闭时长（ms）。`<= 0` 表示不自动关闭 |
|
||||
| `closable` | `boolean` | `false` | 是否显示关闭按钮 |
|
||||
| `placement` | `MessagePlacement` | 全局配置 | 显示方位（9 个） |
|
||||
|
||||
## 方位与全局配置
|
||||
|
||||
`placement` 可逐条指定；`G3Message.config()` 设置全局默认，只影响之后的调用。
|
||||
|
||||
<demo vue="message/placement.vue" />
|
||||
|
||||
```ts
|
||||
G3Message.config({ placement: 'top-right', duration: 2000 })
|
||||
```
|
||||
|
||||
## 使用注意
|
||||
|
||||
- `G3Message` 在**组件树之外**创建实例：命名空间、语言包、初始方位来自全局配置（`G3UI.config()` / `ConfigProvider` 无法 inject 到它），因此多主题场景请在 `G3UI.config({ namespace })` 里统一；
|
||||
- 消息是「短反馈」，不要放按钮、链接等需要交互的内容——那属于 Notification 或 Modal；
|
||||
- 同一时刻的消息默认堆叠在同一个方位，超过屏幕高度时请自行控制数量（例如 `duration` 缩短）。
|
||||
|
||||
## API
|
||||
|
||||
### 方法
|
||||
|
||||
| 方法 | 签名 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `open` | `(options: MessageOptions) => MessageHandle` | 通用入口 |
|
||||
| `info` | `(content: string, options?: ShortcutOptions) => MessageHandle` | 信息提示 |
|
||||
| `success` | `(content: string, options?: ShortcutOptions) => MessageHandle` | 成功 |
|
||||
| `warning` | `(content: string, options?: ShortcutOptions) => MessageHandle` | 警告 |
|
||||
| `error` | `(content: string, options?: ShortcutOptions) => MessageHandle` | 错误 |
|
||||
| `close` | `(id: string) => void` | 按 id 关闭一条 |
|
||||
| `config` | `(config: MessageConfig) => void` | 设置全局默认（`placement` / `duration`） |
|
||||
| `destroy` | `() => void` | 清空全部消息并卸载容器（登出 / 切租户时用） |
|
||||
| `count` | `() => number` | 当前存活条数（调试用） |
|
||||
|
||||
`ShortcutOptions` = `Omit<MessageOptions, 'content' | 'type'>`，即 `{ duration?, closable?, placement? }`。
|
||||
|
||||
### 类型定义
|
||||
|
||||
```ts
|
||||
export type MessageType = 'info' | 'success' | 'warning' | 'error'
|
||||
|
||||
export type MessagePlacement =
|
||||
| 'top-left' | 'top-center' | 'top-right'
|
||||
| 'center-left' | 'center' | 'center-right'
|
||||
| 'bottom-left' | 'bottom-center' | 'bottom-right'
|
||||
|
||||
export interface MessageOptions {
|
||||
content: string
|
||||
type?: MessageType
|
||||
duration?: number
|
||||
closable?: boolean
|
||||
placement?: MessagePlacement
|
||||
}
|
||||
|
||||
export interface MessageHandle {
|
||||
close: () => void
|
||||
}
|
||||
|
||||
export interface MessageConfig {
|
||||
placement?: MessagePlacement
|
||||
duration?: number
|
||||
}
|
||||
```
|
||||
|
||||
### 组件形式（G3MessageItem / G3MessageContainer）
|
||||
|
||||
一般不需要直接使用；如果要把消息渲染进自己的容器（例如某个面板内部），可以组合它们：
|
||||
|
||||
| 组件 | Props | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `G3MessageItem` | `id` / `type` / `content` / `duration` / `closable` | 单条消息，`close` 事件表示「该关闭了」（自动计时到期或点了关闭按钮） |
|
||||
| `G3MessageContainer` | `zIndex` | 9 个方位的容器，读取全局 `messageState` 渲染 |
|
||||
|
||||
### 样式变量
|
||||
|
||||
| 变量 | 默认值 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `--g3-feedback-offset` | `24px` | 距视口边缘的距离 |
|
||||
| `--g3-feedback-icon-size` | `18px` | 类型图标尺寸 |
|
||||
| `--g3-shadow-popup` | 浮层阴影 | 消息卡片阴影 |
|
||||
|
||||
## 实现说明
|
||||
|
||||
- **组件树外挂载**：首次调用时创建单例容器（`createVNode` + `render` 挂到 `body`），之后复用；`destroy()` 才会卸载并回收 z-index；
|
||||
- 全局状态放在 `messageState`（`reactive`），容器读它、管理器写它，因此消息增删是响应式的；容器对 9 个方位各渲染一个常驻的 `TransitionGroup`，**只让消息项进出**，这是进出场动画能稳定触发的前提；
|
||||
- 层级取 z-index 注册表的 `feedback` 档（高于 modal / popup），保证弹窗里的操作提示也能看到；容器本身 `pointer-events: none`，只有消息卡片可交互，避免挡住页面；
|
||||
- `duration` 计时在消息项内部完成（`onMounted` 启动、卸载时清除），因此手动关闭与自动关闭不会互相干扰；
|
||||
- 文案来自语言包（关闭按钮的 `aria-label` 等），可用 `ConfigProvider.locale` / `G3UI.config({ locale })` 切换。
|
||||
@@ -0,0 +1,110 @@
|
||||
---
|
||||
title: Notification 通知提醒
|
||||
description: 命令式通知：带标题与描述，适合承载需要阅读的信息
|
||||
---
|
||||
|
||||
# Notification 通知提醒
|
||||
|
||||
`Notification` 与 [Message](/ui/feedback/message) 是同一套机制，但**承载更多信息**：有标题、有描述、默认停留更久（4500ms），适合「需要被读到」的内容。
|
||||
|
||||
## 何时使用
|
||||
|
||||
- 后台任务完成 / 失败，用户当前可能不在看那一块界面；
|
||||
- 需要标题 + 详细描述的信息（版本发布、审核结果、系统告警）；
|
||||
- 只是「一句话结果」时用 Message 更轻；需要用户做出选择时用 [Modal](/ui/overlay/modal)。
|
||||
|
||||
## 基础用法
|
||||
|
||||
<demo vue="notification/basic.vue" />
|
||||
|
||||
```ts
|
||||
import { G3Notification } from '@g3soft/ui'
|
||||
|
||||
G3Notification.success({ title: '发布成功', description: '版本 1.2.0 已上线' })
|
||||
G3Notification.error({ title: '构建失败', description: '单元测试未通过', duration: 0 })
|
||||
```
|
||||
|
||||
## 方位
|
||||
|
||||
通知只出现在四角（避免遮挡页面中央内容）；逐条可指定 `placement`，也可以用 `config()` 设全局默认。
|
||||
|
||||
<demo vue="notification/placement.vue" />
|
||||
|
||||
```ts
|
||||
G3Notification.config({ placement: 'bottom-right', duration: 6000 })
|
||||
```
|
||||
|
||||
## 关闭与清理
|
||||
|
||||
<demo vue="notification/close.vue" />
|
||||
|
||||
## 使用注意
|
||||
|
||||
- 通知是「异步结果」的表达，不要在用户操作的同一瞬间用它替代即时反馈——那种场景用 Message；
|
||||
- `duration: 0` 的通知必须带 `closable`（默认就是 `true`），否则用户无法关闭；
|
||||
- 登出、切换租户、路由跳转到登录页时建议调用 `G3Notification.destroy()`，避免残留旧上下文的通知。
|
||||
|
||||
## API
|
||||
|
||||
### 方法
|
||||
|
||||
| 方法 | 签名 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `open` | `(options: NotificationOptions) => NotificationHandle` | 通用入口 |
|
||||
| `info` | `(options: ShortcutOptions) => NotificationHandle` | 信息 |
|
||||
| `success` | `(options: ShortcutOptions) => NotificationHandle` | 成功 |
|
||||
| `warning` | `(options: ShortcutOptions) => NotificationHandle` | 警告 |
|
||||
| `error` | `(options: ShortcutOptions) => NotificationHandle` | 错误 |
|
||||
| `close` | `(id: string) => void` | 按 id 关闭一条 |
|
||||
| `config` | `(config: NotificationConfig) => void` | 设置全局默认（`placement` / `duration`） |
|
||||
| `destroy` | `() => void` | 清空全部通知并卸载容器 |
|
||||
| `count` | `() => number` | 当前存活条数（调试用） |
|
||||
|
||||
`ShortcutOptions` = `Omit<NotificationOptions, 'type'>`，即 `{ title?, description?, duration?, closable?, placement? }`。
|
||||
|
||||
### 类型定义
|
||||
|
||||
```ts
|
||||
export type NotificationType = 'info' | 'success' | 'warning' | 'error'
|
||||
export type NotificationPlacement = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'
|
||||
|
||||
export interface NotificationOptions {
|
||||
title?: string
|
||||
description?: string
|
||||
type?: NotificationType
|
||||
duration?: number
|
||||
closable?: boolean
|
||||
placement?: NotificationPlacement
|
||||
}
|
||||
|
||||
export interface NotificationHandle {
|
||||
close: () => void
|
||||
}
|
||||
|
||||
export interface NotificationConfig {
|
||||
placement?: NotificationPlacement
|
||||
duration?: number
|
||||
}
|
||||
```
|
||||
|
||||
### 组件形式（G3NotificationItem / G3NotificationContainer）
|
||||
|
||||
| 组件 | Props | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `G3NotificationItem` | `id` / `type` / `title` / `description` / `duration` / `closable` | 单条通知，`close` 事件表示「该关闭了」 |
|
||||
| `G3NotificationContainer` | `zIndex` | 四角容器，读取全局 `notificationState` 渲染 |
|
||||
|
||||
### 样式变量
|
||||
|
||||
| 变量 | 默认值 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `--g3-feedback-offset` | `24px` | 距视口边缘的距离 |
|
||||
| `--g3-feedback-icon-size` | `18px` | 类型图标尺寸 |
|
||||
| `--g3-shadow-popup` | 浮层阴影 | 通知卡片阴影 |
|
||||
|
||||
## 实现说明
|
||||
|
||||
- 与 Message 同构：组件树外单例容器（`createVNode` + `render`）、`reactive` 全局列表、四角常驻 `TransitionGroup`；
|
||||
- 单条宽度固定 `340px`，`max-width: calc(100vw - offset*2)`，窄屏不会溢出；描述文字换行不截断（通知的意义就在于把话说完）；
|
||||
- 层级的 `feedback` 档高于 modal / popup：弹窗里触发的通知一定能被看到；
|
||||
- `destroy()` 会卸载容器并回收 z-index，适合登出等「上下文整体切换」的场景；`close(id)` 只关一条。
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
title: Scrollbar 滚动容器
|
||||
description: 隐藏原生滚动条，用自绘滑块承载可滚动内容
|
||||
---
|
||||
|
||||
# Scrollbar 滚动容器
|
||||
|
||||
`Scrollbar` 给内容区套一层自绘滚动条。它统一了各浏览器（尤其是 Windows 与 macOS）的滚动条外观，并保证在深色主题下也可见。
|
||||
|
||||
## 何时使用
|
||||
|
||||
- 侧栏、面板、下拉列表等「内部滚动区域」需要与整体视觉统一时；
|
||||
- 原生滚动条太粗、或在深色主题下对比度不足时；
|
||||
- 高度固定的区域（必须给容器一个确定的高度，否则内容不会滚动）。
|
||||
|
||||
## 基础用法
|
||||
|
||||
容器必须有确定高度（`height` / `max-height`），滚动才会生效。
|
||||
|
||||
<demo vue="scrollbar/basic.vue" />
|
||||
|
||||
## 自动隐藏策略
|
||||
|
||||
`autoHide` 控制滚动条何时出现：
|
||||
|
||||
| 取值 | 行为 | 适合 |
|
||||
| --- | --- | --- |
|
||||
| `never` | 常显（默认） | 长列表、始终需要滚动提示 |
|
||||
| `scroll` | 滚动时显示，停止后渐隐 | 阅读区、日志 |
|
||||
| `move` | 鼠标移入或滚动时显示 | 面板、卡片 |
|
||||
| `leave` | 鼠标移出后隐藏 | 需要极简视觉的展示区 |
|
||||
|
||||
<demo vue="scrollbar/autohide.vue" />
|
||||
|
||||
## 无障碍
|
||||
|
||||
滚动区域是一个可聚焦容器（键盘 `↑ ↓ PageUp PageDown` 可滚动），因此需要给出可读名称：
|
||||
|
||||
```vue
|
||||
<G3Scrollbar aria-label="构建日志">…</G3Scrollbar>
|
||||
```
|
||||
|
||||
`visibility="hidden"` 时滚动条彻底不显示，但内容仍可滚动（键盘 / 触控板可用）。
|
||||
|
||||
## API
|
||||
|
||||
### Props
|
||||
|
||||
| 名称 | 类型 | 默认值 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `visibility` | `'visible' \| 'auto' \| 'hidden'` | `'auto'` | 滚动条显示策略。`auto` 时按 `autoHide` 规则显隐；`hidden` 彻底不显示滚动条（仍可滚动） |
|
||||
| `autoHide` | `'never' \| 'scroll' \| 'move' \| 'leave'` | `'never'` | 自动隐藏策略，仅 `visibility="auto"` 时生效 |
|
||||
| `ariaLabel` | `string` | — | 滚动区域的无障碍名称，等价于 `aria-label` |
|
||||
|
||||
### Slots
|
||||
|
||||
| 名称 | 参数 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `default` | — | 可滚动内容 |
|
||||
|
||||
### 类型定义
|
||||
|
||||
```ts
|
||||
export type ScrollbarVisibility = 'visible' | 'auto' | 'hidden'
|
||||
export type ScrollbarAutoHide = 'never' | 'scroll' | 'move' | 'leave'
|
||||
|
||||
export interface ScrollbarProps {
|
||||
visibility?: ScrollbarVisibility
|
||||
autoHide?: ScrollbarAutoHide
|
||||
ariaLabel?: string
|
||||
}
|
||||
```
|
||||
|
||||
### 样式变量
|
||||
|
||||
| 变量 | 默认值 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `--g3-scrollbar-size` | `8px` | 滚动条粗细 |
|
||||
| `--g3-scrollbar-thumb` | 半透明中性色 | 滑块颜色（hover 时加深） |
|
||||
| `--g3-scrollbar-track` | `transparent` | 轨道颜色 |
|
||||
|
||||
## 实现说明
|
||||
|
||||
- 滑块位置由 `scrollTop / scrollHeight` 实时换算，拖动滑块时反向写回滚动容器的 `scrollTop`；拖动期间给容器加 `is-dragging` 类，避免原生滚动干扰；
|
||||
- 尺寸变化（内容增删、容器缩放）通过 `ResizeObserver` 监听，滑块长度与可见性会自动更新，不需要手动 `update()`；
|
||||
- 隐藏原生滚动条用 `scrollbar-width: none` + `::-webkit-scrollbar { display: none }`，**不改** `overflow` 语义，因此键盘、触控板、`scrollIntoView` 全部照旧可用；
|
||||
- 不引第三方滚动库（如 overlayscrollbars），保持组件库零运行时依赖；代价是不支持原生「橡皮筋回弹」等平台特性。
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
title: Spin 加载中
|
||||
description: 包裹内容显示加载遮罩，或作为独立的加载指示器
|
||||
---
|
||||
|
||||
# Spin 加载中
|
||||
|
||||
`Spin` 表达「正在加载」。它会**遮罩被包裹的内容并阻止交互**，这是它与只显示图标的纯视觉 loading 的区别。
|
||||
|
||||
## 何时使用
|
||||
|
||||
- 区域级加载：表格、卡片、表单在请求期间需要冻结交互时；
|
||||
- 局部刷新：点「重新加载」后只遮住该区域，而不是整页 loading；
|
||||
- 全局 loading 建议用顶部进度条或 [Message](/ui/feedback/message)，避免整页白屏。
|
||||
|
||||
## 基础用法
|
||||
|
||||
传默认插槽即「包裹模式」：`spinning` 为 true 时给内容加遮罩并显示指示器。
|
||||
|
||||
<demo vue="spin/basic.vue" />
|
||||
|
||||
## 独立使用
|
||||
|
||||
不传默认插槽时就是独立指示器，配 `description` 显示加载文案。
|
||||
|
||||
<demo vue="spin/standalone.vue" />
|
||||
|
||||
## 延迟显示
|
||||
|
||||
`delay` 用来防「闪一下」：请求很快时根本不显示加载态，只有超过 `delay` 才出现。
|
||||
|
||||
<demo vue="spin/delay.vue" />
|
||||
|
||||
## 使用建议
|
||||
|
||||
```vue
|
||||
<!-- 推荐：局部冻结，用户知道「正在刷新的是哪一块」 -->
|
||||
<G3Spin :spinning="loading" :delay="300">
|
||||
<DataTable :rows="rows" />
|
||||
</G3Spin>
|
||||
|
||||
<!-- 不推荐：把整页包起来，用户失去上下文 -->
|
||||
<G3Spin :spinning="loading"><App /></G3Spin>
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### Props
|
||||
|
||||
| 名称 | 类型 | 默认值 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `spinning` | `boolean` | `false` | 是否加载中。包裹模式下会显示遮罩并阻止点击；独立模式下控制指示器显隐 |
|
||||
| `delay` | `number` | `0` | 延迟显示（ms）。请求快于该值时不显示加载态，避免闪烁 |
|
||||
| `description` | `string` | — | 加载文案，显示在指示器下方 |
|
||||
|
||||
### Slots
|
||||
|
||||
| 名称 | 参数 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `default` | — | 被遮罩的内容。不传时渲染为独立指示器 |
|
||||
| `indicator` | — | 自定义指示器（替换默认转圈） |
|
||||
| `description` | — | 自定义文案内容 |
|
||||
|
||||
### 类型定义
|
||||
|
||||
```ts
|
||||
export interface SpinProps {
|
||||
spinning?: boolean
|
||||
delay?: number
|
||||
description?: string
|
||||
}
|
||||
```
|
||||
|
||||
### 样式变量
|
||||
|
||||
| 变量 | 默认值 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `--g3-spin-size` | `20px` | 指示器尺寸 |
|
||||
| `--g3-spin-description-gap` | `8px` | 指示器与文案的间距 |
|
||||
| `--g3-color-primary` | `#18181b` | 指示器颜色 |
|
||||
|
||||
## 实现说明
|
||||
|
||||
- 遮罩是绝对定位覆盖在内容之上（内容区保持原尺寸，不会因为加载而跳高跳宽），并吃掉点击，避免用户在加载中重复提交；
|
||||
- 遮罩带 `aria-busy="true"`，屏幕阅读器能感知「该区域忙」，并且不会改变内容的可访问名称；
|
||||
- `delay` 的计时在 `spinning` 变 true 时启动、变 false 时清除：这样连续多次短请求不会累积显示；
|
||||
- 转圈动画在 `prefers-reduced-motion: reduce` 下会变成静态（保留图形、停止旋转），避免诱发不适。
|
||||
Reference in new issue
Block a user