import * as React from "react"
import { Card, CardContent } from "@/components/ui/card"
import {关于
🌐 About
轮播组件是使用 Embla Carousel 库构建的。
🌐 The carousel component is built using the Embla Carousel library.
安装
🌐 Installation
pnpm dlx shadcn@latest add carousel
用法
🌐 Usage
import {
Carousel,
CarouselContent,
CarouselItem,
CarouselNext,
CarouselPrevious,
} from "@/components/ui/carousel"<Carousel>
<CarouselContent>
<CarouselItem>...</CarouselItem>
<CarouselItem>...</CarouselItem>
<CarouselItem>...</CarouselItem>
</CarouselContent>
<CarouselPrevious />
<CarouselNext />
</Carousel>示例
🌐 Examples
大小
🌐 Sizes
要设置项目的大小，你可以在 <CarouselItem /> 上使用 basis 工具类。
🌐 To set the size of the items, you can use the basis utility class on the <CarouselItem />.
import * as React from "react"
import { Card, CardContent } from "@/components/ui/card"
import {// 33% of the carousel width.
<Carousel>
<CarouselContent>
<CarouselItem className="basis-1/3">...</CarouselItem>
<CarouselItem className="basis-1/3">...</CarouselItem>
<CarouselItem className="basis-1/3">...</CarouselItem>
</CarouselContent>
</Carousel>// 50% on small screens and 33% on larger screens.
<Carousel>
<CarouselContent>
<CarouselItem className="md:basis-1/2 lg:basis-1/3">...</CarouselItem>
<CarouselItem className="md:basis-1/2 lg:basis-1/3">...</CarouselItem>
<CarouselItem className="md:basis-1/2 lg:basis-1/3">...</CarouselItem>
</CarouselContent>
</Carousel>间距
🌐 Spacing
要设置项目之间的间距，我们在 <CarouselItem /> 上使用 pl-[VALUE] 工具，并在 <CarouselContent /> 上使用负 -ml-[VALUE]。
🌐 To set the spacing between the items, we use a pl-[VALUE] utility on the <CarouselItem /> and a negative -ml-[VALUE] on the <CarouselContent />.
import * as React from "react"
import { Card, CardContent } from "@/components/ui/card"
import {<Carousel>
<CarouselContent className="-ml-4">
<CarouselItem className="pl-4">...</CarouselItem>
<CarouselItem className="pl-4">...</CarouselItem>
<CarouselItem className="pl-4">...</CarouselItem>
</CarouselContent>
</Carousel><Carousel>
<CarouselContent className="-ml-2 md:-ml-4">
<CarouselItem className="pl-2 md:pl-4">...</CarouselItem>
<CarouselItem className="pl-2 md:pl-4">...</CarouselItem>
<CarouselItem className="pl-2 md:pl-4">...</CarouselItem>
</CarouselContent>
</Carousel>方向
🌐 Orientation
使用 orientation 属性来设置轮播的方向。
🌐 Use the orientation prop to set the orientation of the carousel.
import * as React from "react"
import { Card, CardContent } from "@/components/ui/card"
import {<Carousel orientation="vertical | horizontal">
<CarouselContent>
<CarouselItem>...</CarouselItem>
<CarouselItem>...</CarouselItem>
<CarouselItem>...</CarouselItem>
</CarouselContent>
</Carousel>选项
🌐 Options
你可以使用 opts 属性向轮播传递选项。有关更多信息，请参见 Embla Carousel 文档。
🌐 You can pass options to the carousel using the opts prop. See the Embla Carousel docs for more information.
<Carousel
opts={{
align: "start",
loop: true,
}}
>
<CarouselContent>
<CarouselItem>...</CarouselItem>
<CarouselItem>...</CarouselItem>
<CarouselItem>...</CarouselItem>
</CarouselContent>
</Carousel>应用编程接口
🌐 API
使用一个状态和 setApi 属性来获取轮播 API 的实例。
🌐 Use a state and the setApi props to get an instance of the carousel API.
"use client"
import * as React from "react"import { type CarouselApi } from "@/components/ui/carousel"
export function Example() {
const [api, setApi] = React.useState<CarouselApi>()
const [current, setCurrent] = React.useState(0)
const [count, setCount] = React.useState(0)
React.useEffect(() => {
if (!api) {
return
}
setCount(api.scrollSnapList().length)
setCurrent(api.selectedScrollSnap() + 1)
api.on("select", () => {
setCurrent(api.selectedScrollSnap() + 1)
})
}, [api])
return (
<Carousel setApi={setApi}>
<CarouselContent>
<CarouselItem>...</CarouselItem>
<CarouselItem>...</CarouselItem>
<CarouselItem>...</CarouselItem>
</CarouselContent>
</Carousel>
)
}事件
🌐 Events
你可以使用来自 setApi 的 api 实例来监听事件。
🌐 You can listen to events using the api instance from setApi.
import { type CarouselApi } from "@/components/ui/carousel"
export function Example() {
const [api, setApi] = React.useState<CarouselApi>()
React.useEffect(() => {
if (!api) {
return
}
api.on("select", () => {
// Do something on select.
})
}, [api])
return (
<Carousel setApi={setApi}>
<CarouselContent>
<CarouselItem>...</CarouselItem>
<CarouselItem>...</CarouselItem>
<CarouselItem>...</CarouselItem>
</CarouselContent>
</Carousel>
)
}有关使用事件的更多信息，请参阅 Embla Carousel 文档。
🌐 See the Embla Carousel docs for more information on using events.
插件
🌐 Plugins
你可以使用 plugins 属性向轮播添加插件。
🌐 You can use the plugins prop to add plugins to the carousel.
import Autoplay from "embla-carousel-autoplay"
export function Example() {
return (
<Carousel
plugins={[
Autoplay({
delay: 2000,
}),
]}
>
// ...
</Carousel>
)
}"use client"
import * as React from "react"从右到左
🌐 RTL
要在 shadcn/ui 中启用 RTL 支持，请参阅 RTL 配置指南。
🌐 To enable RTL support in shadcn/ui, see the RTL configuration guide.
"use client"
import { Card, CardContent } from "@/examples/radix/ui-rtl/card"在为从右到左的语言本地化轮播时，你需要在 opts 属性中设置 direction 选项以匹配文本方向。这可以确保轮播以正确的方向滚动。
🌐 When localizing the carousel for RTL languages, you need to set the direction option in the opts prop to match the text direction. This ensures the carousel scrolls in the correct direction.
<Carousel
dir={dir}
opts={{
direction: dir,
}}
>
<CarouselContent>
<CarouselItem>...</CarouselItem>
<CarouselItem>...</CarouselItem>
<CarouselItem>...</CarouselItem>
</CarouselContent>
<CarouselPrevious className="rtl:rotate-180" />
<CarouselNext className="rtl:rotate-180" />
</Carousel>direction 选项接受 "ltr" 或 "rtl"，并且应与 dir 属性值匹配。你可能还想使用 rtl:rotate-180 类旋转导航按钮，以确保它们指向正确的方向。
🌐 The direction option accepts "ltr" or "rtl" and should match the dir prop value. You may also want to rotate the navigation buttons using the rtl:rotate-180 class to ensure they point in the correct direction.
API参考
🌐 API Reference
有关 props 和插件的更多信息，请参见 Embla Carousel 文档。
🌐 See the Embla Carousel docs for more information on props and plugins.