Switch 开关

表示两种相互对立的状态间的切换，多用于触发「开/关」。

基础用法

绑定 v-model 到一个 Boolean 类型的变量。可以使用 --el-switch-on-color 属性与 --el-switch-off-color 属性来设置开关的背景色。

export function SwitchBasic() {  const [value1, setValue1] = useState(true);  const [value2, setValue2] = useState(true);  return (    <>      <ElSwitch checked={value1} onCheckedChange={setValue1} />      <ElSwitch        checked={value2}        onCheckedChange={setValue2}        style={{ ...ml2, ...greenRed }}      />    </>  );}

尺寸

Open

export function SwitchSizes() {  const [value, setValue] = useState(true);  return (    <>      <ElSwitch        checked={value}        onCheckedChange={setValue}        size="large"        activeText="Open"        inactiveText="Close"      />      <br />      <ElSwitch        checked={value}        onCheckedChange={setValue}        activeText="Open"        inactiveText="Close"      />      <br />      <ElSwitch        checked={value}        onCheckedChange={setValue}        size="small"        activeText="Open"        inactiveText="Close"      />    </>  );}

文字描述

使用active-text属性与inactive-text属性来设置开关的文字描述。使用 inline-prompt 属性来控制文本是否显示在点内。

使用active-text属性与inactive-text属性来设置开关的文字描述。

export function SwitchText() {  const [value1, setValue1] = useState(true);  const [value2, setValue2] = useState(true);  const [value3, setValue3] = useState(true);  const [value4, setValue4] = useState(true);  const [value5, setValue5] = useState(true);  const [value6, setValue6] = useState(true);  return (    <>      <ElSwitch        checked={value1}        onCheckedChange={setValue1}        style={mb2}        activeText="Pay by month"        inactiveText="Pay by year"      />      <br />      <ElSwitch        checked={value2}        onCheckedChange={setValue2}        style={{ ...mb2, ...greenRed }}        activeText="Pay by month"        inactiveText="Pay by year"      />      <br />      <ElSwitch        checked={value3}        onCheckedChange={setValue3}        inlinePrompt        activeText="是"        inactiveText="否"      />      <ElSwitch        checked={value4}        onCheckedChange={setValue4}        style={{ ...ml2, ...greenRed }}        inlinePrompt        activeText="Y"        inactiveText="N"      />      <ElSwitch        checked={value6}        onCheckedChange={setValue6}        style={ml2}        width="60"        inlinePrompt        activeText="超出省略"        inactiveText="超出省略"      />      <ElSwitch        checked={value5}        onCheckedChange={setValue5}        style={{ ...ml2, ...greenRed }}        inlinePrompt        activeText="完整展示多个内容"        inactiveText="多个内容"      />    </>  );}

显示自定义图标

TIP

使用 inactive-icon 和 active-icon 属性来添加图标。您可以传递组件名称的字符串（提前注册）或组件本身是一个 SVG Vue 组件。 Element Plus 提供了一套图标，你可以在 icon 找到它们。

使用 inactive-icon 和 active-icon 属性来添加图标。使用 inline-prompt 属性来控制图标显示在点内。

export function SwitchIcons() {  const [value1, setValue1] = useState(true);  const [value2, setValue2] = useState(true);  return (    <>      <ElSwitch        checked={value1}        onCheckedChange={setValue1}        activeIcon={<Check />}        inactiveIcon={<Close />}      />      <br />      <ElSwitch        checked={value2}        onCheckedChange={setValue2}        style={{ marginTop: 8, marginLeft: 24 }}        inlinePrompt        activeIcon={<Check />}        inactiveIcon={<Close />}      />    </>  );}

扩展的 value 类型

你可以设置 active-value 和 inactive-value 属性，它们接受 Boolean、String 或 Number 类型的值。

export function SwitchCustomValue() {  const [value, setValue] = useState<string>("100");  return (    <ElTooltip content={`Switch value: ${value}`} placement="top">      <span>        <ElSwitch          value={value}          onChange={(next) => setValue(String(next))}          activeValue="100"          inactiveValue="0"          style={greenRed}        />      </span>    </ElTooltip>  );}

禁用状态

设置disabled属性，接受一个Boolean，设置true即可禁用。

export function SwitchDisabled() {  const [value1, setValue1] = useState(true);  const [value2, setValue2] = useState(true);  return (    <>      <ElSwitch checked={value1} onCheckedChange={setValue1} disabled />      <ElSwitch        checked={value2}        onCheckedChange={setValue2}        style={ml2}      />    </>  );}

