Bento 轮播

<head>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <title>bento-base-carousel</title>
    <script src="https://cdn.ampproject.org/bento.js"></script>
    <link
      rel="stylesheet"
      type="text/css"
      href="https://cdn.ampproject.org/v0/bento-base-carousel-1.0.css"
    />
    <script
      async
      src="https://cdn.ampproject.org/v0/bento-base-carousel-1.0.js"
    ></script>
    <style>
      body {
        margin: 0;
      }
      bento-base-carousel {
        height: 100vh;
        width: 100vw;
      }
      bento-base-carousel > img {
        width: 100%;
        height: 100%;
        object-fit: cover;
      }
    </style>

</head>

<body>

    <bento-base-carousel id="my-carousel">
      <img
        height="700"
        width="1037"
        src="banana.jpg"
        alt="Example image: banana "
      />
      <img
        height="700"
        width="1037"
        src="bentobox.jpg"
        alt="Example image: bento box"
      />
      <img
        height="700"
        width="1037"
        src="avocado.jpg"
        alt="Example image: avocado"
      />
    </bento-base-carousel>
    <script>
      (async () => {
        const carousel = document.querySelector('#my-carousel');
        await customElements.whenDefined('bento-base-carousel');
        const api = await carousel.getApi();
        // programatically advance to next slide
        api.next();
      })();
    </script>

</body>

一个通用轮播，用于沿水平或垂直轴显示多块类似的内容。该组件的每个直接子项都被视为轮播中的一个项目。这些节点中的每一个也可以有任意子项。轮播由任意数量的项目组成，以及可选的导航箭头，用于向前或向后移动一个项目。如果用户滑动或使用可自定义的箭头按钮，轮播将在项目之间前进。

将 bento-base-carousel 用作 Web 组件或 React 函数组件

↓ Web 组件 ↓ React / Preact

Web 组件

您必须包含每个 Bento 组件所需的 CSS 库，以确保正确加载，然后再添加自定义样式。或使用内联提供的轻量级预升级样式。请参阅布局和样式。

通过 npm 导入

npm install @bentoproject/base-carousel

import {defineElement as defineBentoBaseCarousel} from '@bentoproject/base-carousel';
defineBentoBaseCarousel();

通过 `<script>` 包含

<script type="module" src="https://cdn.ampproject.org/bento.mjs" crossorigin="anonymous"></script>
<script nomodule src="https://cdn.ampproject.org/bento.js" crossorigin="anonymous"></script>
<script type="module" src="https://cdn.ampproject.org/v0/bento-base-carousel-1.0.mjs" crossorigin="anonymous"></script>
<script nomodule src="https://cdn.ampproject.org/v0/bento-base-carousel-1.0.js" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdn.ampproject.org/v0/bento-base-carousel-1.0.css" crossorigin="anonymous">

示例

<head>

<script
      type="module"
      async
      src="https://cdn.ampproject.org/bento.mjs"
    ></script>
    <script nomodule src="https://cdn.ampproject.org/bento.js"></script>
    <link
      rel="stylesheet"
      type="text/css"
      href="https://cdn.ampproject.org/v0/bento-base-carousel-1.0.css"
    />
    <script
      type="module"
      async
      src="https://cdn.ampproject.org/v0/bento-base-carousel-1.0.mjs"
    ></script>
    <script
      nomodule
      async
      src="https://cdn.ampproject.org/v0/bento-base-carousel-1.0.js"
    ></script>
    <style>
      bento-base-carousel,
      bento-base-carousel > div {
        aspect-ratio: 4/1;
      }
      .red {
        background: darkred;
      }
      .blue {
        background: steelblue;
      }
      .green {
        background: seagreen;
      }
    </style>

</head>

<body>

<bento-base-carousel id="my-carousel">
      <div class="red"></div>
      <div class="blue"></div>
      <div class="green"></div>
    </bento-base-carousel>

</body>

交互性和 API 使用

Bento 组件通过其 API 具有高度交互性。通过在文档中包含以下脚本标签，可以访问 bento-base-carousel 组件 API

<head>

<script
      type="module"
      async
      src="https://cdn.ampproject.org/bento.mjs"
    ></script>
    <script nomodule src="https://cdn.ampproject.org/bento.js"></script>
    <link
      rel="stylesheet"
      type="text/css"
      href="https://cdn.ampproject.org/v0/bento-base-carousel-1.0.css"
    />
    <script
      type="module"
      async
      src="https://cdn.ampproject.org/v0/bento-base-carousel-1.0.mjs"
    ></script>
    <script
      nomodule
      async
      src="https://cdn.ampproject.org/v0/bento-base-carousel-1.0.js"
    ></script>
    <style>
      bento-base-carousel,
      bento-base-carousel > div {
        aspect-ratio: 4/1;
      }
      .red {
        background: darkred;
      }
      .blue {
        background: steelblue;
      }
      .green {
        background: seagreen;
      }
    </style>

