Skip to content

feat(Swiper): add modelValue prop and update cardScale documentation #6095

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
wants to merge 4 commits into
base: develop
Choose a base branch
from
+49 −40
Open

feat(Swiper): add modelValue prop and update cardScale documentation #6095

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9858757
feat(Swiper): add modelValue prop and update cardScale documentation
RSS1102 Oct 27, 2025
934d137
docs(Swiper): update documentation header format
RSS1102 Oct 27, 2025
883568f
feat(Swiper): set default value for cardScale prop and update documen…
RSS1102 Oct 27, 2025
9f14fc9
fix(Swiper): remove unused second argument in setup function
RSS1102 Nov 1, 2025
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
17 changes: 10 additions & 7 deletions packages/components/swiper/props.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@

/**
* 该文件为脚本自动生成文件，请勿随意修改。如需修改请联系 PMC
* updated at 2021-12-12 19:17:30
* */

import { TdSwiperProps } from './type';
Expand All @@ -23,10 +22,19 @@ export default {
type: Boolean,
default: true,
},
/** 卡片模式下非当前展示轮播图的缩放比例 */
cardScale: {
type: Number,
default: 210 / 332,
},
/** 当前轮播在哪一项（下标） */
current: {
type: Number,
default: 0,
default: undefined,
},
modelValue: {
type: Number,
default: undefined,
},
/** 当前轮播在哪一项（下标），非受控属性 */
defaultCurrent: {
Expand Down Expand Up @@ -97,11 +105,6 @@ export default {
return ['default', 'card'].includes(val);
},
},
/** 卡片模式下的缩放比例 */
cardScale: {
type: Number,
default: 210 / 332,
},
/** 轮播切换时触发 */
onChange: Function as PropType<TdSwiperProps['onChange']>,
};
19 changes: 10 additions & 9 deletions packages/components/swiper/swiper.en-US.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,25 +2,26 @@

## API


### Swiper Props

