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 + + + + 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. + + + + 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,