加载状态

设置loading属性，接受一个Boolean，设置true即加载中状态。

export function SwitchLoading() {  const [value1, setValue1] = useState(true);  const [value2, setValue2] = useState(false);  return (    <>      <ElSwitch checked={value1} onCheckedChange={setValue1} loading />      <ElSwitch        checked={value2}        onCheckedChange={setValue2}        style={ml2}        loading      />    </>  );}

阻止切换

设置beforeChange属性，若返回 false 或者返回 Promise 且被 reject，则停止切换。

export function SwitchBeforeChange() {  const [value1, setValue1] = useState(false);  const [value2, setValue2] = useState(false);  const [loading1, setLoading1] = useState(false);  const [loading2, setLoading2] = useState(false);  const beforeChange1 = (): Promise<boolean> => {    setLoading1(true);    return new Promise((resolve) => {      setTimeout(() => {        setLoading1(false);        message.success("Switch success");        resolve(true);      }, 1000);    });  };  const beforeChange2 = (): Promise<boolean> => {    setLoading2(true);    return new Promise((_, reject) => {      setTimeout(() => {        setLoading2(false);        message.error("Switch failed");        reject(new Error("Error"));      }, 1000);    });  };  return (    <>      <ElSwitch        checked={value1}        onCheckedChange={setValue1}        loading={loading1}        beforeChange={beforeChange1}      />      <ElSwitch        checked={value2}        onCheckedChange={setValue2}        style={ml2}        loading={loading2}        beforeChange={beforeChange2}      />    </>  );}

自定义动作图标 2.3.9

使用 inactive-action-icon 和 active-action-icon 属性来添加图标。

export function SwitchCustomActionIcon() {  const [value1, setValue1] = useState(true);  return (    <ElSwitch      checked={value1}      onCheckedChange={setValue1}      activeActionIcon={<View />}      inactiveActionIcon={<Hide />}    />  );}

自定义操作图标 2.4.4

使用 active-action 和 inactive-action 属性来添加图标。

export function SwitchCustomActionSlot() {  const [value1, setValue1] = useState(true);  return (    <ElSwitch      checked={value1}      onCheckedChange={setValue1}      activeActionContent={<span className="custom-active-action">T</span>}      inactiveActionContent={<span className="custom-inactive-action">F</span>}    />  );}

Switch API

Switch Attributes

属性名	说明	类型	默认值
checked	布尔模式下的选中态	`boolean`	false
value	自定义值模式下的当前值	`boolean` / `string` / `number`	—
active-value	开启时的值，传入即启用自定义值模式	`boolean` / `string` / `number`	true
inactive-value	关闭时的值	`boolean` / `string` / `number`	false
disabled	是否禁用	`boolean`	false
loading	是否处于加载中	`boolean`	false
size	尺寸	`enum`	—
width	开关宽度	`string` / `number`	—
inline-prompt	文字或图标是否显示在圆点内部	`boolean`	false
active-text	开启时的文字	`string`	—
inactive-text	关闭时的文字	`string`	—
active-icon	开启时的图标，优先于 active-text	`Component`	—
inactive-icon	关闭时的图标，优先于 inactive-text	`Component`	—
active-action-icon	圆点上开启态的动作图标	`Component`	—
inactive-action-icon	圆点上关闭态的动作图标	`Component`	—
active-action-content	圆点上开启态的动作内容，优先于 active-action-icon	`ReactNode`	—
inactive-action-content	圆点上关闭态的动作内容，优先于 inactive-action-icon	`ReactNode`	—
name	原生 name 属性	`string`	—
id	原生 id 属性	`string`	—
tabindex	原生 tabindex 属性	`string` / `number`	—
aria-label	无障碍标签	`string`	—
before-change	切换前钩子，返回 false 或 reject 的 Promise 阻止切换	`Function`	—

Switch Events

事件名	说明	参数
onCheckedChange	布尔模式下选中态变化	`Function`
onChange	自定义值模式下值变化	`Function`

Switch Slots

插槽名	说明	React 写法
active	开启态文字/图标内容	`activeContent`
inactive	关闭态文字/图标内容	`inactiveContent`
active-action	开启态动作区内容	`activeActionContent`
inactive-action	关闭态动作区内容	`inactiveActionContent`

Switch Exposes

名称	说明	类型
focus	手动聚焦开关	`Function`
checked	当前是否开启	`boolean`