</head>

<body>

<bento-base-carousel id="my-carousel">
      <div class="red"></div>
      <div class="blue"></div>
      <div class="green"></div>
    </bento-base-carousel>
    <div class="buttons" style="margin-top: 8px">
      <button id="prev-button">Go to previous slide</button>
      <button id="next-button">Go to next slide</button>
      <button id="go-to-button">Go to slide with green gradient</button>
    </div>

    <script>
      (async () => {
        const carousel = document.querySelector('#my-carousel');
        await customElements.whenDefined('bento-base-carousel');
        const api = await carousel.getApi();

        // programatically advance to next slide
        api.next();

        // set up button actions
        document.querySelector('#prev-button').onclick = () => api.prev();
        document.querySelector('#next-button').onclick = () => api.next();
        document.querySelector('#go-to-button').onclick = () =>
          api.goToSlide(2);
      })();
    </script>

</body>

await customElements.whenDefined('bento-base-carousel');
const api = await carousel.getApi();

操作

bento-base-carousel API 允许您执行以下操作

next()

将轮播向前移动 advance-count 个幻灯片。

api.next();

prev()

将轮播向后移动 advance-count 个幻灯片。

api.prev();

goToSlide(index: number)

将轮播移动到由 index 参数指定的幻灯片。注意：index 将被标准化为大于或等于 0 且小于给定幻灯片数量的数字。

api.goToSlide(0); // Advance to first slide.
api.goToSlide(length - 1); // Advance to last slide.

事件

bento-base-carousel API 允许您注册并响应以下事件

slideChange

当轮播显示的索引发生更改时，将触发此事件。新索引可通过 event.data.index 获得。

carousel.addEventListener('slideChange', (e) => console.log(e.data.index));

布局和样式

每个 Bento 组件都有一个小 CSS 库，您必须包含该库以保证正确加载，而不会出现内容偏移。由于基于顺序的特异性，您必须手动确保在任何自定义样式之前包含样式表。

<link
  rel="stylesheet"
  type="text/css"
  href="https://cdn.ampproject.org/v0/bento-base-carousel-1.0.css"
/>

或者，您还可以使轻量级预升级样式内联可用

<style>
  bento-base-carousel {
    display: block;
    overflow: hidden;
    position: relative;
  }
</style>

容器类型

bento-base-carousel 组件具有已定义的布局大小类型。为确保组件正确呈现，请务必通过所需的 CSS 布局（例如使用 height、width、aspect-ratio 或其他此类属性定义的布局）将大小应用于组件及其直接子级（幻灯片）

bento-base-carousel {
  height: 100px;
  width: 100%;
}

bento-base-carousel > * {
  aspect-ratio: 4/1;
}

从右到左的幻灯片更改

<bento-base-carousel> 要求您定义它何时处于从右到左 (rtl) 的上下文中（例如阿拉伯语、希伯来语页面）。虽然轮播通常可以在没有此定义的情况下工作，但可能存在一些错误。您可以按照以下方法让轮播知道它应作为 rtl 运行

<bento-base-carousel dir="rtl" …> … </bento-base-carousel>

如果轮播处于 RTL 上下文中，并且您希望轮播作为 LTR 运行，则可以明确在轮播上设置 dir="ltr"。

幻灯片布局

当不指定 mixed-lengths 时，幻灯片会自动按轮播调整大小。

<bento-base-carousel …>
  <img style="height: 100%; width: 100%" src="…" />
</bento-base-carousel>

当轮播布局时，幻灯片具有隐式高度。这可以通过 CSS 轻松更改。指定高度时，幻灯片将在轮播内垂直居中。

如果您想水平居中幻灯片内容，您将需要创建一个包装元素，并使用它来居中内容。

可见幻灯片数量

在响应媒体查询时使用 visible-slides 更改可见幻灯片数量时，您可能希望更改轮播本身的纵横比以匹配可见幻灯片的新数量。例如，如果您希望以一比一的纵横比一次显示三张幻灯片，那么您将希望轮播本身的纵横比为三比一。类似地，一次显示四张幻灯片时，您将希望纵横比为四比一。此外，在更改 visible-slides 时，您可能希望更改 advance-count。