name | type | default | description | required
-- | -- | -- | -- | --
animation | String | slide | options：slide/fade | N
animation | String | slide | options: slide/fade | N
autoplay | Boolean | true | \- | N
cardScale | Number | 210/332 | \- | N
current | Number | 0 | `v-model` and `v-model:current` is supported | N
defaultCurrent | Number | 0 | uncontrolled property | N
direction | String | horizontal | options：horizontal/vertical | N
direction | String | horizontal | options: horizontal/vertical | N
duration | Number | 300 | \- | N
height | Number | - | \- | N
interval | Number | 5000 | \- | N
loop | Boolean | true | \- | N
navigation | Object / Slot / Function | - | Typescript：`SwiperNavigation \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/common.ts) | N
stopOnHover | Boolean | true | \- | N
theme | String | light | options：light/dark | N
trigger | String | hover | options：hover/click | N
type | String | default | options：default/card | N
cardScale | Number | 210/332 | scale ratio in card mode | N
theme | String | light | options: light/dark | N
trigger | String | hover | options: hover/click | N
type | String | default | options: default/card | N
onChange | Function | | Typescript：`(current: number, context: { source: SwiperChangeSource }) => void`<br/>[see more ts definition](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/swiper/type.ts)。<br/>`type SwiperChangeSource = 'autoplay' \| 'click' \| 'hover'`<br/> | N

### Swiper Events
Expand All @@ -33,7 +34,7 @@ change | `(current: number, context: { source: SwiperChangeSource })` | [see mor

name | type | default | description | required
-- | -- | -- | -- | --
placement | String | inside | options：inside/outside | N
showSlideBtn | String | always | options：always/hover/never | N
size | String | medium | options：small/medium/large | N
placement | String | inside | options: inside/outside | N
showSlideBtn | String | always | options: always/hover/never | N
size | String | medium | options: small/medium/large | N
type | String | - | Typescript：`SwiperNavigationType` `type SwiperNavigationType = 'dots' \| 'dots-bar' \| 'bars' \| 'fraction'`。[see more ts definition](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/swiper/type.ts) | N
8 changes: 5 additions & 3 deletions packages/components/swiper/swiper.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,15 @@
:: BASE_DOC ::

## API


### Swiper Props

名称 | 类型 | 默认值 | 说明 | 必传
名称 | 类型 | 默认值 | 描述 | 必传
-- | -- | -- | -- | --
animation | String | slide | 轮播切换动画效果类型：滑动、淡入淡出等。可选项：slide/fade | N
autoplay | Boolean | true | 是否自动播放 | N
cardScale | Number | 210/332 | 卡片模式下非当前展示轮播图的缩放比例 | N
current | Number | 0 | 当前轮播在哪一项（下标）。支持语法糖 `v-model` 或 `v-model:current` | N
defaultCurrent | Number | 0 | 当前轮播在哪一项（下标）。非受控属性 | N
direction | String | horizontal | 轮播滑动方向，包括横向滑动和纵向滑动两个方向。可选项：horizontal/vertical | N
Expand All @@ -19,7 +22,6 @@ stopOnHover | Boolean | true | 是否悬浮时停止轮播 | N
theme | String | light | 深色模式和浅色模式。可选项：light/dark | N
trigger | String | hover | 触发切换的方式：悬浮、点击等。可选项：hover/click | N
type | String | default | 样式类型：默认样式、卡片样式。可选项：default/card | N
cardScale | Number | 210/332 | 卡片模式下的缩放比例 | N
onChange | Function | | TS 类型：`(current: number, context: { source: SwiperChangeSource }) => void`<br/>轮播切换时触发。[详细类型定义](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/swiper/type.ts)。<br/>`type SwiperChangeSource = 'autoplay' \| 'click' \| 'hover'`<br/> | N

### Swiper Events
Expand All @@ -30,7 +32,7 @@ change | `(current: number, context: { source: SwiperChangeSource })` | 轮播

### SwiperNavigation

名称 | 类型 | 默认值 | 说明 | 必传
名称 | 类型 | 默认值 | 描述 | 必传
-- | -- | -- | -- | --
placement | String | inside | 导航器位置，位于主体的内侧或是外侧。可选项：inside/outside | N
showSlideBtn | String | always | 何时显示导航器的翻页按钮：始终显示、悬浮显示、永不显示。可选项：always/hover/never | N
Expand Down
27 changes: 12 additions & 15 deletions packages/components/swiper/swiper.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import { defineComponent, ref, computed, watch, isVNode, onMounted, cloneVNode } from 'vue';
import { defineComponent, ref, computed, watch, isVNode, onMounted, cloneVNode, toRefs } from 'vue';
import { ChevronLeftIcon as TdChevronLeftIcon, ChevronRightIcon as TdChevronRightIcon } from 'tdesign-icons-vue-next';

import { useTNodeJSX, useGlobalIcon, usePrefixClass, useChildComponentSlots } from '@tdesign/shared-hooks';
import { useTNodeJSX, useGlobalIcon, usePrefixClass, useChildComponentSlots, useVModel } from '@tdesign/shared-hooks';

import props from './props';
import { SwiperNavigation, SwiperChangeSource } from './type';
Expand All @@ -18,7 +18,7 @@ export default defineComponent({
name: 'TSwiper',
props,
emits: ['update:current'],
setup(props, { emit }) {
setup(props, {}) {
Copy link
Collaborator

@liweijie0812 liweijie0812 Oct 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
setup(props, {}) {
setup(props) {

const prefix = usePrefixClass();
const renderTNodeJSX = useTNodeJSX();

Expand All @@ -30,8 +30,11 @@ export default defineComponent({
let swiperSwitchingTimer = 0;
let isBeginToEnd = false;
let isEndToBegin = false;
const currentIndex = ref(props.current || props.defaultCurrent);
const navActiveIndex = ref(props.current || props.defaultCurrent);

const { current, modelValue } = toRefs(props);
const [currentIndex, setCurrentIndex] = useVModel(current, modelValue, props.defaultCurrent, props.onChange);

const navActiveIndex = ref(currentIndex.value);
const isHovering = ref(false);
const isSwitching = ref(false);
const showArrow = ref(false);
Expand Down Expand Up @@ -129,7 +132,7 @@ export default defineComponent({
const swiperTo = (index: number, context: { source: SwiperChangeSource }) => {
let targetIndex = index % swiperItemLength.value;
navActiveIndex.value = targetIndex;
emit('update:current', targetIndex);
setCurrentIndex(targetIndex, context);
props.onChange?.(targetIndex, context);
isSwitching.value = true;
if (props.animation === 'slide' && swiperItemLength.value > 1 && props.type !== 'card') {
Expand All @@ -140,7 +143,7 @@ export default defineComponent({
clearTimer();
setTimeout(() => {
isEndToBegin = true;
currentIndex.value = 0;
setCurrentIndex(0, context);
}, props.duration);
}
if (currentIndex.value === 0) {
Expand All @@ -150,12 +153,12 @@ export default defineComponent({
clearTimer();
setTimeout(() => {
isBeginToEnd = true;
currentIndex.value = swiperItemLength.value - 1;
setCurrentIndex(swiperItemLength.value - 1, context);
}, props.duration);
}
}
}
currentIndex.value = targetIndex;
setCurrentIndex(targetIndex, context);
};
const clearTimer = () => {
if (swiperTimer) {
Expand Down Expand Up @@ -319,12 +322,6 @@ export default defineComponent({
}
},
);
watch(
() => props.current,
() => {
swiperTo(props.current, { source: 'autoplay' });
},
);

onMounted(() => {
setTimer();
Expand Down
18 changes: 12 additions & 6 deletions packages/components/swiper/type.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,10 @@

/**
* 该文件为脚本自动生成文件，请勿随意修改。如需修改请联系 PMC
* updated at 2021-12-12 19:17:30
* */

import { TNode } from '../common';

export interface TdSwiperProps {
/**
* 轮播切换动画效果类型：滑动、淡入淡出等
Expand All @@ -16,6 +17,11 @@ export interface TdSwiperProps {
* @default true
*/
autoplay?: boolean;
/**
* 卡片模式下非当前展示轮播图的缩放比例
* @default 210/332
*/
cardScale?: number;
/**
* 当前轮播在哪一项（下标）
* @default 0
Expand All @@ -26,6 +32,11 @@ export interface TdSwiperProps {
* @default 0
*/
defaultCurrent?: number;
/**
* 当前轮播在哪一项（下标）
* @default 0
*/
modelValue?: number;
/**
* 轮播滑动方向，包括横向滑动和纵向滑动两个方向
* @default horizontal
Expand Down Expand Up @@ -74,11 +85,6 @@ export interface TdSwiperProps {
* @default default
*/
type?: 'default' | 'card';
/**
* 卡片模式下的缩放比例
* @default 210/332
*/
cardScale?: number;
/**
* 轮播切换时触发
*/
Expand Down
Loading