@apexhub/apex-ui-react 0.0.0-stage → 1.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +37 -2
- package/dist/en_US.d.ts +191 -0
- package/dist/index.cjs +40727 -0
- package/dist/index.d.ts +6873 -0
- package/dist/index.mjs +40711 -0
- package/dist/llm/alert.tokens.txt +44 -0
- package/dist/llm/alert.txt +167 -0
- package/dist/llm/apex-provider.txt +369 -0
- package/dist/llm/auto-complete.tokens.txt +77 -0
- package/dist/llm/auto-complete.txt +373 -0
- package/dist/llm/avatar.tokens.txt +38 -0
- package/dist/llm/avatar.txt +199 -0
- package/dist/llm/breadcrumb.tokens.txt +143 -0
- package/dist/llm/breadcrumb.txt +251 -0
- package/dist/llm/button.tokens.txt +470 -0
- package/dist/llm/button.txt +270 -0
- package/dist/llm/card.tokens.txt +29 -0
- package/dist/llm/card.txt +118 -0
- package/dist/llm/cascader.tokens.txt +261 -0
- package/dist/llm/cascader.txt +917 -0
- package/dist/llm/checkbox.tokens.txt +36 -0
- package/dist/llm/checkbox.txt +343 -0
- package/dist/llm/collapse.tokens.txt +84 -0
- package/dist/llm/collapse.txt +330 -0
- package/dist/llm/date-picker.tokens.txt +171 -0
- package/dist/llm/date-picker.txt +428 -0
- package/dist/llm/divider.tokens.txt +22 -0
- package/dist/llm/divider.txt +161 -0
- package/dist/llm/drawer.tokens.txt +71 -0
- package/dist/llm/drawer.txt +369 -0
- package/dist/llm/dropdown.tokens.txt +59 -0
- package/dist/llm/dropdown.txt +420 -0
- package/dist/llm/form.tokens.txt +28 -0
- package/dist/llm/form.txt +341 -0
- package/dist/llm/grid.txt +419 -0
- package/dist/llm/image.tokens.txt +28 -0
- package/dist/llm/image.txt +428 -0
- package/dist/llm/input-number.tokens.txt +159 -0
- package/dist/llm/input-number.txt +491 -0
- package/dist/llm/input.tokens.txt +136 -0
- package/dist/llm/input.txt +424 -0
- package/dist/llm/layout.tokens.txt +29 -0
- package/dist/llm/layout.txt +298 -0
- package/dist/llm/menu.tokens.txt +100 -0
- package/dist/llm/menu.txt +687 -0
- package/dist/llm/message.tokens.txt +25 -0
- package/dist/llm/message.txt +301 -0
- package/dist/llm/modal.tokens.txt +96 -0
- package/dist/llm/modal.txt +584 -0
- package/dist/llm/notification.tokens.txt +79 -0
- package/dist/llm/notification.txt +383 -0
- package/dist/llm/pagination.tokens.txt +35 -0
- package/dist/llm/pagination.txt +217 -0
- package/dist/llm/popover.tokens.txt +18 -0
- package/dist/llm/popover.txt +233 -0
- package/dist/llm/progress.tokens.txt +83 -0
- package/dist/llm/progress.txt +279 -0
- package/dist/llm/radio.tokens.txt +26 -0
- package/dist/llm/radio.txt +385 -0
- package/dist/llm/rate.tokens.txt +20 -0
- package/dist/llm/rate.txt +241 -0
- package/dist/llm/select.tokens.txt +160 -0
- package/dist/llm/select.txt +831 -0
- package/dist/llm/skeleton.tokens.txt +15 -0
- package/dist/llm/skeleton.txt +275 -0
- package/dist/llm/spin.tokens.txt +21 -0
- package/dist/llm/spin.txt +294 -0
- package/dist/llm/steps.tokens.txt +30 -0
- package/dist/llm/steps.txt +300 -0
- package/dist/llm/switch.tokens.txt +38 -0
- package/dist/llm/switch.txt +216 -0
- package/dist/llm/table.tokens.txt +94 -0
- package/dist/llm/table.txt +1049 -0
- package/dist/llm/tabs.tokens.txt +78 -0
- package/dist/llm/tabs.txt +306 -0
- package/dist/llm/tag.tokens.txt +75 -0
- package/dist/llm/tag.txt +304 -0
- package/dist/llm/tooltip.tokens.txt +22 -0
- package/dist/llm/tooltip.txt +304 -0
- package/dist/llm/tree-select.tokens.txt +175 -0
- package/dist/llm/tree-select.txt +772 -0
- package/dist/llm/tree.tokens.txt +34 -0
- package/dist/llm/tree.txt +501 -0
- package/dist/llm/typography.tokens.txt +60 -0
- package/dist/llm/typography.txt +413 -0
- package/dist/llm/upload.tokens.txt +205 -0
- package/dist/llm/upload.txt +708 -0
- package/dist/llms-full.txt +16826 -0
- package/dist/llms-theme.txt +32 -0
- package/dist/llms.txt +59 -0
- package/dist/locale/en_US.cjs +160 -0
- package/dist/locale/en_US.d.ts +4 -0
- package/dist/locale/en_US.mjs +161 -0
- package/dist/locale/zh_CN.cjs +160 -0
- package/dist/locale/zh_CN.d.ts +4 -0
- package/dist/locale/zh_CN.mjs +161 -0
- package/dist/style.css +20095 -0
- package/dist/zh_CN.d.ts +191 -0
- package/llms-full.txt +16826 -0
- package/llms-theme.txt +32 -0
- package/llms.txt +59 -0
- package/package.json +118 -3
- package/src/alert/llm.txt +167 -0
- package/src/alert/tokens.txt +44 -0
- package/src/apex-provider/llm.txt +369 -0
- package/src/auto-complete/llm.txt +373 -0
- package/src/auto-complete/tokens.txt +77 -0
- package/src/avatar/llm.txt +199 -0
- package/src/avatar/tokens.txt +38 -0
- package/src/breadcrumb/llm.txt +251 -0
- package/src/breadcrumb/tokens.txt +143 -0
- package/src/button/llm.txt +270 -0
- package/src/button/tokens.txt +470 -0
- package/src/card/llm.txt +118 -0
- package/src/card/tokens.txt +29 -0
- package/src/cascader/llm.txt +917 -0
- package/src/cascader/tokens.txt +261 -0
- package/src/checkbox/llm.txt +343 -0
- package/src/checkbox/tokens.txt +36 -0
- package/src/collapse/llm.txt +330 -0
- package/src/collapse/tokens.txt +84 -0
- package/src/date-picker/llm.txt +428 -0
- package/src/date-picker/tokens.txt +171 -0
- package/src/divider/llm.txt +161 -0
- package/src/divider/tokens.txt +22 -0
- package/src/drawer/llm.txt +369 -0
- package/src/drawer/tokens.txt +71 -0
- package/src/dropdown/llm.txt +420 -0
- package/src/dropdown/tokens.txt +59 -0
- package/src/form/llm.txt +341 -0
- package/src/form/tokens.txt +28 -0
- package/src/grid/llm.txt +419 -0
- package/src/image/llm.txt +428 -0
- package/src/image/tokens.txt +28 -0
- package/src/input/llm.txt +424 -0
- package/src/input/tokens.txt +136 -0
- package/src/input-number/llm.txt +491 -0
- package/src/input-number/tokens.txt +159 -0
- package/src/layout/llm.txt +298 -0
- package/src/layout/tokens.txt +29 -0
- package/src/menu/llm.txt +687 -0
- package/src/menu/tokens.txt +100 -0
- package/src/message/llm.txt +301 -0
- package/src/message/tokens.txt +25 -0
- package/src/modal/llm.txt +584 -0
- package/src/modal/tokens.txt +96 -0
- package/src/notification/llm.txt +383 -0
- package/src/notification/tokens.txt +79 -0
- package/src/pagination/llm.txt +217 -0
- package/src/pagination/tokens.txt +35 -0
- package/src/popover/llm.txt +233 -0
- package/src/popover/tokens.txt +18 -0
- package/src/progress/llm.txt +279 -0
- package/src/progress/tokens.txt +83 -0
- package/src/radio/llm.txt +385 -0
- package/src/radio/tokens.txt +26 -0
- package/src/rate/llm.txt +241 -0
- package/src/rate/tokens.txt +20 -0
- package/src/select/llm.txt +831 -0
- package/src/select/tokens.txt +160 -0
- package/src/skeleton/llm.txt +275 -0
- package/src/skeleton/tokens.txt +15 -0
- package/src/spin/llm.txt +294 -0
- package/src/spin/tokens.txt +21 -0
- package/src/steps/llm.txt +300 -0
- package/src/steps/tokens.txt +30 -0
- package/src/switch/llm.txt +216 -0
- package/src/switch/tokens.txt +38 -0
- package/src/table/llm.txt +1049 -0
- package/src/table/tokens.txt +94 -0
- package/src/tabs/llm.txt +306 -0
- package/src/tabs/tokens.txt +78 -0
- package/src/tag/llm.txt +304 -0
- package/src/tag/tokens.txt +75 -0
- package/src/tooltip/llm.txt +304 -0
- package/src/tooltip/tokens.txt +22 -0
- package/src/tree/llm.txt +501 -0
- package/src/tree/tokens.txt +34 -0
- package/src/tree-select/llm.txt +772 -0
- package/src/tree-select/tokens.txt +175 -0
- package/src/typography/llm.txt +413 -0
- package/src/typography/tokens.txt +60 -0
- package/src/upload/llm.txt +708 -0
- package/src/upload/tokens.txt +205 -0
|
@@ -0,0 +1,428 @@
|
|
|
1
|
+
# Image
|
|
2
|
+
|
|
3
|
+
> Image:需要以缩略图形式展示图片,并支持点击放大预览时。
|
|
4
|
+
|
|
5
|
+
包:`@apexhub/apex-ui-react`;版本:`1.2.2`(当前源码快照,发布状态以安装包版本为准)。
|
|
6
|
+
|
|
7
|
+
公开导出:`Image`。
|
|
8
|
+
|
|
9
|
+
以下 API 属于 Apex UI;不要据 antd 的同名组件推断额外属性或默认值。默认值列的空缺表示未声明,不代表 `false`。
|
|
10
|
+
|
|
11
|
+
## 快速开始
|
|
12
|
+
|
|
13
|
+
```tsx
|
|
14
|
+
import { Image } from '@apexhub/apex-ui-react'
|
|
15
|
+
|
|
16
|
+
import '@apexhub/apex-ui-react/style.css'
|
|
17
|
+
|
|
18
|
+
function imageDemoDataUrl(fill: string, label: string, width = 300, height = 200): string {
|
|
19
|
+
const fontSize = Math.round(Math.min(width, height) * 0.2)
|
|
20
|
+
return (
|
|
21
|
+
'data:image/svg+xml;utf8,' +
|
|
22
|
+
encodeURIComponent(
|
|
23
|
+
`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}"><rect width="100%" height="100%" fill="${fill}"/><text x="50%" y="55%" dominant-baseline="middle" fill="white" font-family="Arial,sans-serif" font-size="${fontSize}" text-anchor="middle">${label}</text></svg>`,
|
|
24
|
+
)
|
|
25
|
+
)
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
const DEMO_IMG_A = imageDemoDataUrl('#7B61FF', 'A')
|
|
29
|
+
|
|
30
|
+
const DEMO_IMG_B = imageDemoDataUrl('#5B8DEF', 'B')
|
|
31
|
+
|
|
32
|
+
const DEMO_IMG_C = imageDemoDataUrl('#E86452', 'C')
|
|
33
|
+
|
|
34
|
+
const DEMO_IMG_FALLBACK = imageDemoDataUrl('#888888', 'Fallback')
|
|
35
|
+
|
|
36
|
+
export default () => <Image src={DEMO_IMG_A} alt="示例图片" width={300} height={200} />
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## 何时使用
|
|
40
|
+
|
|
41
|
+
- 需要以缩略图形式展示图片,并支持点击放大预览时。
|
|
42
|
+
- 多张图片需要统一灯箱浏览、键盘左右切换时,使用 `Image.PreviewGroup`。
|
|
43
|
+
- 图片来源不可靠,需要 `fallback` 替代图或加载中 `placeholder` 占位时。
|
|
44
|
+
- **仅限图片**:内置预览只处理图片格式;PDF/Office 等非图片文件请使用 Upload 的 文件预览回调 自行接管。
|
|
45
|
+
|
|
46
|
+
## API
|
|
47
|
+
|
|
48
|
+
仅使用类型定义支持的属性;原生属性、ref 目标和事件签名因组件而异。关联类型用于解释字段结构;只有「导出类型」中的名称可从包根导入。
|
|
49
|
+
|
|
50
|
+
### Image
|
|
51
|
+
|
|
52
|
+
| 属性 | 说明 | 类型 | 必填 | 默认值 |
|
|
53
|
+
| --- | --- | --- | --- | --- |
|
|
54
|
+
| fallback | 首图加载失败后的替代地址;该地址再失败时停止切换,不循环 | `string` | 否 | — |
|
|
55
|
+
| placeholder | 首图加载完成前的占位节点 | `React.ReactNode` | 否 | — |
|
|
56
|
+
| preview | 预览行为。<br>- `true`:点击打开预览(默认)<br>- `false`:禁用预览<br>- 对象:自定义预览 `src` 与受控 / 非受控打开状态 | `boolean \| ImagePreviewConfig` | 否 | `true` |
|
|
57
|
+
|
|
58
|
+
### ImagePreviewConfig
|
|
59
|
+
|
|
60
|
+
单图预览层配置(挂在 `Image.preview` 对象上)
|
|
61
|
+
|
|
62
|
+
| 属性 | 说明 | 类型 | 必填 | 默认值 |
|
|
63
|
+
| --- | --- | --- | --- | --- |
|
|
64
|
+
| src | 预览大图地址;与缩略图 `src` 不同时使用 | `string` | 否 | — |
|
|
65
|
+
| open | 是否打开预览(受控) | `boolean` | 否 | — |
|
|
66
|
+
| defaultOpen | 非受控初始是否打开 | `boolean` | 否 | `false` |
|
|
67
|
+
| onOpenChange | 预览开关变化 | `(open: boolean) => void` | 否 | — |
|
|
68
|
+
|
|
69
|
+
### ImagePreviewItem
|
|
70
|
+
|
|
71
|
+
PreviewGroup 数据项:仅描述图片 URL 与必要 `<img>` 属性,不接收 `UploadFile`
|
|
72
|
+
|
|
73
|
+
| 属性 | 说明 | 类型 | 必填 | 默认值 |
|
|
74
|
+
| --- | --- | --- | --- | --- |
|
|
75
|
+
| src | 图片地址 | `string` | 是 | — |
|
|
76
|
+
| key | 稳定 key;未传时实现可用 `src` + 索引兜底 | `React.Key` | 否 | — |
|
|
77
|
+
|
|
78
|
+
### ImagePreviewGroupSharedProps
|
|
79
|
+
|
|
80
|
+
PreviewGroup 共享的开关 / 索引契约(顶层受控,不嵌套进 `preview`)
|
|
81
|
+
|
|
82
|
+
| 属性 | 说明 | 类型 | 必填 | 默认值 |
|
|
83
|
+
| --- | --- | --- | --- | --- |
|
|
84
|
+
| fallback | 组级加载失败兜底地址 | `string` | 否 | — |
|
|
85
|
+
| open | 是否打开预览层(受控) | `boolean` | 否 | — |
|
|
86
|
+
| defaultOpen | 非受控初始是否打开 | `boolean` | 否 | `false` |
|
|
87
|
+
| onOpenChange | 预览开关变化 | `(open: boolean) => void` | 否 | — |
|
|
88
|
+
| current | 当前预览索引(受控,从 0 起) | `number` | 否 | — |
|
|
89
|
+
| defaultCurrent | 非受控初始索引 | `number` | 否 | `0` |
|
|
90
|
+
| onCurrentChange | 当前索引变化 | `(current: number) => void` | 否 | — |
|
|
91
|
+
|
|
92
|
+
### ImagePreviewGroupItemsProps
|
|
93
|
+
|
|
94
|
+
数据源模式:传入 `items`,禁止同时传 `children`
|
|
95
|
+
|
|
96
|
+
| 属性 | 说明 | 类型 | 必填 | 默认值 |
|
|
97
|
+
| --- | --- | --- | --- | --- |
|
|
98
|
+
| fallback | 组级加载失败兜底地址 | `string` | 否 | — |
|
|
99
|
+
| open | 是否打开预览层(受控) | `boolean` | 否 | — |
|
|
100
|
+
| defaultOpen | 非受控初始是否打开 | `boolean` | 否 | `false` |
|
|
101
|
+
| onOpenChange | 预览开关变化 | `(open: boolean) => void` | 否 | — |
|
|
102
|
+
| current | 当前预览索引(受控,从 0 起) | `number` | 否 | — |
|
|
103
|
+
| defaultCurrent | 非受控初始索引 | `number` | 否 | `0` |
|
|
104
|
+
| onCurrentChange | 当前索引变化 | `(current: number) => void` | 否 | — |
|
|
105
|
+
| items | 预览图片列表 | `ImagePreviewItem[]` | 是 | — |
|
|
106
|
+
| children | — | `never` | 否 | — |
|
|
107
|
+
|
|
108
|
+
### ImagePreviewGroupChildrenProps
|
|
109
|
+
|
|
110
|
+
子节点注册模式:传入 `children`(多个 `Image`),禁止同时传 `items`
|
|
111
|
+
|
|
112
|
+
| 属性 | 说明 | 类型 | 必填 | 默认值 |
|
|
113
|
+
| --- | --- | --- | --- | --- |
|
|
114
|
+
| fallback | 组级加载失败兜底地址 | `string` | 否 | — |
|
|
115
|
+
| open | 是否打开预览层(受控) | `boolean` | 否 | — |
|
|
116
|
+
| defaultOpen | 非受控初始是否打开 | `boolean` | 否 | `false` |
|
|
117
|
+
| onOpenChange | 预览开关变化 | `(open: boolean) => void` | 否 | — |
|
|
118
|
+
| current | 当前预览索引(受控,从 0 起) | `number` | 否 | — |
|
|
119
|
+
| defaultCurrent | 非受控初始索引 | `number` | 否 | `0` |
|
|
120
|
+
| onCurrentChange | 当前索引变化 | `(current: number) => void` | 否 | — |
|
|
121
|
+
| children | 组内 `Image` 子节点;点击任一张从对应索引打开 | `React.ReactNode` | 是 | — |
|
|
122
|
+
| items | — | `never` | 否 | — |
|
|
123
|
+
|
|
124
|
+
### ImagePreviewGroupProps
|
|
125
|
+
|
|
126
|
+
`Image.PreviewGroup` Props。
|
|
127
|
+
|
|
128
|
+
```typescript
|
|
129
|
+
type ImagePreviewGroupProps = ImagePreviewGroupItemsProps | ImagePreviewGroupChildrenProps
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### 导出类型
|
|
133
|
+
|
|
134
|
+
另可从 `@apexhub/apex-ui-react` 导入:`ImagePreviewConfig`、`ImagePreviewGroupProps`、`ImagePreviewItem`、`ImageProps`(与上文子类型配合使用)。
|
|
135
|
+
|
|
136
|
+
## 代码演示
|
|
137
|
+
|
|
138
|
+
### 加载占位
|
|
139
|
+
|
|
140
|
+
通过 `placeholder` 在图片加载完成前展示占位节点(自定义 自定义节点,常见为 Spin / 骨架)。点 Reload 可重新观看加载过程。
|
|
141
|
+
|
|
142
|
+
```tsx
|
|
143
|
+
import { Button, Image, Spin } from '@apexhub/apex-ui-react'
|
|
144
|
+
|
|
145
|
+
import { useEffect, useState } from 'react'
|
|
146
|
+
|
|
147
|
+
function imageDemoDataUrl(fill: string, label: string, width = 300, height = 200): string {
|
|
148
|
+
const fontSize = Math.round(Math.min(width, height) * 0.2)
|
|
149
|
+
return (
|
|
150
|
+
'data:image/svg+xml;utf8,' +
|
|
151
|
+
encodeURIComponent(
|
|
152
|
+
`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}"><rect width="100%" height="100%" fill="${fill}"/><text x="50%" y="55%" dominant-baseline="middle" fill="white" font-family="Arial,sans-serif" font-size="${fontSize}" text-anchor="middle">${label}</text></svg>`,
|
|
153
|
+
)
|
|
154
|
+
)
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
const DEMO_IMG_A = imageDemoDataUrl('#7B61FF', 'A')
|
|
158
|
+
|
|
159
|
+
const DEMO_IMG_B = imageDemoDataUrl('#5B8DEF', 'B')
|
|
160
|
+
|
|
161
|
+
const DEMO_IMG_C = imageDemoDataUrl('#E86452', 'C')
|
|
162
|
+
|
|
163
|
+
const DEMO_IMG_FALLBACK = imageDemoDataUrl('#888888', 'Fallback')
|
|
164
|
+
|
|
165
|
+
const LOAD_DELAY_MS = 1200
|
|
166
|
+
|
|
167
|
+
export default () => {
|
|
168
|
+
const [seed, setSeed] = useState(0)
|
|
169
|
+
const [src, setSrc] = useState<string>()
|
|
170
|
+
|
|
171
|
+
useEffect(() => {
|
|
172
|
+
setSrc(undefined)
|
|
173
|
+
const id = window.setTimeout(() => setSrc(DEMO_IMG_A), LOAD_DELAY_MS)
|
|
174
|
+
return () => window.clearTimeout(id)
|
|
175
|
+
}, [seed])
|
|
176
|
+
|
|
177
|
+
return (
|
|
178
|
+
<div style={{ display: 'flex', flexDirection: 'column', gap: 12, alignItems: 'flex-start' }}>
|
|
179
|
+
<Image
|
|
180
|
+
key={seed}
|
|
181
|
+
src={src}
|
|
182
|
+
alt="带占位图片"
|
|
183
|
+
width={300}
|
|
184
|
+
height={200}
|
|
185
|
+
preview={false}
|
|
186
|
+
placeholder={
|
|
187
|
+
<span aria-label="加载占位">
|
|
188
|
+
<Spin size="medium" />
|
|
189
|
+
</span>
|
|
190
|
+
}
|
|
191
|
+
/>
|
|
192
|
+
<Button
|
|
193
|
+
onClick={() => {
|
|
194
|
+
setSrc(undefined)
|
|
195
|
+
setSeed((value) => value + 1)
|
|
196
|
+
}}
|
|
197
|
+
>
|
|
198
|
+
Reload
|
|
199
|
+
</Button>
|
|
200
|
+
</div>
|
|
201
|
+
)
|
|
202
|
+
}
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
### 加载失败回退
|
|
206
|
+
|
|
207
|
+
`fallback` 指定一个备用图片地址;首图加载失败后自动切换,备用图再失败不会循环。
|
|
208
|
+
|
|
209
|
+
```tsx
|
|
210
|
+
import { Image } from '@apexhub/apex-ui-react'
|
|
211
|
+
|
|
212
|
+
function imageDemoDataUrl(fill: string, label: string, width = 300, height = 200): string {
|
|
213
|
+
const fontSize = Math.round(Math.min(width, height) * 0.2)
|
|
214
|
+
return (
|
|
215
|
+
'data:image/svg+xml;utf8,' +
|
|
216
|
+
encodeURIComponent(
|
|
217
|
+
`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}"><rect width="100%" height="100%" fill="${fill}"/><text x="50%" y="55%" dominant-baseline="middle" fill="white" font-family="Arial,sans-serif" font-size="${fontSize}" text-anchor="middle">${label}</text></svg>`,
|
|
218
|
+
)
|
|
219
|
+
)
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
const DEMO_IMG_A = imageDemoDataUrl('#7B61FF', 'A')
|
|
223
|
+
|
|
224
|
+
const DEMO_IMG_B = imageDemoDataUrl('#5B8DEF', 'B')
|
|
225
|
+
|
|
226
|
+
const DEMO_IMG_C = imageDemoDataUrl('#E86452', 'C')
|
|
227
|
+
|
|
228
|
+
const DEMO_IMG_FALLBACK = imageDemoDataUrl('#888888', 'Fallback')
|
|
229
|
+
|
|
230
|
+
export default () => (
|
|
231
|
+
<Image
|
|
232
|
+
src="https://invalid-url-that-will-fail.test/img.png"
|
|
233
|
+
alt="回退图片"
|
|
234
|
+
width={300}
|
|
235
|
+
height={200}
|
|
236
|
+
fallback={DEMO_IMG_FALLBACK}
|
|
237
|
+
/>
|
|
238
|
+
)
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
### 禁用预览
|
|
242
|
+
|
|
243
|
+
`preview` 设为 `false` 仅展示缩略图,点击不会打开预览层。
|
|
244
|
+
|
|
245
|
+
```tsx
|
|
246
|
+
import { Image } from '@apexhub/apex-ui-react'
|
|
247
|
+
|
|
248
|
+
function imageDemoDataUrl(fill: string, label: string, width = 300, height = 200): string {
|
|
249
|
+
const fontSize = Math.round(Math.min(width, height) * 0.2)
|
|
250
|
+
return (
|
|
251
|
+
'data:image/svg+xml;utf8,' +
|
|
252
|
+
encodeURIComponent(
|
|
253
|
+
`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}"><rect width="100%" height="100%" fill="${fill}"/><text x="50%" y="55%" dominant-baseline="middle" fill="white" font-family="Arial,sans-serif" font-size="${fontSize}" text-anchor="middle">${label}</text></svg>`,
|
|
254
|
+
)
|
|
255
|
+
)
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
const DEMO_IMG_A = imageDemoDataUrl('#7B61FF', 'A')
|
|
259
|
+
|
|
260
|
+
const DEMO_IMG_B = imageDemoDataUrl('#5B8DEF', 'B')
|
|
261
|
+
|
|
262
|
+
const DEMO_IMG_C = imageDemoDataUrl('#E86452', 'C')
|
|
263
|
+
|
|
264
|
+
const DEMO_IMG_FALLBACK = imageDemoDataUrl('#888888', 'Fallback')
|
|
265
|
+
|
|
266
|
+
export default () => (
|
|
267
|
+
<Image src={DEMO_IMG_A} alt="禁用预览" width={300} height={200} preview={false} />
|
|
268
|
+
)
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
### 受控预览
|
|
272
|
+
|
|
273
|
+
通过 `preview` 的 `open` 与 `onOpenChange` 配置 将预览层开关交由外部状态管理,可实现按钮触发等场景。
|
|
274
|
+
|
|
275
|
+
```tsx
|
|
276
|
+
import { Button, Image } from '@apexhub/apex-ui-react'
|
|
277
|
+
|
|
278
|
+
import { useState } from 'react'
|
|
279
|
+
|
|
280
|
+
function imageDemoDataUrl(fill: string, label: string, width = 300, height = 200): string {
|
|
281
|
+
const fontSize = Math.round(Math.min(width, height) * 0.2)
|
|
282
|
+
return (
|
|
283
|
+
'data:image/svg+xml;utf8,' +
|
|
284
|
+
encodeURIComponent(
|
|
285
|
+
`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}"><rect width="100%" height="100%" fill="${fill}"/><text x="50%" y="55%" dominant-baseline="middle" fill="white" font-family="Arial,sans-serif" font-size="${fontSize}" text-anchor="middle">${label}</text></svg>`,
|
|
286
|
+
)
|
|
287
|
+
)
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
const DEMO_IMG_A = imageDemoDataUrl('#7B61FF', 'A')
|
|
291
|
+
|
|
292
|
+
const DEMO_IMG_B = imageDemoDataUrl('#5B8DEF', 'B')
|
|
293
|
+
|
|
294
|
+
const DEMO_IMG_C = imageDemoDataUrl('#E86452', 'C')
|
|
295
|
+
|
|
296
|
+
const DEMO_IMG_FALLBACK = imageDemoDataUrl('#888888', 'Fallback')
|
|
297
|
+
|
|
298
|
+
export default () => {
|
|
299
|
+
const [open, setOpen] = useState(false)
|
|
300
|
+
|
|
301
|
+
return (
|
|
302
|
+
<div>
|
|
303
|
+
<Button onClick={() => setOpen(true)} style={{ marginBottom: 12 }}>
|
|
304
|
+
外部按钮打开预览
|
|
305
|
+
</Button>
|
|
306
|
+
<br />
|
|
307
|
+
<Image
|
|
308
|
+
src={DEMO_IMG_A}
|
|
309
|
+
alt="受控预览"
|
|
310
|
+
width={300}
|
|
311
|
+
height={200}
|
|
312
|
+
preview={{ open, onOpenChange: setOpen }}
|
|
313
|
+
/>
|
|
314
|
+
</div>
|
|
315
|
+
)
|
|
316
|
+
}
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
### 多图预览(children 模式)
|
|
320
|
+
|
|
321
|
+
用 `Image.PreviewGroup` 包裹多个 `Image` 子节点,点击任一张即可按顺序浏览全组图片。
|
|
322
|
+
|
|
323
|
+
```tsx
|
|
324
|
+
import { Image } from '@apexhub/apex-ui-react'
|
|
325
|
+
|
|
326
|
+
function imageDemoDataUrl(fill: string, label: string, width = 300, height = 200): string {
|
|
327
|
+
const fontSize = Math.round(Math.min(width, height) * 0.2)
|
|
328
|
+
return (
|
|
329
|
+
'data:image/svg+xml;utf8,' +
|
|
330
|
+
encodeURIComponent(
|
|
331
|
+
`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}"><rect width="100%" height="100%" fill="${fill}"/><text x="50%" y="55%" dominant-baseline="middle" fill="white" font-family="Arial,sans-serif" font-size="${fontSize}" text-anchor="middle">${label}</text></svg>`,
|
|
332
|
+
)
|
|
333
|
+
)
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
const DEMO_IMG_A = imageDemoDataUrl('#7B61FF', 'A')
|
|
337
|
+
|
|
338
|
+
const DEMO_IMG_B = imageDemoDataUrl('#5B8DEF', 'B')
|
|
339
|
+
|
|
340
|
+
const DEMO_IMG_C = imageDemoDataUrl('#E86452', 'C')
|
|
341
|
+
|
|
342
|
+
const DEMO_IMG_FALLBACK = imageDemoDataUrl('#888888', 'Fallback')
|
|
343
|
+
|
|
344
|
+
export default () => (
|
|
345
|
+
<Image.PreviewGroup>
|
|
346
|
+
<div style={{ display: 'flex', gap: 12 }}>
|
|
347
|
+
<Image src={DEMO_IMG_A} alt="图A" width={150} height={100} />
|
|
348
|
+
<Image src={DEMO_IMG_B} alt="图B" width={150} height={100} />
|
|
349
|
+
<Image src={DEMO_IMG_C} alt="图C" width={150} height={100} />
|
|
350
|
+
</div>
|
|
351
|
+
</Image.PreviewGroup>
|
|
352
|
+
)
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
### 多图预览(items 数据源模式)
|
|
356
|
+
|
|
357
|
+
通过 `items` 传入图片数组,无需渲染子 `Image` 缩略图;适合纯灯箱浏览或与 Upload 集成的场景。`items` 与 子内容 **互斥**。
|
|
358
|
+
|
|
359
|
+
```tsx
|
|
360
|
+
import { Button, Image } from '@apexhub/apex-ui-react'
|
|
361
|
+
|
|
362
|
+
import { useState } from 'react'
|
|
363
|
+
|
|
364
|
+
function imageDemoDataUrl(fill: string, label: string, width = 300, height = 200): string {
|
|
365
|
+
const fontSize = Math.round(Math.min(width, height) * 0.2)
|
|
366
|
+
return (
|
|
367
|
+
'data:image/svg+xml;utf8,' +
|
|
368
|
+
encodeURIComponent(
|
|
369
|
+
`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}"><rect width="100%" height="100%" fill="${fill}"/><text x="50%" y="55%" dominant-baseline="middle" fill="white" font-family="Arial,sans-serif" font-size="${fontSize}" text-anchor="middle">${label}</text></svg>`,
|
|
370
|
+
)
|
|
371
|
+
)
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
const DEMO_IMG_A = imageDemoDataUrl('#7B61FF', 'A')
|
|
375
|
+
|
|
376
|
+
const DEMO_IMG_B = imageDemoDataUrl('#5B8DEF', 'B')
|
|
377
|
+
|
|
378
|
+
const DEMO_IMG_C = imageDemoDataUrl('#E86452', 'C')
|
|
379
|
+
|
|
380
|
+
const DEMO_IMG_FALLBACK = imageDemoDataUrl('#888888', 'Fallback')
|
|
381
|
+
|
|
382
|
+
export default () => {
|
|
383
|
+
const [open, setOpen] = useState(false)
|
|
384
|
+
|
|
385
|
+
return (
|
|
386
|
+
<>
|
|
387
|
+
<Button onClick={() => setOpen(true)}>打开图片组</Button>
|
|
388
|
+
<Image.PreviewGroup
|
|
389
|
+
items={[
|
|
390
|
+
{ src: DEMO_IMG_A, alt: '图A' },
|
|
391
|
+
{ src: DEMO_IMG_B, alt: '图B' },
|
|
392
|
+
{ src: DEMO_IMG_C, alt: '图C' },
|
|
393
|
+
]}
|
|
394
|
+
open={open}
|
|
395
|
+
onOpenChange={setOpen}
|
|
396
|
+
/>
|
|
397
|
+
</>
|
|
398
|
+
)
|
|
399
|
+
}
|
|
400
|
+
```
|
|
401
|
+
|
|
402
|
+
## DOM 结构
|
|
403
|
+
|
|
404
|
+
源码声明的静态 `data-slot`:`image`、`image-img`、`image-placeholder`、`image-cover`、`image-action-icon`、`image-preview`、`image-preview-mask`、`image-preview-wrapper`、`image-preview-container`、`image-preview-viewport-shell`、`image-preview-viewport`、`image-preview-stage`、`image-preview-swap`、`image-preview-content`、`image-preview-rotate-frame`、`image-preview-image`、`image-preview-toolbar-prev`、`image-preview-toolbar-next`、`image-preview-close`、`image-preview-zoom-level`、`image-preview-toolbar`。具体节点随模式和状态出现,不表示固定嵌套顺序。
|
|
405
|
+
|
|
406
|
+
## 行为要点
|
|
407
|
+
|
|
408
|
+
- **URL 所有权**:Image 只接收可用 URL 字符串,**不接收 `File`/`Blob`**,不调用 `revokeObjectURL`。如果你使用 `URL.createObjectURL` 生成的 `blob:` 地址,需自行管理生命周期。
|
|
409
|
+
- **变换工具栏**:预览层使用 medium 图标按钮,内置缩放(步进 0.25,范围 0.25–5)、左右旋转、1:1 原始尺寸、适应视口、占满视口。切图/关闭/重开时变换复位。
|
|
410
|
+
- **键盘**:打开后焦点陷阱;`Esc` 在占满视口时先退出占满再关闭;`←` / `→` 切图;关闭后焦点回触发元素。
|
|
411
|
+
- **边界**:单图无 prev/next 控件;索引越界时禁用不循环;`fallback` 再失败不递归。
|
|
412
|
+
|
|
413
|
+
## 样式定制
|
|
414
|
+
|
|
415
|
+
优先使用本组件公开的尺寸、类型和状态属性。换肤与变量覆盖方式见 [主题指南](../../llms-theme.txt)。
|
|
416
|
+
|
|
417
|
+
需要定制具体样式时再读取 [Token 明细](./tokens.txt),其中包含用途、定义值及适用作用域。常规组件使用无需加载该文件。
|
|
418
|
+
|
|
419
|
+
## FAQ
|
|
420
|
+
|
|
421
|
+
### Image 能预览 PDF 或 Office 文件吗?
|
|
422
|
+
|
|
423
|
+
不能。内置预览仅支持图片格式。非图片文件请使用 Upload 的 `onPreview` 回调自行实现业务预览逻辑。
|
|
424
|
+
|
|
425
|
+
|
|
426
|
+
### 与 antd Image 有什么区别?
|
|
427
|
+
|
|
428
|
+
PreviewGroup 的受控状态(`open`/`current`)在顶层而非嵌套在 `preview` 内;不支持 `actionsRender`、`movable`、翻转;超大图滚动而非拖拽;缩放上下限不开放 prop。
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Image Token 明细
|
|
2
|
+
|
|
3
|
+
包:`@apexhub/apex-ui-react`;版本:`1.2.2`(当前源码快照)。
|
|
4
|
+
|
|
5
|
+
按需读取:[组件用法](./llm.txt) · [主题与覆盖规则](../../llms-theme.txt)。
|
|
6
|
+
|
|
7
|
+
以下组件变量在设计 Token 源中已定义,并被组件或其共享样式使用;不包含仅在实现中声明的临时变量。用途来自实际 CSS 属性,不是对外新增的 Props。
|
|
8
|
+
|
|
9
|
+
定义值依赖所列尺寸、变体、状态和媒体作用域;Alias 引用还会随 light/dark 主题改变。它们不是统一默认值或最终计算值。作用域用于解释定义位置,不代表内部选择器是稳定的定制 API。
|
|
10
|
+
|
|
11
|
+
| Token | 用途(CSS 属性) | 定义值 | 定义作用域 |
|
|
12
|
+
| --- | --- | --- | --- |
|
|
13
|
+
| `--image-preview-spacing-gap` | `gap` | `var(--apex-spacing-16)` | `.apex-image-preview.apex-default-image-preview` |
|
|
14
|
+
| `--image-preview-spacing-padding-y-bar` | `padding` | `var(--apex-spacing-8)` | `.apex-image-preview.apex-default-image-preview` |
|
|
15
|
+
| `--overlay-fill-default` | `background` | `var(--apex-grey-dark-overlay)` | `.apex-image-preview.apex-default-image-preview` |
|
|
16
|
+
| `--overlay-fill-default` | `background` | `var(--apex-fill-neutral-overlay)` | `.apex-overlay.apex-default-overlay` |
|
|
17
|
+
| `--upload-fill-default` | `background` | `var(--apex-grey-dark-3)` | `.apex-image-preview.apex-default-image-preview` |
|
|
18
|
+
| `--upload-fill-default` | `background` | `var(--apex-fill-neutral-tertiary)` | `.apex-upload.apex-item-default-upload` |
|
|
19
|
+
| `--upload-fill-default` | `background` | `var(--apex-fill-neutral-quaternary)` | `.apex-upload.apex-item-elevated-upload` |
|
|
20
|
+
| `--upload-fill-default` | `background` | `var(--apex-fill-neutral-tertiary)` | `.apex-upload.apex-picture-upload` |
|
|
21
|
+
| `--upload-fill-default` | `background` | `var(--apex-fill-neutral-tertiary)` | `.apex-upload.apex-trigger-default-upload` |
|
|
22
|
+
| `--upload-fill-default` | `background` | `var(--apex-fill-neutral-quaternary)` | `.apex-upload.apex-trigger-elevated-upload` |
|
|
23
|
+
| `--upload-stroke-default` | `background` | `var(--apex-grey-dark-5)` | `.apex-image-preview.apex-default-image-preview` |
|
|
24
|
+
| `--upload-stroke-default` | `background` | `var(--apex-stroke-neutral-quaternary)` | `.apex-upload.apex-item-default-upload` |
|
|
25
|
+
| `--upload-stroke-default` | `background` | `var(--apex-stroke-neutral-quinary)` | `.apex-upload.apex-item-elevated-upload` |
|
|
26
|
+
| `--upload-stroke-default` | `background` | `var(--apex-stroke-neutral-quaternary)` | `.apex-upload.apex-picture-upload` |
|
|
27
|
+
| `--upload-stroke-default` | `background` | `var(--apex-stroke-neutral-quaternary)` | `.apex-upload.apex-trigger-default-upload` |
|
|
28
|
+
| `--upload-stroke-default` | `background` | `var(--apex-stroke-neutral-quinary)` | `.apex-upload.apex-trigger-elevated-upload` |
|