<!-- Using an aspect ratio of 3:2 for the slides in this example. -->
<bento-base-carousel
  visible-count="(min-width: 600px) 4, 3"
  advance-count="(min-width: 600px) 4, 3"
>
  <img style="height: 100%; width: 100%" src="…" />
  …
</bento-base-carousel>

属性

媒体查询

<bento-base-carousel> 的属性可以配置为根据媒体查询使用不同的选项。

可见幻灯片数量

mixed-length

true 或 false，默认为 false。为 true 时，对每张幻灯片使用现有宽度（或水平方向时的现有高度）。这允许使用具有不同宽度的幻灯片的轮播。

visible-count

一个数字，默认为 1。确定在给定时间内应显示多少张幻灯片。可以使用分数来使部分附加幻灯片可见。当 mixed-length 为 true 时，将忽略此选项。

advance-count

一个数字，默认为 1。确定使用上一个或下一个箭头前进时轮播将前进多少张幻灯片。在指定 visible-count 属性时，这很有用。

自动前进

auto-advance

true 或 false，默认为 false。根据延迟自动将轮播前进到下一张幻灯片。如果用户手动更改幻灯片，则自动前进将停止。请注意，如果未启用 loop，则在到达最后一项时，自动前进将向后移动到第一项。

auto-advance-count

一个数字，默认为 1。确定自动前进时轮播将前进多少张幻灯片。在指定 visible-count 属性时，这很有用。

auto-advance-interval

一个数字，默认为 1000。指定轮播自动前进之间的时间量（以毫秒为单位）。

auto-advance-loops

一个数字，默认为 ∞。轮播在停止前应在幻灯片中前进的次数。

捕捉

snap

true 或 false，默认为 true。确定在滚动时轮播是否应在幻灯片上捕捉。

snap-align

start 或 center。当开始对齐时，幻灯片的开始（例如，水平对齐时的左边缘）与轮播的开始对齐。当居中对齐时，幻灯片的中心与轮播的中心对齐。

snap-by

一个数字，默认为 1。这确定了捕捉的粒度，在使用 visible-count 时很有用。

其他

controls

"always"、"auto" 或 "never"，默认为 "auto"。这确定是否以及何时显示上一个/下一个导航箭头。注意：当 outset-arrows 为 true 时，箭头将显示为 "always"。

always：始终显示箭头。
auto：当轮播最近通过鼠标接收交互时显示箭头，当轮播最近通过触摸接收交互时不显示箭头。在触摸设备上首次加载时，箭头显示，直至首次交互。
never：从不显示箭头。

slide

一个数字，默认为 0。这确定了轮播中显示的初始幻灯片。这可以通过 Element.setAttribute 进行改变，以控制当前显示哪张幻灯片。

loop

为 true 或 false，省略时默认为 false。为 true 时，旋转木马允许用户从第一项移回最后一项，反之亦然。必须至少有 visible-count 的三倍幻灯片才能进行循环。

方向

为 horizontal 或 vertical，默认为 horizontal。当为 horizontal 时，旋转木马将水平布局，用户可以向左和向右滑动。当为 vertical 时，旋转木马将垂直布局，用户可以向上和向下滑动。

样式

你可以使用 bento-base-carousel 元素选择器自由设置旋转木马的样式。

自定义箭头按钮

可以通过传入你自己的自定义标记来自定义箭头按钮。例如，你可以使用以下 HTML 和 CSS 来重新创建默认样式

