切换开关

Toggle 用于在两种状态间进行切换。支持常规开关、图标切换以及按钮形态。

基础用法

基础的开关用法，支持 矩形 (Rect) 和 圆形 (Round) 两种外观。

vue

<script setup>
import { ref } from 'vue'

const valueRect = ref(true)
const valueRound = ref(false)
</script>

<template>
  <div class="demo-box">
    <TuiToggle v-model="valueRect" />
    
    <TuiToggle v-model="valueRound" appearance="toggleRound" />
  </div>
</template>

文字描述与内联显示

通过 activeText 和 inactiveText 设置开关的文字描述。结合 inlinePrompt 属性，可以让文字显示在开关内部。

提示：在使用 inlinePrompt 时，建议通过 width 属性设置合适的宽度以容纳文字。

vue

<script setup>
import { reactive, ref } from 'vue'

const state = reactive({
  val1: true,
  val2: false
})
</script>

<template>
  <TuiToggle 
    v-model="state.val1" 
    activeText="开启" 
    inactiveText="关闭" 
  />

  <TuiToggle 
    v-model="state.val2" 
    inlinePrompt 
    :width="70"
    activeText="ON" 
    inactiveText="OFF"
    appearance="toggleRect"
  />
  
  <TuiToggle 
    v-model="state.val1" 
    inlinePrompt 
    :width="100"
    activeText="开启提示" 
    inactiveText="关闭提示"
  />
</template>

图标交互模式

TuiToggle 的强大之处在于它不仅仅是开关，还可以通过 appearance 变身为纯图标切换或图标按钮。

通过 icon 属性传入数组 ['inactiveIcon', 'activeIcon'] 可实现图标切换。

vue

<script setup>
import { ref } from 'vue'
const active = ref(false)
</script>

<template>
  <div class="icon-demo">
    <TuiToggle 
      v-model="active" 
      appearance="icon" 
      :icon="['tui-icon ti-lock', 'tui-icon ti-lock-open']" 
    />

    <TuiToggle 
      v-model="active" 
      appearance="iconPlain" 
      :icon="['tui-icon ti-view-expand', 'tui-icon ti-view-restore']" 
    />
  </div>
</template>

按钮形态

将 appearance 设置为 iconButton，组件将呈现为按钮样式，常用于工具栏或面板控制。

vue

<script setup>
import { ref } from 'vue'
const stared = ref(false)
const locked = ref(true)
</script>

<template>
  <TuiToggle 
    v-model="stared" 
    appearance="iconButton" 
    size="large"
    :icon="['tui-icon ti-star', 'tui-icon tis-star']" 
  />

  <TuiToggle 
    v-model="locked" 
    appearance="iconButton" 
    activeText="已开启"
    inactiveText="已关闭"
    icon="tui-icon ti-lock" 
  />
</template>

尺寸

支持 large, default, small 三种尺寸，适用于不同的布局场景。

vue

<script setup>
import { ref } from 'vue'
const val = ref(true)
</script>

<template>
  <TuiToggle v-model="val" size="large" />
  <TuiToggle v-model="val" size="default" />
  <TuiToggle v-model="val" size="small" />
  
  <TuiToggle v-model="val" appearance="iconButton" icon="tui-icon ti-home" size="large" />
  <TuiToggle v-model="val" appearance="iconButton" icon="tui-icon ti-home" size="small" />
</template>

自定义颜色

可以通过覆盖 CSS 变量来自定义开关在不同状态下的背景色和边框色。

vue

<script setup>
import { ref } from 'vue'
const val = ref(true)
</script>

<template>
  <TuiToggle v-model="val" class="custom-status-toggle" inlinePrompt activeText="Online" />
</template>

<style scoped>
.custom-status-toggle {
  /* 定义默认状态 (关闭) */
  --tui-tgl-bg_def: #909399;
  --tui-tgl-bd_def: #909399;

  /* 定义激活状态 (开启) - 比如改为绿色 */
  --tui-tgl-bg_act: #67c23a;
  --tui-tgl-bd_act: #67c23a;
  
  /* 定义 Hover 状态 */
  --tui-tgl-bg_hov: #a6a9ad;
}
</style>

API 参考

Props

属性名	说明	类型	默认值
modelValue	(v-model) 绑定值	`Boolean`	Required
appearance	外观类型，可选值：`'toggleRect'`, `'toggleRound'`, `'icon'`, `'iconPlain'`, `'iconButton'`	`String`	`'toggleRect'`
size	尺寸，可选值：`'large'`, `'default'`, `'small'`	`String`	`'default'`
activeText	switch 打开时的文字描述	`String`	—
inactiveText	switch 关闭时的文字描述	`String`	—
inlinePrompt	无论图标还是文本是否显示在开关内部（仅 Rect/Round 有效）	`Boolean`	`false`
width	switch 的宽度（像素）	`Number`	—
icon	图标配置。传入字符串代表单图标；传入数组 `[inactive, active]` 代表双图标切换	`String` / `Array`	`['tui-icon ti-toggle-off', 'tui-icon ti-toggle-on']`
disabled	是否禁用	`Boolean`	`false`

