拨动器／Toggle

# 拨动器／Toggle

<p class="uk-text-lead">通过拨动器隐藏或切换内容，或者是更改各种内容的外观样式。</p>

## Usage-用法

要应用此组件，只需将 `uk-toggle="target: #ID"` 属性添加到 `<button>` 或 `<a>` 元素。可以在拨动器属性中使用任何选择器。

拨动器按钮可用于对某元素添加或删除一个class或属性。默认情况下，它会添加 `hidden` 属性以隐藏元素。

```html
<button uk-toggle="target: #my-id" type="button"></button>
<p id="my-id"></p>
```

```example
<div>
    <button class="uk-button uk-button-default" type="button" uk-toggle="target: #toggle-usage">Toggle</button>
    <p id="toggle-usage">What's up?</p>
</div>
```

***

## Multiple items-拨动多个元素

您可以同时拨动多个元素。只需将 `target: SELECTOR` 选项添加到 `uk-toggle` 属性并使用一个作用于所有元素的选择器即可。

```html
<button type="button" uk-toggle="target: .my-class"></button>
<p class="my-class"></p>
<p class="my-class"></p>
```

```example
<button class="uk-button uk-button-default" type="button" uk-toggle="target: .toggle">Toggle</button>
<p class="toggle">Hello!</p>
<p class="toggle" hidden>Bazinga!</p>
```

**注意** 在此示例中，我们对其中一个元素添加了 `hidden` 属性，以便仅显示另一项。拨动器将在两个元素之间切换可见状态。

***

## Custom class-自定义class

如果您不想拨动 `hidden` 属性，也可以拨动自定义class。只需将 `cls: CLASS` 选项添加到 `uk-toggle` 属性即可。在下面示例中，我们使用 `.uk-card-primary` class在不同的卡片样式之间进行切换。

```html
<button type="button" uk-toggle="target: #my-id; cls: uk-card-primary"></button>
<p id="my-id" class="uk-card uk-card-default"></p>
```

```example
<button class="uk-button uk-button-default" type="button" uk-toggle="target: #toggle-custom; cls: uk-card-primary">Toggle</button>
<div id="toggle-custom" class="uk-card uk-card-default uk-card-body uk-margin-small">Custom class</div>
```

***

## Animations-动画
拨动器组件允许您在元素切换时添加动画到元素中。只需为animation参数添加一个 [Animation 组件](animation.md) 中的 `.uk-animation-*` class之一。这个class将应用于入场动画和出场动画。如果您喜欢其他动画，只需添加另一个类。

```html
<button type="button" uk-toggle="target: #my-id; animation: uk-animation-fade"></button>
<p id="my-id"></p>
```

```example
<button href="#toggle-animation" class="uk-button uk-button-default" type="button" uk-toggle="target: #toggle-animation; animation: uk-animation-fade">Toggle</button>
<div id="toggle-animation" class="uk-card uk-card-default uk-card-body uk-margin-small">Animation</div>
```

### 多个动画

您还可以使用 [Animation 组件](animation)中的多个动画效果。这样您就可以设置不同的入场和出场动画。

```html
<button type="button" uk-toggle="target: #my-id; animation: uk-animation-slide-left, uk-animation-slide-bottom"></button>
<p id="my-id"></p>
```

```example
<button class="uk-button uk-button-default" type="button" uk-toggle="target: #toggle-animation-multiple; animation:  uk-animation-slide-left, uk-animation-slide-bottom">Toggle</button>
<div id="toggle-animation-multiple" class="uk-card uk-card-default uk-card-body uk-margin-small">Animation</div>
```

### 排队动画

当拨动多个带有动画的元素时，您可能想要等到第一个动画执行结束后再开始第二个元素的动画。要实现这个效果，只需将 `queued: true` 选项添加到 `uk-toggle` 属性即可。

```html
<button type="button" uk-toggle="target: .my-class; animation: uk-animation-fade; queued: true"></button>
<p class="my-class"></p>
<p class="my-class"></p>
```

```example
<button class="uk-button uk-button-default" type="button" uk-toggle="target: .toggle-animation-queued; animation: uk-animation-fade; queued: true; duration: 300">Toggle</button>
<p class="toggle-animation-queued uk-card uk-card-default uk-card-body uk-margin-small">Animation</p>
<p class="toggle-animation-queued uk-card uk-card-primary uk-card-body uk-margin-small" hidden>Animation</p>
```