.carousel-prev,
.carousel-next {
  filter: drop-shadow(0px 1px 2px #4a4a4a);
  width: 40px;
  height: 40px;
  padding: 20px;
  background-color: transparent;
  border: none;
  outline: none;
}

.carousel-prev {
  background-image: url('data:image/svg+xml;charset=utf-8,<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path  d="M14,7.4 L9.4,12 L14,16.6" fill="none" stroke="#fff" stroke-width="2px" stroke-linejoin="round" stroke-linecap="round" /></svg>');
}

.carousel-next {
  background-image: url('data:image/svg+xml;charset=utf-8,<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path  d="M10,7.4 L14.6,12 L10,16.6" fill="none" stroke="#fff" stroke-width="2px" stroke-linejoin="round" stroke-linecap="round" /></svg>');
}

<bento-base-carousel …>
  <div>first slide</div>
  …
  <button slot="next-arrow" class="carousel-next" aria-label="Next"></button>
  <button
    slot="prev-arrow"
    class="carousel-prev"
    aria-label="Previous"
  ></button>
</bento-base-carousel>

Preact/React 组件

通过 npm 导入

npm install @bentoproject/base-carousel

import React from 'react';
import {BentoBaseCarousel} from '@bentoproject/base-carousel/react';
import '@bentoproject/base-carousel/styles.css';

function App() {
  return (
    <BentoBaseCarousel>
      <img src="puppies.jpg" />
      <img src="kittens.jpg" />
      <img src="hamsters.jpg" />
    </BentoBaseCarousel>
  );
}

交互性和 API 使用

Bento 组件通过其 API 具有高度交互性。可以通过传递 ref 来访问 BentoBaseCarousel 组件 API。

import React, {createRef} from 'react';
const ref = createRef();

function App() {
  return (
    <BentoBaseCarousel ref={ref}>
      <img src="puppies.jpg" />
      <img src="kittens.jpg" />
      <img src="hamsters.jpg" />
    </BentoBaseCarousel>
  );
}

操作

BentoBaseCarousel API 允许你执行以下操作

next()

通过 advanceCount 幻灯片向前移动旋转木马。

ref.current.next();

prev()

通过 advanceCount 幻灯片向后移动旋转木马。

ref.current.prev();

goToSlide(index: number)

将轮播移动到由 index 参数指定的幻灯片。注意：index 将被标准化为大于或等于 0 且小于给定幻灯片数量的数字。

ref.current.goToSlide(0); // Advance to first slide.
ref.current.goToSlide(length - 1); // Advance to last slide.

事件

BentoBaseCarousel API 允许你注册并响应以下事件

onSlideChange

当旋转木马显示的索引发生变化时触发此事件。

<BentoBaseCarousel onSlideChange={(index) => console.log(index)}>
  <img src="puppies.jpg" />
  <img src="kittens.jpg" />
  <img src="hamsters.jpg" />
</BentoBaseCarousel>

布局和样式

容器类型

BentoBaseCarousel 组件具有已定义的布局大小类型。为了确保组件正确渲染，请务必通过所需的 CSS 布局（例如使用 height、width、aspect-ratio 或其他此类属性定义的布局）将大小应用于组件及其直接子项（幻灯片）。这些可以内联应用

<BentoBaseCarousel style={{width: 300, height: 100}}>
  <img src="puppies.jpg" />
  <img src="kittens.jpg" />
  <img src="hamsters.jpg" />
</BentoBaseCarousel>

或通过 className

<BentoBaseCarousel className="custom-styles">
  <img src="puppies.jpg" />
  <img src="kittens.jpg" />
  <img src="hamsters.jpg" />
</BentoBaseCarousel>

.custom-styles {
  height: 100px;
  width: 100%;
}

.custom-styles > * {
  aspect-ratio: 4/1;
}

从右到左的幻灯片更改

<BentoBaseCarousel> 要求你在右到左 (rtl) 上下文中定义它（例如阿拉伯语、希伯来语页面）。虽然旋转木马通常可以在没有此项的情况下工作，但可能存在一些错误。你可以让旋转木马知道它应该作为 rtl 运行，如下所示

<BentoBaseCarousel dir="rtl">…</BentoBaseCarousel>

如果轮播处于 RTL 上下文中，并且您希望轮播作为 LTR 运行，则可以明确在轮播上设置 dir="ltr"。

幻灯片布局

当不指定 mixedLengths 时，幻灯片会自动按旋转木马的大小调整。

<BentoBaseCarousel>
  <img style={{height: '100%', width: '100%'}} src="…" />
</BentoBaseCarousel>

当轮播布局时，幻灯片具有隐式高度。这可以通过 CSS 轻松更改。指定高度时，幻灯片将在轮播内垂直居中。

如果您想水平居中幻灯片内容，您将需要创建一个包装元素，并使用它来居中内容。

可见幻灯片数量

在响应媒体查询时，使用 visibleSlides 更改可见幻灯片数量时，你可能希望更改旋转木马本身的宽高比以匹配可见幻灯片的新数量。例如，如果你想一次显示三个幻灯片，且宽高比为一比一，那么你可能希望旋转木马本身的宽高比为三比一。类似地，一次显示四个幻灯片时，你可能希望宽高比为四比一。此外，在更改 visibleSlides 时，你可能希望更改 advanceCount。

const count = window.matchMedia('(max-width: 600px)').matches ? 4 : 3;

<BentoBaseCarousel visibleCount={count} advanceCount={count}>
  <img style={{height: '100%', width: '100%'}} src="…" />…
</BentoBaseCarousel>

属性

可见幻灯片数量

mixedLength

true 或 false，默认为 false。为 true 时，对每张幻灯片使用现有宽度（或水平方向时的现有高度）。这允许使用具有不同宽度的幻灯片的轮播。

visibleCount

一个数字，默认为 1。确定在给定时间应显示多少张幻灯片。可以使用分数值使部分附加幻灯片可见。当 mixedLength 为 true 时，将忽略此选项。

advanceCount

一个数字，默认为 1。确定使用上一个或下一个箭头前进时旋转木马将前进多少张幻灯片。在指定 visibleCount 属性时，这很有用。

自动前进

autoAdvance

autoAdvanceCount

一个数字，默认为 1。确定自动前进时轮播将前进多少张幻灯片。在指定 visible-count 属性时，这很有用。

autoAdvanceInterval

一个数字，默认为 1000。指定轮播自动前进之间的时间量（以毫秒为单位）。

autoAdvanceLoops

一个数字，默认为 ∞。轮播在停止前应在幻灯片中前进的次数。

捕捉

snap

true 或 false，默认为 true。确定在滚动时轮播是否应在幻灯片上捕捉。

snapAlign

start 或 center。当开始对齐时，幻灯片的开始（例如，水平对齐时的左边缘）与轮播的开始对齐。当居中对齐时，幻灯片的中心与轮播的中心对齐。

snapBy

一个数字，默认为 1。这确定了捕捉的粒度，在使用 visible-count 时很有用。

其他

controls

always：始终显示箭头。
auto：当轮播最近通过鼠标接收交互时显示箭头，当轮播最近通过触摸接收交互时不显示箭头。在触摸设备上首次加载时，箭头显示，直至首次交互。
never：从不显示箭头。

defaultSlide

一个数字，默认为 0。这决定了旋转木马中显示的初始幻灯片。

loop

方向

样式

你可以使用 BentoBaseCarousel 元素选择器自由设置旋转木马的样式。

自定义箭头按钮

可以通过传入你自己的自定义标记来自定义箭头按钮。例如，你可以使用以下 HTML 和 CSS 来重新创建默认样式

.carousel-prev,
.carousel-next {
  filter: drop-shadow(0px 1px 2px #4a4a4a);
  width: 40px;
  height: 40px;
  padding: 20px;
  background-color: transparent;
  border: none;
  outline: none;
}

.carousel-prev {
  background-image: url('data:image/svg+xml;charset=utf-8,<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path  d="M14,7.4 L9.4,12 L14,16.6" fill="none" stroke="#fff" stroke-width="2px" stroke-linejoin="round" stroke-linecap="round" /></svg>');
}

.carousel-next {
  background-image: url('data:image/svg+xml;charset=utf-8,<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path  d="M10,7.4 L14.6,12 L10,16.6" fill="none" stroke="#fff" stroke-width="2px" stroke-linejoin="round" stroke-linecap="round" /></svg>');
}

function CustomPrevButton(props) {
  return <button {...props} className="carousel-prev" />;
}

function CustomNextButton(props) {
  return <button {...props} className="carousel-prev" />;
}

<BentoBaseCarousel
  arrowPrevAs={CustomPrevButton}
  arrowNextAs={CustomNextButton}
>
  <div>first slide</div>
  // …
</BentoBaseCarousel>

Bento 轮播

<head>

<body>

Web 组件

通过 npm 导入

通过 <script> 包含

示例

<head>

<body>

交互性和 API 使用

<head>

<body>

操作

next()

prev()

goToSlide(index: number)

事件

slideChange

布局和样式

容器类型

从右到左的幻灯片更改

幻灯片布局

可见幻灯片数量

属性

媒体查询

可见幻灯片数量

mixed-length

visible-count

advance-count

自动前进

auto-advance

auto-advance-count

auto-advance-interval

auto-advance-loops

捕捉

snap

snap-align

snap-by

其他

controls

slide

loop

方向

样式

自定义箭头按钮

Preact/React 组件

通过 npm 导入

交互性和 API 使用

操作

next()

prev()

goToSlide(index: number)

事件

onSlideChange

布局和样式

容器类型

从右到左的幻灯片更改

幻灯片布局

可见幻灯片数量

属性

可见幻灯片数量

mixedLength

visibleCount

advanceCount

自动前进

autoAdvance

autoAdvanceCount

autoAdvanceInterval

autoAdvanceLoops

捕捉

snap

snapAlign

snapBy

其他

controls

defaultSlide

loop

方向

样式

自定义箭头按钮

通过 `<script>` 包含