diff --git a/packages/docs/src/assets/images/opendesign-twinkle.mp4 b/packages/docs/src/assets/images/opendesign-twinkle.mp4
new file mode 100644
index 0000000000000000000000000000000000000000..b9dba1517d803ee28551121f2825ea5cadc3786f
Binary files /dev/null and b/packages/docs/src/assets/images/opendesign-twinkle.mp4 differ
diff --git a/packages/docs/src/assets/images/opendesign.png b/packages/docs/src/assets/images/opendesign.png
new file mode 100644
index 0000000000000000000000000000000000000000..dbcb7de3fbdc17e4c3b81a6abd11be1125bf2aed
Binary files /dev/null and b/packages/docs/src/assets/images/opendesign.png differ
diff --git a/packages/docs/src/assets/images/tree1.png b/packages/docs/src/assets/images/tree1.png
new file mode 100644
index 0000000000000000000000000000000000000000..3c93b39d60984981061324ebeb295d1804645ee2
Binary files /dev/null and b/packages/docs/src/assets/images/tree1.png differ
diff --git a/packages/docs/src/assets/images/tree2.png b/packages/docs/src/assets/images/tree2.png
new file mode 100644
index 0000000000000000000000000000000000000000..997d3dc1ef892eaf029f3e9d12ec5ee2122785ed
Binary files /dev/null and b/packages/docs/src/assets/images/tree2.png differ
diff --git a/packages/docs/src/assets/images/tree3.png b/packages/docs/src/assets/images/tree3.png
new file mode 100644
index 0000000000000000000000000000000000000000..d90287997cbdacbd51d71729865a7c198a85497e
Binary files /dev/null and b/packages/docs/src/assets/images/tree3.png differ
diff --git a/packages/docs/src/assets/images/tree4.png b/packages/docs/src/assets/images/tree4.png
new file mode 100644
index 0000000000000000000000000000000000000000..3bcd2fbf4b9043e66d5f51544e876268488e2a28
Binary files /dev/null and b/packages/docs/src/assets/images/tree4.png differ
diff --git a/packages/docs/src/assets/images/tree5.png b/packages/docs/src/assets/images/tree5.png
new file mode 100644
index 0000000000000000000000000000000000000000..4bb087d03cdeaf0e94c83ef493b1135a97197488
Binary files /dev/null and b/packages/docs/src/assets/images/tree5.png differ
diff --git a/packages/opendesign/src/figure/__docs__/__case__/CustomPlayIcon.vue b/packages/opendesign/src/figure/__docs__/__case__/CustomPlayIcon.vue
new file mode 100644
index 0000000000000000000000000000000000000000..09073f2782d046a1b90723db5a7411852dbc0301
--- /dev/null
+++ b/packages/opendesign/src/figure/__docs__/__case__/CustomPlayIcon.vue
@@ -0,0 +1,54 @@
+
+
+
+#### 自定义播放图标
+
+可通过 `play-icon` 插槽自定义播放图标。
+
+
+
+#### Custom Play Icon
+
+You can customize the play icon through the `play-icon` slot.
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/packages/opendesign/src/figure/__docs__/__case__/FigureUsage.vue b/packages/opendesign/src/figure/__docs__/__case__/FigureUsage.vue
new file mode 100644
index 0000000000000000000000000000000000000000..fe6e5bc4e7a092c20ac9ed30cab31ce1c8d0c089
--- /dev/null
+++ b/packages/opendesign/src/figure/__docs__/__case__/FigureUsage.vue
@@ -0,0 +1,204 @@
+
+
+
+### 使用说明
+
+#### 属性说明
+
+**`ratio`**: 图片宽高比控制
+
+- 通过 `padding-top` 百分比实现宽高比
+- 子元素使用 `absolute` 定位填充容器。这会覆盖 `
` 元素的固有宽高比特性
+- 基于以上两点必要时显式设置容器宽度,否则容器宽高可能坍塌为 0,导致图片无法显示
+
+**`fit`**: 图片填充模式(默认:`contain`)
+
+- `background=false` 时(使用 `
` 标签):
+ - 通过 [object-fit](https://developer.mozilla.org/zh-CN/docs/Web/CSS/object-fit) 控制
+ - 可选值:`cover` | `contain` | `fill` | `none` | `scale-down`
+- `background=true` 时(使用背景图):
+ - 通过 [background-size](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-size) 控制
+ - 可选值:`cover` | `contain` | `auto` | `` | ``
+ - 示例:`fit="100% 80%"` 可设置自定义背景图尺寸
+ - 注意:由于不再使用 `
` 标签渲染,可能导致宽高塌陷
+
+**`hoverable`**: 悬停放大效果
+
+- 自动生效场景(无需显式设置该属性):
+ - `href` 存在时(链接跳转)
+ - `preview=true`(图片预览)
+ - `videoPoster=true`(视频海报)
+- 当需要**独立控制**悬停效果时使用
+
+**`preview`**: 点击预览功能,启用后会接管点击事件(显示全屏预览层)
+
+**`previewClose`**: 预览关闭方式
+
+- 可选值:
+ - `'none'`:禁用关闭
+ - `'mask'`:点击遮罩层关闭
+ - `'button'`:点击关闭按钮
+ - `'body'`:点击预览图片关闭
+- 组合模式:支持数组配置(如 `['mask','button']`)
+- 默认值:
+ - 📱 Pad 端(视口 < 1200px 的触屏设备):`['mask','button']`
+ - 💻 PC 端:`['mask','button','body']`
+
+**`href`**: 链接跳转
+
+- 启用后组件渲染为 `` 标签
+- 行为:点击执行页面跳转
+
+#### 互斥属性冲突
+
+`preview`, `href` **禁止同时启用**(两者均会接管点击事件)
+
+
+
+### Usage Instructions
+
+#### Property Description
+
+**`ratio`**: Controls the aspect ratio of the image
+
+- Achieved via `padding-top` percentage
+- Child elements use `absolute` positioning to fill the container.
+ This overrides the intrinsic aspect ratio characteristics of the `
` element.
+- Based on the above two points, explicitly set the container width when necessary.
+ Otherwise, the container's width and height may collapse to 0, causing the image to fail to display.
+
+**`fit`**: Image fill mode (Default: `contain`)
+
+- When `background=false` (uses `
` tag):
+ - Controlled via [object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit)
+ - Optional values: `cover` | `contain` | `fill` | `none` | `scale-down`
+- When `background=true` (uses background image):
+ - Controlled via [background-size](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size)
+ - Optional values: `cover` | `contain` | `auto` | `` | ``
+ - Example: `fit="100% 80%"` can be used to set a custom background image size
+ - Note: Since the `
` tag is no longer used for rendering, this may cause width and height collapse.
+
+**`hoverable`**: Hover zoom effect
+
+- Automatically enabled scenarios (no need to explicitly set this property):
+ - When `href` is present (link navigation)
+ - When `preview=true` (image preview)
+ - When `videoPoster=true` (video poster)
+- Use when you need to **independently control** the hover effect.
+
+**`preview`**: Click-to-preview functionality. When enabled, it takes over the click event (displays a full-screen preview layer).
+
+**`previewClose`**: Preview close method
+
+- Optional values:
+ - `'none'`: Disable closing
+ - `'mask'`: Click the mask layer to close
+ - `'button'`: Click the close button
+ - `'body'`: Click the preview image to close
+- Combination mode: Supports array configuration (e.g., `['mask','button']`)
+- Default values:
+ - 📱 Pad side (touch screen devices with viewport < 1200px): `['mask','button']`
+ - 💻 PC side: `['mask','button','body']`
+
+**`href`**: Link navigation
+
+- When enabled, the component renders as an `` tag
+- Behavior: Clicking performs page navigation.
+
+#### Mutually Exclusive Property Conflict
+
+The `preview` and `href` properties **cannot be enabled simultaneously** (both would take over the click event).
+
+
diff --git a/packages/opendesign/src/figure/__docs__/__case__/HandlePreview.vue b/packages/opendesign/src/figure/__docs__/__case__/HandlePreview.vue
new file mode 100644
index 0000000000000000000000000000000000000000..58c06f1ee10bdeb021f31b4e8f9f7ba5a1b7569b
--- /dev/null
+++ b/packages/opendesign/src/figure/__docs__/__case__/HandlePreview.vue
@@ -0,0 +1,57 @@
+
+
+
+### 手动控制预览
+
+通过调用 `OFigure` 实例的 `preview(boolean)` 方法,可以手动控制预览的显示与隐藏。注意:
+
+- 设置 `lazy-preview` 属性为 `true` 以启用预览功能
+- 可以设置 `preview-close="none"` 属性禁用默认关闭行为,然后通过 `preview(false)` 方法自定义关闭预览的方式
+
+
+
+### Manual Preview Control
+
+You can manually control the display and hiding of the preview by calling the `preview(boolean)` method of the `OFigure` instance. Note:
+
+- Set the `lazy-preview` attribute to `true` to enable the preview functionality
+- You can set the `preview-close="none"` attribute to disable the default close behavior,
+ and then use the `preview(false)` method to customize how the preview is closed
+
+
+
+ Open preview
+
+
+
+
+
+
+
diff --git a/packages/opendesign/src/figure/__docs__/__case__/LazyLoad.vue b/packages/opendesign/src/figure/__docs__/__case__/LazyLoad.vue
new file mode 100644
index 0000000000000000000000000000000000000000..6b381363749946c13f8e400afc018754d95546c2
--- /dev/null
+++ b/packages/opendesign/src/figure/__docs__/__case__/LazyLoad.vue
@@ -0,0 +1,75 @@
+
+
+
+### 图片懒加载
+
+通过设置`lazy`属性,可以开启图片懒加载。
+
+- 当 `background` 属性为假时,组件使用 `
` 标签渲染图片,此时使用的是 `
` 原生的懒加载,`lazy` 取值为 `true` 或 `false`
+- 当 `background` 属性为真时,组件以背景图的形式渲染图片,此时使用 `IntersectionObserver` 处理懒加载,`lazy` 取值为 `true` 或 `false` 或 `IntersectionObserverInit` 对象
+
+```ts
+/** new IntersectionObserver(callback, options?: IntersectionObserverInit) */
+interface IntersectionObserverInit {
+ root?: Element | Document | null;
+ rootMargin?: string;
+ threshold?: number | number[];
+}
+```
+
+
+
+### Image Lazy Loading
+
+Lazy loading for images can be enabled by setting the `lazy` attribute.
+
+- When the `background` attribute is `false`, the component uses the `
` tag to render the image.
+ In this case, the native lazy loading of the `
` tag is used, and the `lazy` attribute accepts values of `true` or `false`.
+- When the `background` attribute is `true`, the component renders the image as a background image.
+ In this case, `IntersectionObserver` is used to handle lazy loading, and the `lazy` attribute accepts values of `true`, `false`,
+ or an `IntersectionObserverInit` object.
+
+```ts
+/** new IntersectionObserver(callback, options?: IntersectionObserverInit) */
+interface IntersectionObserverInit {
+ root?: Element | Document | null;
+ rootMargin?: string;
+ threshold?: number | number[];
+}
+```
+
+
+
+
+
+
diff --git a/packages/opendesign/src/figure/__docs__/__case__/LoadError.vue b/packages/opendesign/src/figure/__docs__/__case__/LoadError.vue
new file mode 100644
index 0000000000000000000000000000000000000000..f805ae33a31158480ad9382a94ee1f0f07a64349
--- /dev/null
+++ b/packages/opendesign/src/figure/__docs__/__case__/LoadError.vue
@@ -0,0 +1,39 @@
+
+
+
+### 加载失败
+
+- 可通过 `error` 事件监听加载失败事件,`load` 事件监听加载成功事件
+- 可通过 `error` 插槽自定义失败内容
+
+注意:图片加载失败时,可能导致元素宽度及高度坍塌,可显示设置宽高或 `ratio`。
+
+
+
+### Loading Failure
+
+- The `error` event can be used to listen for loading failure events, and the `load` event can be used to listen for successful loading events
+- Custom failure content can be defined through the `error` slot
+
+Note: When image loading fails, it may cause the element's width and height to collapse.
+Explicitly set the width and height or use the `ratio` attribute to prevent this.
+
+
+
+
+
+
+ FAILED
+
+
+
diff --git a/packages/opendesign/src/figure/__docs__/__case__/VideoPoster.vue b/packages/opendesign/src/figure/__docs__/__case__/VideoPoster.vue
new file mode 100644
index 0000000000000000000000000000000000000000..5b2b88e7be5fbca5fd482d7d3491f933b7de47d5
--- /dev/null
+++ b/packages/opendesign/src/figure/__docs__/__case__/VideoPoster.vue
@@ -0,0 +1,51 @@
+
+
+
+### 视频海报
+
+设置 `OFigure` 组件的 `videoPoster` 属性为 `true`,开启视频海报模式:
+
+- 自动添加中心播放图标
+- 自动启用悬停放大效果
+
+#### 自定义预览内容
+
+- 设置组件的 `preview` 属性为 `true` 开启预览功能
+- 使用 `preview` 插槽自定义预览内容(如:视频播放界面)
+- 使用 `preview-extra` 插槽可添加预览区域底部内容(例如:播放控制按钮)
+
+
+
+### Video Poster
+
+Set the `videoPoster` property of the `OFigure` component to `true` to enable video poster mode:
+
+- Automatically adds a center play icon
+- Automatically enables the hover zoom effect
+
+#### Custom Preview Content
+
+- Set the component's `preview` property to `true` to enable the preview functionality
+- Use the `preview` slot to customize the preview content (e.g., video playback interface)
+- Use the `preview-extra` slot to add content at the bottom of the preview area (e.g., playback control buttons)
+
+
+
+
+
+
+
+
+
+
diff --git a/packages/opendesign/src/figure/__docs__/index.en-US.md b/packages/opendesign/src/figure/__docs__/index.en-US.md
new file mode 100644
index 0000000000000000000000000000000000000000..a965beddc26702acf61b483443f1fde18639c8b3
--- /dev/null
+++ b/packages/opendesign/src/figure/__docs__/index.en-US.md
@@ -0,0 +1,39 @@
+---
+sidebar: OFigure
+kind: display
+---
+
+# OFigure
+
+## Demo
+
+
+
+
+
+
+
+### Card
+
+- The image title can be rendered through the `title` or `content` slot
+- Cards containing text content can be rendered through the `default` slot
+
+For details: [Image-Only Card](/en-US/components/card#image-only-card?__skin=a)
+
+
+
+### API
+
+#### CSS Variable
+
+| CSS Variable | Description |
+| --- | --- |
+| \-\-figure-padding-top | The percentage of the container's width that determines the image height, corresponding to the `ratio` value |
+| \-\-figure-fit | Value corresponding to the `fit` property (recommended to set via the `fit` attribute) |
+| \-\-figure-position | Image display position, used to assign values to the `background-position` or `object-position` property |
+| \-\-figure-radius | Image border radius |
+| \-\-figure-error-color | Text color for the error message when image loading fails |
+| \-\-figure-error-size | Text size or icon size for the error prompt when image loading fails |
+| \-\-figure-play-icon-size | Play icon size |
+
+
diff --git a/packages/opendesign/src/figure/__docs__/index.zh-CN.md b/packages/opendesign/src/figure/__docs__/index.zh-CN.md
new file mode 100644
index 0000000000000000000000000000000000000000..11ad943742b2eceacc382f483dcf7c27c3c0bcb2
--- /dev/null
+++ b/packages/opendesign/src/figure/__docs__/index.zh-CN.md
@@ -0,0 +1,39 @@
+---
+sidebar: OFigure 图片
+kind: display
+---
+
+# OFigure 图片
+
+## 示例
+
+
+
+
+
+
+
+### 卡片
+
+- 通过 `title` 或 `content` 插槽可以渲染图片标题
+- 通过 `default` 插槽可以渲染含有文案的卡片。
+
+详见:[纯图卡片](/zh-CN/components/card#纯图卡片?_skin=a)
+
+
+
+### API
+
+#### CSS 变量
+
+| CSS 变量 | 描述 |
+| --- | --- |
+| \-\-figure-padding-top | `ratio` 值对应的图片高度占容器宽度的比例 |
+| \-\-figure-fit | `fit` 属性对应的值(建议通过 `fit` 属性设置) |
+| \-\-figure-position | 图片显示位置,用于给 `background-position` 或 `object-position` 属性赋值 |
+| \-\-figure-radius | 图片圆角 |
+| \-\-figure-error-color | 图片加载失败时的提示文案颜色 |
+| \-\-figure-error-size | 图片加载失败时的提示文字大小或图标大小 |
+| \-\-figure-play-icon-size | 播放图标大小 |
+
+
diff --git a/packages/opendesign/src/figure/types.ts b/packages/opendesign/src/figure/types.ts
index 0955b8ebbba2b57577ebaff9a098a0fe1a86aebe..1a6ed3c76456dabe42a865e85f0a2495606b53f9 100644
--- a/packages/opendesign/src/figure/types.ts
+++ b/packages/opendesign/src/figure/types.ts
@@ -4,86 +4,93 @@ type PreviewCloseType = 'none' | 'button' | 'mask' | 'body';
export const figureProps = {
/**
- * 地址
+ * @zh-CN 资源地址
+ * @en-US Resource address
*/
src: {
type: String,
- required: true,
+ required: true as const,
},
/**
- * 长宽比
+ * @zh-CN 宽高比
+ * @en-US Width/height ratio
*/
ratio: {
type: Number,
},
/**
- * 填充方式 cover | contain | fill | none | scale-down
+ * @zh-CN 图片填充方式 (cover | contain | fill | none | scale-down)
+ * @en-US Image fill mode (cover | contain | fill | none | scale-down)
*/
fit: {
type: String,
},
/**
- * img alt
+ * @zh-CN 图片描述,同 img 的 alt 属性
+ * @en-US Image description, same as the alt attribute of img element
*/
alt: {
type: String,
},
/**
- * 使用背景
+ * @zh-CN 使用背景展示图片而非img元素
+ * @en-US Use background to display image instead of img element
*/
background: {
type: Boolean,
},
/**
- * 可hover
+ * @zh-CN 鼠标悬停时图片放大
+ * @en-US Mouse hover to zoom image
*/
hoverable: {
type: Boolean,
},
/**
- * 链接跳转
+ * @zh-CN 点击图片时跳转链接
+ * @en-US Click image to jump link
*/
href: {
type: String,
},
/**
- * 预置随机多彩背景
+ * @zh-CN 图片加载完成前显示的预制随机多彩背景
+ * @en-US Show a colorful background before the image is loaded
*/
colorful: {
type: Boolean,
},
/**
- * 预览
+ * @zh-CN 是否可点击预览
+ * @en-US Whether clickable preview
*/
preview: {
type: Boolean,
},
/**
- * 支持通过实例接口调用预览
+ * @zh-CN 是否支持调用实例接口进行预览
+ * @en-US Whether to support calling instance interface to preview
*/
lazyPreview: {
type: Boolean,
},
/**
- * 视频预览图
+ * @zh-CN 是否将组件渲染为视频海报(具有视频播放按钮,鼠标hover放大图片等效果)
+ * @en-US Whether to render the component as a video poster (with video play button, mouse hover to zoom image effect)
*/
videoPoster: {
type: Boolean,
},
/**
- * 关闭预览方式
+ * @zh-CN 预览关闭方式,'none' 表示使用默认关闭方式,'button'表示点击按钮关闭,'mask'表示点击遮罩关闭,'body'表示点击预览图片关闭
+ * @en-US Preview close method. 'none' means use default close method, 'button' means close by clicking button, 'mask' means close by clicking mask, 'body' means close by clicking preview image
*/
previewClose: {
type: [String, Array] as PropType,
},
/**
- * 图片懒加载
- * [false]: 立即加载
- * [true]: 启用懒加载,根据与视口的位置关系判断是否加载图片
- * 1. background为false时,使用原生img loading=lazy判断是否加载
- * 2. background为true时,使用IntersectionObserver检测是否进入视口,加载图片
- * [IntersectionObserverInit]: { root, rootMargin, threshold },指定使用IntersectionObserver检测是否进入视口
- * 配置参见 https://developer.mozilla.org/zh-CN/docs/Web/API/IntersectionObserver/IntersectionObserver
+ * @zh-CN 图片懒加载配置项,false表示不使用懒加载,true表示启用懒加载,对象表示IntersectionObserverInit配置项。
+ * @en-US Image lazy loading configuration item, false means not to use lazy loading, true means to enable lazy loading, object means IntersectionObserverInit configuration item.
*/
lazy: {
type: [Boolean, Object] as PropType,