***

## Modes-模式

拨动器可以以不同方式触发。只需在 `uk-toggle` 属性中添加 `mode` 选项到并应用下列值之一即可。

| Value          | 描述                                                                      |
| :------------- | :------------------------------------------------------------------------------- |
| `hover`        | 切换将在悬停时触发。                                           |
| `click `       | 点击将触发切换。 这是默认值。                |
| `click, hover` | 单击和悬停将触发切换。                                 |
| `media`        | 切换行为取决于视口宽度。 [更多信息](#media)。 |


```html
<button type="button" uk-toggle="target: #my-id; mode: hover"></button>
<p id="my-id"></p>
```

```example
<button class="uk-button uk-button-default" type="button" uk-toggle="target: #toggle-hover; mode: hover">hover</button>
<p id="toggle-hover">What's up?</p>
```

### Media

使用 `media` 模式时，还必须添加 `media` 选项，并设置视口的值。可以添加以像素为单位的数字，例如 `640`或添加断点，例如`@s`, `@m`, `@l` 或 `@xl`。如果没有 `target` 选项，那么拨动器会将切换状态应用于自身。这样它就能根据视口的宽度切换 `cls` 由选项定义的不同状态。

```html
<!-- The primary modifier will only be applied on large screens -->

<div class="uk-card uk-card-default" uk-toggle="cls: uk-card-primary; mode: media; media: @l"></div>
```

```example
<div class="uk-card uk-card-default uk-card-body uk-width-medium" uk-toggle="cls: uk-card-primary; mode: media; media: @l">
    Primary on large screens
</div>
```

**注意** 初始切换状态取决于`cls`选项。 它是空格分隔列表中的第一个给定的类，或者如果设置为`false`，则为`hidden`属性。 如果给出多个类，则仅在状态更改时切换其他类。

***

## Component options-组件选项

这些选项中的任何一个都可以应用于组件属性。用分号分隔多个选项。 [了解更多](javascript.md#component-configuration)

| 选项      | 可用值           | 默认值 | 描述                             |
| :---------- | :-------------- | :------ | :--------------------------------------------- |
| `target`    | String          | `false` | 要拨动的元素的CSS选择器                                                                                                                                         |
| `mode`      | String          | `click` | 触发的行为模式列表，用逗号分隔。 (`hover`, `click`, `media`)                                                                                                      |
| `cls`       | String          | `false` | 正在拨动的class。默认为 `hidden` 属性。                           |
| `media`     | Integer, String | `false` | 在media模式下，可触发拨动器的断点-宽度为整数（例如640) 或断点（例如e.g. @s, @m, @l, @xl）或任何有效的媒体查询（例如(min-width: 900px)）。 |
| `animation` | String          | `false` | 用空格分隔要使用的动画 [animations](animation.md) 名称，元素的隐藏动画用逗号分隔。                |
| `duration`  | Number          | `200`   | 动画持续时间（以毫秒为单位）。                                           |
| `queued`    | Boolean         | `true`  | 按序列切换目标                           |

`target` 是 _Primary_ 的选项，如果它是属性值中的唯一选项，则可以省略其键。

```html
<span uk-toggle=".my-class"></span>
```

***

## JavaScript

了解更多关于 [JavaScript 组件](javascript.md#programmatic-use)的内容。

### 初始化

```js
UIkit.toggle(element, options);
```

### 事件

将在附加了此组件的元素上触发以下事件：

| Name         | 描述                                                              |
| :----------- | :----------------------------------------------------------------------- |
| `beforeshow` | 在显示项目之前触发。可以通过调用 `preventDefault()` 事件来防止显示。 |
| `show`       | 显示一个项目后触发。                                          |
| `shown`      | 项目的显示动画完成后触发。                     |
| `beforehide` | 在隐藏项目之前触发。可以通过调用 `preventDefault()` 事件来防止隐藏。 |
| `hide`       | 在项目的隐藏动画开始后触发。                        |
| `hidden`     | 项目被隐藏后触发。                                           |

### 方法

以下方法可用于该组件：

#### Toggle

```js
UIkit.toggle(element).toggle();
```

拨动拨动器的目标。