Skip to content

feat(ImageViewer): add loop prop #855

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
anlyyao wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat(ImageViewer): add loop prop #855

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7bbca04
feat(ImageViewer): add loop prop
anlyyao Apr 24, 2026
436b372
feat(ImageViewer): enriched image slot parameters
anlyyao Apr 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file modified db/TDesign.db
View file
Open in desktop
Binary file not shown.
1 change: 1 addition & 0 deletions ...s/products/tdesign-miniprogram/packages/components/image-viewer/README.en-US.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ image-props | Object | - | `1.12.0`。Typescript: `ImageProps`，[Image API Docu
images | Array | [] | Typescript: `Array<string>` | N
initial-index | Number | 0 | Typescript: `Number` | N
lazy | Boolean | true | `1.9.4` | N
loop | Boolean | true | \- | N
show-index | Boolean | false | \- | N
using-custom-navbar | Boolean | false | `v1.1.4` | N
visible | Boolean | false | hide or show image viewer | N
Expand Down
1 change: 1 addition & 0 deletions packages/products/tdesign-miniprogram/packages/components/image-viewer/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ image-props | Object | - | `1.12.0`。透传至 Image 组件。TS 类型：`Imag
images | Array | [] | 图片数组。TS 类型：`Array<string>` | N
initial-index | Number | 0 | 初始化页码。TS 类型：`Number` | N
lazy | Boolean | true | `1.9.4`。是否开启图片懒加载。开启后会预加载当前图片、相邻图片 | N
loop | Boolean | true | 是否开启循环滚动 | N
show-index | Boolean | false | 是否显示页码 | N
using-custom-navbar | Boolean | false | `v1.1.4`。是否使用了自定义导航栏 | N
visible | Boolean | false | 隐藏/显示预览 | N
Expand Down
5 changes: 5 additions & 0 deletions packages/products/tdesign-miniprogram/packages/components/image-viewer/props.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,11 @@ const props: TdImageViewerProps = {
type: Boolean,
value: true,
},
/** 是否开启循环滚动 */
loop: {
type: Boolean,
value: true,
},
/** 是否显示页码 */
showIndex: {
type: Boolean,
Expand Down
8 changes: 8 additions & 0 deletions packages/products/tdesign-miniprogram/packages/components/image-viewer/type.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,14 @@ export interface TdImageViewerProps {
type: BooleanConstructor;
value?: boolean;
};
/**
* 是否开启循环滚动
* @default true
*/
loop?: {
type: BooleanConstructor;
value?: boolean;
};
/**
* 是否显示页码
* @default false
Expand Down
1 change: 1 addition & 0 deletions ...cts/tdesign-miniprogram/packages/uniapp-components/image-viewer/README.en-US.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ image-props | Object | - | Typescript: `ImageProps`，[Image API Documents](./im
images | Array | [] | Typescript: `Array<string>` | N
initial-index | Number | 0 | Typescript: `Number` | N
lazy | Boolean | true | \- | N
loop | Boolean | true | \- | N
show-index | Boolean | false | \- | N
using-custom-navbar | Boolean | false | \- | N
visible | Boolean | false | hide or show image viewer。`v-model:visible` is supported | N
Expand Down
1 change: 1 addition & 0 deletions .../products/tdesign-miniprogram/packages/uniapp-components/image-viewer/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ image-props | Object | - | 透传至 Image 组件。TS 类型：`ImageProps`，[
images | Array | [] | 图片数组。TS 类型：`Array<string>` | N
initial-index | Number | 0 | 初始化页码。TS 类型：`Number` | N
lazy | Boolean | true | 是否开启图片懒加载。开启后会预加载当前图片、相邻图片 | N
loop | Boolean | true | 是否开启循环滚动 | N
show-index | Boolean | false | 是否显示页码 | N
using-custom-navbar | Boolean | false | 是否使用了自定义导航栏 | N
visible | Boolean | false | 隐藏/显示预览。支持语法糖 `v-model:visible` | N
Expand Down
5 changes: 5 additions & 0 deletions packages/products/tdesign-miniprogram/packages/uniapp-components/image-viewer/props.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,11 @@ export default {
type: Boolean,
default: true,
},
/** 是否开启循环滚动 */
loop: {
type: Boolean,
default: true,
},
/** 是否显示页码 */
showIndex: Boolean,
/** 是否使用了自定义导航栏 */
Expand Down
5 changes: 5 additions & 0 deletions packages/products/tdesign-miniprogram/packages/uniapp-components/image-viewer/type.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,11 @@ export interface TdImageViewerProps {
* @default true
*/
lazy?: boolean;
/**
* 是否开启循环滚动
* @default true
*/
loop?: boolean;
/**
* 是否显示页码
* @default false
Expand Down
1 change: 1 addition & 0 deletions packages/products/tdesign-mobile-react/src/image-viewer/defaultProps.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ export const imageViewerDefaultProps: TdImageViewerProps = {
deleteBtn: false,
images: [],
defaultIndex: 0,
loop: true,
maxZoom: 3,
showIndex: false,
defaultVisible: false,
Expand Down
5 changes: 3 additions & 2 deletions packages/products/tdesign-mobile-react/src/image-viewer/image-viewer.en-US.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,11 @@ style | Object | - | CSS(Cascading Style Sheets)，Typescript: `React.CSSPropert
closeBtn | TNode | true | Typescript: `boolean \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-react/blob/develop/src/common.ts) | N
cover | TElement | - | `0.21.1`。Typescript: `TNode`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-react/blob/develop/src/common.ts) | N
deleteBtn | TNode | false | Typescript: `boolean \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-react/blob/develop/src/common.ts) | N
image | TElement | - | `0.21.1`。Typescript: `TNode<ImageSlotParams>` `interface ImageSlotParams {src: string; className?: string; style?: string; onLoad?: (e: Event) => void; onTransitionstart?: (e: TransitionEvent) => void; onTransitionend?: (e: TransitionEvent) => void;} `。[see more ts definition](https://github.com/Tencent/tdesign-mobile-react/blob/develop/src/common.ts)。[see more ts definition](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/image-viewer/type.ts) | N
images | Array | [] | Typescript: `Array<string \| ImageInfo>` `interface ImageInfo { url: string; align: 'start' \| 'center' \| 'end' }`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/image-viewer/type.ts) | N
image | TElement | - | `0.21.1`。Typescript: `TNode<ImageSlotParams>` `interface ImageSlotParams {src: string; index?: number; extra?: Record<string, any>; className?: string; style?: string; onLoad?: (e: Event) => void; onTransitionstart?: (e: TransitionEvent) => void; onTransitionend?: (e: TransitionEvent) => void;} `。[see more ts definition](https://github.com/Tencent/tdesign-mobile-react/blob/develop/src/common.ts)。[see more ts definition](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/image-viewer/type.ts) | N
images | Array | [] | Typescript: `Array<string \| ImageInfo>` `interface ImageInfo { url: string; align: 'start' \| 'center' \| 'end'; extra?: Record<string, any>}`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/image-viewer/type.ts) | N
index | Number | 0 | \- | N
defaultIndex | Number | 0 | uncontrolled property | N
loop | Boolean | true | \- | N
maxZoom | Number | 3 | \- | N
showIndex | Boolean | false | \- | N
visible | Boolean | false | hide or show image viewer | N
Expand Down
5 changes: 3 additions & 2 deletions packages/products/tdesign-mobile-react/src/image-viewer/image-viewer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,11 @@ style | Object | - | 样式，TS 类型：`React.CSSProperties` | N
closeBtn | TNode | true | 是否展示关闭按钮，值为 `true` 显示默认关闭按钮；值为 `false` 则不显示关闭按钮；也可以完全自定义关闭按钮。TS 类型：`boolean \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-mobile-react/blob/develop/src/common.ts) | N
cover | TElement | - | `0.21.1`。支持自定义覆盖在图片预览最上方的内容。TS 类型：`TNode`。[通用类型定义](https://github.com/Tencent/tdesign-mobile-react/blob/develop/src/common.ts) | N
deleteBtn | TNode | false | 是否显示删除操作，前提需要开启页码。TS 类型：`boolean \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-mobile-react/blob/develop/src/common.ts) | N
image | TElement | - | `0.21.1`。自定义图片内容。TS 类型：`TNode<ImageSlotParams>` `interface ImageSlotParams {src: string; className?: string; style?: string; onLoad?: (e: Event) => void; onTransitionstart?: (e: TransitionEvent) => void; onTransitionend?: (e: TransitionEvent) => void;} `。[通用类型定义](https://github.com/Tencent/tdesign-mobile-react/blob/develop/src/common.ts)。[详细类型定义](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/image-viewer/type.ts) | N
images | Array | [] | 图片数组。TS 类型：`Array<string \| ImageInfo>` `interface ImageInfo { url: string; align: 'start' \| 'center' \| 'end' }`。[详细类型定义](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/image-viewer/type.ts) | N
image | TElement | - | `0.21.1`。自定义图片内容。TS 类型：`TNode<ImageSlotParams>` `interface ImageSlotParams {src: string; index?: number; extra?: Record<string, any>; className?: string; style?: string; onLoad?: (e: Event) => void; onTransitionstart?: (e: TransitionEvent) => void; onTransitionend?: (e: TransitionEvent) => void;} `。[通用类型定义](https://github.com/Tencent/tdesign-mobile-react/blob/develop/src/common.ts)。[详细类型定义](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/image-viewer/type.ts) | N
images | Array | [] | 图片数组。TS 类型：`Array<string \| ImageInfo>` `interface ImageInfo { url: string; align: 'start' \| 'center' \| 'end'; extra?: Record<string, any>}`。[详细类型定义](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/image-viewer/type.ts) | N
index | Number | 0 | 当前预览图片所在的下标 | N
defaultIndex | Number | 0 | 当前预览图片所在的下标。非受控属性 | N
loop | Boolean | true | 是否开启循环滚动 | N
maxZoom | Number | 3 | 【开发中】最大放大比例 | N
showIndex | Boolean | false | 是否显示页码 | N
visible | Boolean | false | 隐藏/显示预览 | N
Expand Down
8 changes: 8 additions & 0 deletions packages/products/tdesign-mobile-react/src/image-viewer/type.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,11 @@ export interface TdImageViewerProps {
* @default 0
*/
defaultIndex?: number;
/**
* 是否开启循环滚动
* @default true
*/
loop?: boolean;
/**
* 【开发中】最大放大比例
* @default 3
Expand Down Expand Up @@ -77,6 +82,8 @@ export interface TdImageViewerProps {

export interface ImageSlotParams {
src: string;
index?: number;
extra?: Record<string, any>;
className?: string;
style?: string;
onLoad?: (e: Event) => void;
Expand All @@ -87,6 +94,7 @@ export interface ImageSlotParams {
export interface ImageInfo {
url: string;
align: 'start' | 'center' | 'end';
extra?: Record<string, any>;
}

export type ImageViewerCloseTrigger = 'image' | 'overlay' | 'close-btn';
5 changes: 3 additions & 2 deletions packages/products/tdesign-mobile-vue/src/image-viewer/image-viewer.en-US.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,11 @@ name | type | default | description | required
closeBtn | Boolean / Slot / Function | true | Typescript: `boolean \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/blob/develop/src/common.ts) | N
cover | Slot / Function | - | `1.12.0`。Typescript: `TNode`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/blob/develop/src/common.ts) | N
deleteBtn | Boolean / Slot / Function | false | Typescript: `boolean \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/blob/develop/src/common.ts) | N
image | Slot / Function | - | `1.12.0`。Typescript: `TNode<ImageSlotParams>` `interface ImageSlotParams {src: string; className?: string; style?: string; onLoad?: (e: Event) => void; onTransitionstart?: (e: TransitionEvent) => void; onTransitionend?: (e: TransitionEvent) => void;} `。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/blob/develop/src/common.ts)。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/image-viewer/type.ts) | N
images | Array | [] | Typescript: `Array<string \| ImageInfo>` `interface ImageInfo { url: string; align: 'start' \| 'center' \| 'end' }`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/image-viewer/type.ts) | N
image | Slot / Function | - | `1.12.0`。Typescript: `TNode<ImageSlotParams>` `interface ImageSlotParams {src: string; index?: number; extra?: Record<string, any>; className?: string; style?: string; onLoad?: (e: Event) => void; onTransitionstart?: (e: TransitionEvent) => void; onTransitionend?: (e: TransitionEvent) => void;} `。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/blob/develop/src/common.ts)。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/image-viewer/type.ts) | N
images | Array | [] | Typescript: `Array<string \| ImageInfo>` `interface ImageInfo { url: string; align: 'start' \| 'center' \| 'end'; extra?: Record<string, any>}`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/image-viewer/type.ts) | N
index | Number | - | `v-model:index` is supported | N
defaultIndex | Number | - | uncontrolled property | N
loop | Boolean | true | \- | N
maxZoom | Number | 3 | \- | N
showIndex | Boolean | false | \- | N
visible | Boolean | false | hide or show image viewer。`v-model` and `v-model:visible` is supported | N
Expand Down
5 changes: 3 additions & 2 deletions packages/products/tdesign-mobile-vue/src/image-viewer/image-viewer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,11 @@
closeBtn | Boolean / Slot / Function | true | 是否展示关闭按钮，值为 `true` 显示默认关闭按钮；值为 `false` 则不显示关闭按钮；也可以完全自定义关闭按钮。TS 类型：`boolean \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-mobile-vue/blob/develop/src/common.ts) | N
cover | Slot / Function | - | `1.12.0`。支持自定义覆盖在图片预览最上方的内容。TS 类型：`TNode`。[通用类型定义](https://github.com/Tencent/tdesign-mobile-vue/blob/develop/src/common.ts) | N
deleteBtn | Boolean / Slot / Function | false | 是否显示删除操作，前提需要开启页码。TS 类型：`boolean \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-mobile-vue/blob/develop/src/common.ts) | N
image | Slot / Function | - | `1.12.0`。自定义图片内容。TS 类型：`TNode<ImageSlotParams>` `interface ImageSlotParams {src: string; className?: string; style?: string; onLoad?: (e: Event) => void; onTransitionstart?: (e: TransitionEvent) => void; onTransitionend?: (e: TransitionEvent) => void;} `。[通用类型定义](https://github.com/Tencent/tdesign-mobile-vue/blob/develop/src/common.ts)。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/image-viewer/type.ts) | N
images | Array | [] | 图片数组。TS 类型：`Array<string \| ImageInfo>` `interface ImageInfo { url: string; align: 'start' \| 'center' \| 'end' }`。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/image-viewer/type.ts) | N
image | Slot / Function | - | `1.12.0`。自定义图片内容。TS 类型：`TNode<ImageSlotParams>` `interface ImageSlotParams {src: string; index?: number; extra?: Record<string, any>; className?: string; style?: string; onLoad?: (e: Event) => void; onTransitionstart?: (e: TransitionEvent) => void; onTransitionend?: (e: TransitionEvent) => void;} `。[通用类型定义](https://github.com/Tencent/tdesign-mobile-vue/blob/develop/src/common.ts)。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/image-viewer/type.ts) | N
images | Array | [] | 图片数组。TS 类型：`Array<string \| ImageInfo>` `interface ImageInfo { url: string; align: 'start' \| 'center' \| 'end'; extra?: Record<string, any>}`。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/image-viewer/type.ts) | N
index | Number | - | 当前预览图片所在的下标。支持语法糖 `v-model:index` | N
defaultIndex | Number | - | 当前预览图片所在的下标。非受控属性 | N
loop | Boolean | true | 是否开启循环滚动 | N
maxZoom | Number | 3 | 【开发中】最大放大比例 | N
showIndex | Boolean | false | 是否显示页码 | N
visible | Boolean | false | 隐藏/显示预览。支持语法糖 `v-model` 或 `v-model:visible` | N
Expand Down
5 changes: 5 additions & 0 deletions packages/products/tdesign-mobile-vue/src/image-viewer/props.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,11 @@ export default {
defaultIndex: {
type: Number,
},
/** 是否开启循环滚动 */
loop: {
type: Boolean,
default: true,
},
/** 【开发中】最大放大比例 */
maxZoom: {
type: Number,
Expand Down
8 changes: 8 additions & 0 deletions packages/products/tdesign-mobile-vue/src/image-viewer/type.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,11 @@ export interface TdImageViewerProps {
* 当前预览图片所在的下标，非受控属性
*/
defaultIndex?: number;
/**
* 是否开启循环滚动
* @default true
*/
loop?: boolean;
/**
* 【开发中】最大放大比例
* @default 3
Expand Down Expand Up @@ -88,6 +93,8 @@ export interface ImageViewerInstanceFunctions {

export interface ImageSlotParams {
src: string;
index?: number;
extra?: Record<string, any>;
className?: string;
style?: string;
onLoad?: (e: Event) => void;
Expand All @@ -98,6 +105,7 @@ export interface ImageSlotParams {
export interface ImageInfo {
url: string;
align: 'start' | 'center' | 'end';
extra?: Record<string, any>;
}

export type ImageViewerCloseTrigger = 'image' | 'overlay' | 'close-btn';
47 changes: 45 additions & 2 deletions packages/scripts/api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73129,7 +73129,7 @@
"create_time": "2025-12-16 18:16:16",
"update_time": "2025-12-16 18:16:16",
"event_output": null,
"custom_field_type": "TNode<ImageSlotParams>【interface ImageSlotParams {src: string; className?: string; style?: string; onLoad?: (e: Event) => void; onTransitionstart?: (e: TransitionEvent) => void; onTransitionend?: (e: TransitionEvent) => void;} 】",
"custom_field_type": "TNode<ImageSlotParams>【interface ImageSlotParams {src: string; index?: number; extra?: Record<string, any>; className?: string; style?: string; onLoad?: (e: Event) => void; onTransitionstart?: (e: TransitionEvent) => void; onTransitionend?: (e: TransitionEvent) => void;} 】",
"syntactic_sugar": null,
"readonly": 1,
"html_attribute": 0,
Expand Down Expand Up @@ -73363,7 +73363,7 @@
"create_time": "2024-05-31 05:07:01",
"update_time": "2024-05-31 05:07:01",
"event_output": null,
"custom_field_type": "Array<string | ImageInfo>【interface ImageInfo { url: string; align: 'start' | 'center' | 'end' }】",
"custom_field_type": "Array<string | ImageInfo>【interface ImageInfo { url: string; align: 'start' | 'center' | 'end'; extra?: Record<string, any>}】",
"syntactic_sugar": null,
"readonly": 1,
"html_attribute": 0,
Expand Down Expand Up @@ -73580,6 +73580,49 @@
"Boolean"
]
},
{
"id": 1777017746,
"platform_framework": [
"8",
"16",
"64",
"128"
],
"component": "ImageViewer",
"field_category": 1,
"field_name": "loop",
"field_type": [
"4"
],
"field_default_value": "true",
"field_enum": "",
"field_desc_zh": "是否开启循环滚动",
"field_desc_en": null,
"field_required": 0,
"event_input": "",
"create_time": "2026-04-24 08:02:26",
"update_time": "2026-04-24 08:02:26",
"event_output": null,
"custom_field_type": null,
"syntactic_sugar": null,
"readonly": 1,
"html_attribute": 0,
"trigger_elements": "",
"deprecated": 0,
"version": "",
"test_description": null,
"support_default_value": 0,
"field_category_text": "Props",
"platform_framework_text": [
"Vue(Mobile)",
"React(Mobile)",
"Miniprogram",
"UniApp"
],
"field_type_text": [
"Boolean"
]
},
{
"id": 2803,
"platform_framework": [
Expand Down