Emits

事件名	说明	回调参数
update:modelValue	绑定值变化时触发	`value: boolean`
change	switch 状态发生变化时的回调	`value: boolean`

控制面板开关

TuiToggleControlPanel 是基于 TuiToggle 开发专用于控制全局设置面板显隐的业务组件。它预设了标准的齿轮图标，并封装了与控制面板状态绑定的逻辑，支持灵活的布局和外观配置。

基础用法

默认情况下，它展示为一个朴素的齿轮图标 (iconPlain)。您可以将其配置为按钮样式，或者添加文字标签。

vue

<script setup>
import { ref } from 'vue'

const showPanel = ref(false)
</script>

<template>
  <div class="demo-gap">
    <TuiToggleControlPanel v-model="showPanel" />

    <TuiToggleControlPanel 
      v-model="showPanel" 
      appearance="iconButton" 
    />
    
    <TuiToggleControlPanel 
      v-model="showPanel" 
      appearance="icon" 
      size="large"
    />
  </div>
</template>

标签与布局

通过 showLabel 属性显示文本，支持通过 direction 控制文本相对于图标的位置（水平或垂直）。

vue

<script setup>
import { ref } from 'vue'
const showPanel = ref(false)
</script>

<template>
  <div class="demo-gap">
    <TuiToggleControlPanel 
      v-model="showPanel" 
      showLabel 
      label="系统设置" 
    />

    <TuiToggleControlPanel 
      v-model="showPanel" 
      showLabel 
      direction="v" 
      label="Settings" 
    />
    
    <TuiToggleControlPanel 
      v-model="showPanel" 
      appearance="toggleRound" 
      showLabel 
      label="控制面板"
    />
  </div>
</template>

API 参考

属性名	说明	类型	默认值
modelValue	(v-model) 绑定面板显示状态	`Boolean`	`false`
appearance	外观类型，支持 `iconPlain`, `iconButton`, `icon`, `toggleRound`, `toggleRect`	`String`	`'iconPlain'`
size	尺寸，可选 `default`, `small`, `large`	`String`	`'default'`
icon	自定义图标	`String` / `Array`	`'tui-icon ti-cog'`
showLabel	是否显示文本标签	`Boolean`	`false`
label	文本标签的内容	`String`	`null`
direction	图标与标签的排列方向，可选 `'h'` (水平), `'v'` (垂直)	`String`	`'h'`

3D面板开关

TuiToggleT3DPanel 是基于 TuiToggle 开发专用于控制 Tui3DPanel 组件的开启与关闭。它默认采用双图标切换机制（2D 网格 / 3D 立方体），直观地展示当前视图模式。

基础用法

默认展示为图标切换模式。点击后在 2D 和 3D 图标之间切换。

vue

<script setup>
import { ref } from 'vue'

const is3D = ref(false)
</script>

<template>
  <div class="demo-gap">
    <TuiToggleT3DPanel v-model="is3D" />

    <TuiToggleT3DPanel 
      v-model="is3D" 
      appearance="iconButton" 
      size="large" 
    />
  </div>
</template>

自定义图标与标签

您可以覆盖默认的图标组，或添加辅助说明文字。

vue

<script setup>
import { ref } from 'vue'
const is3D = ref(false)
</script>

<template>
  <div class="demo-gap">
    <TuiToggleT3DPanel 
      v-model="is3D" 
      :icon="['tui-icon ti-tablet', 'tui-icon ti-3d']" 
    />

    <TuiToggleT3DPanel 
      v-model="is3D" 
      showLabel 
      label="3D View" 
    />
    
    <TuiToggleT3DPanel 
      v-model="is3D" 
      showLabel 
      direction="v"
      label="视图模式" 
    />
  </div>
</template>

API 参考

属性名	说明	类型	默认值
modelValue	(v-model) 绑定 3D 面板状态	`Boolean`	`false`
appearance	外观类型，支持 `iconPlain`, `iconButton`, `icon`, `toggleRound`, `toggleRect`	`String`	`'iconPlain'`
size	尺寸，可选 `default`, `small`, `large`	`String`	`'default'`
icon	图标配置，通常传入数组 `[inactive, active]`	`String` / `Array`	`['tui-icon ti-grid', 'tui-icon ti-cube']`
showLabel	是否显示文本标签	`Boolean`	`false`
label	文本标签的内容	`String`	`null`
direction	图标与标签的排列方向，可选 `'h'` (水平), `'v'` (垂直)	`String`	`'h'`

切换开关 ​

基础用法 ​

文字描述与内联显示 ​

图标交互模式 ​

按钮形态 ​

尺寸 ​

自定义颜色 ​

API 参考 ​

Props ​

Emits ​

控制面板开关 ​

基础用法 ​

标签与布局 ​

API 参考 ​

3D面板开关 ​

基础用法 ​

自定义图标与标签 ​

API 参考 ​

切换开关

基础用法

文字描述与内联显示

图标交互模式

按钮形态

尺寸

自定义颜色

API 参考

Props

Emits

控制面板开关

基础用法

标签与布局

API 参考

3D面板开关

基础用法

自定义图标与标签

API 参考