SegmentedButton 分段按钮

分段按钮组件封装了一组按钮,用于提供选项、切换视图或对元素进行排序等。

使用方法

按需导入组件:

import 'mdui/components/segmented-button-group.js';
import 'mdui/components/segmented-button.js';

按需导入组件的 TypeScript 类型:

import type { SegmentedButtonGroup } from 'mdui/components/segmented-button-group.js';
import type { SegmentedButton } from 'mdui/components/segmented-button.js';

使用示例:

Day Week Month
<mdui-segmented-button-group>
  <mdui-segmented-button>Day</mdui-segmented-button>
  <mdui-segmented-button>Week</mdui-segmented-button>
  <mdui-segmented-button>Month</mdui-segmented-button>
</mdui-segmented-button-group>

示例

全宽显示

<mdui-segmented-button-group> 元素上添加 full-width 属性,可使组件占据全部宽度。

单选模式

<mdui-segmented-button-group> 元素上指定 selects 属性为 single,可以实现单选模式。此时 <mdui-segmented-button-group>value 属性值即为当前选中的 <mdui-segmented-button>value 属性的值。

多选模式

<mdui-segmented-button-group> 元素上指定 selects 属性为 multiple,可以实现多选模式。此时 <mdui-segmented-button-group>value 属性值为当前选中的 <mdui-segmented-button>value 属性的值组成的数组。

注意:在多选模式下,<mdui-segmented-button-group>value 属性值为数组,只能通过 JavaScript 属性来读取和设置该值。

图标

<mdui-segmented-button> 元素上,通过设置 iconend-icon 属性,可以在按钮的左侧和右侧添加 Material Icons 图标。另外,也可以通过 iconend-icon slot 在按钮的左侧和右侧添加元素。

<mdui-segmented-button> 元素上,通过添加 selected-icon 属性,可以设置选中状态的 Material Icons 图标。也可以通过 selected-icon slot 进行设置。

<mdui-segmented-button> 元素上,通过设置 href 属性,可以将按钮转换为链接。此时,还可以使用与链接相关的属性,如:downloadtargetrel

禁用及加载中状态

<mdui-segmented-button-group> 元素上,通过添加 disabled 属性,可以禁用整个分段按钮组。

<mdui-segmented-button> 元素上,通过添加 disabled 属性,可以禁用特定按钮;通过添加 loading 属性,可以为特定按钮添加加载中状态。

mdui-segmented-button-group API

属性

HTML 属性JavaScript 属性Reflect类型默认值
full-widthfullWidthbooleanfalse

是否填满父元素宽度

selectsselects'single' | 'multiple'-

分段按钮的可选中状态,默认为不可选中。可选值包括:

  • single:单选
  • multiple:多选
disableddisabledbooleanfalse

是否为禁用状态

requiredrequiredbooleanfalse

提交表单时,是否必须选中

formformstring-

关联的 <form> 元素。此属性值应为同一页面中的一个 <form> 元素的 id

如果未指定此属性,则该元素必须是 <form> 元素的子元素。通过此属性,你可以将元素放置在页面的任何位置,而不仅仅是 <form> 元素的子元素。

namenamestring''

提交表单时的名称,将与表单数据一起提交

valuevaluestring | string[]''

当前选中的 <mdui-segmented-button> 的值。

Note:该属性的 HTML 属性始终为字符串,且仅在 selects="single" 时可以通过 HTML 属性设置初始值。该属性的 JavaScript 属性值在 selects="single" 时为字符串,在 selects="multiple" 时为字符串数组。所以,在 selects="multiple" 时,如果要修改该值,只能通过修改 JavaScript 属性值实现。

defaultValuestring | string[]''

默认选中的值。在重置表单时,将重置为该默认值。该属性只能通过 JavaScript 属性设置

validityValidityState-

表单验证状态对象,具体参见 ValidityState

validationMessagestring-

如果表单验证未通过,此属性将包含提示信息。如果验证通过,此属性将为空字符串

方法

名称参数返回值
checkValidity
boolean

检查表单字段是否通过验证。如果未通过,返回 false 并触发 invalid 事件;如果通过,返回 true

reportValidity
boolean

检查表单字段是否通过验证。如果未通过,返回 false 并触发 invalid 事件;如果通过,返回 true

如果验证未通过,还会在组件上显示验证失败的提示。

setCustomValidity
  • message: string
void

设置自定义的错误提示文本。只要这个文本不为空,就表示字段未通过验证

事件

名称
change

选中的值变更时触发

invalid

表单字段验证未通过时触发

Slots

名称
默认

<mdui-segmented-button> 组件

CSS 自定义属性

名称
--shape-corner

组件的圆角大小。可以指定一个具体的像素值;但更推荐引用设计令牌

mdui-segmented-button API

属性

HTML 属性JavaScript 属性Reflect类型默认值
iconiconstring-

左侧的 Material Icons 图标名。也可以通过 slot="icon" 设置

end-iconendIconstring-

右侧的 Material Icons 图标名。也可以通过 slot="end-icon" 设置

selected-iconselectedIconstring-

选中状态的 Material Icons 图标名。也可以通过 slot="selected-icon" 设置

hrefhrefstring-

链接的目标 URL。

如果设置了此属性,组件内部将渲染为 <a> 元素,并可以使用链接相关的属性。

downloaddownloadstring-

下载链接的目标。

Note:仅在设置了 href 属性时,此属性才有效。

targettarget'_blank' | '_parent' | '_self' | '_top'-

链接的打开方式。可选值包括:

  • _blank:在新窗口中打开链接
  • _parent:在父框架中打开链接
  • _self:默认。在当前框架中打开链接
  • _top:在整个窗口中打开链接

Note:仅在设置了 href 属性时,此属性才有效。

relrel'alternate' | 'author' | 'bookmark' | 'external' | 'help' | 'license' | 'me' | 'next' | 'nofollow' | 'noreferrer' | 'opener' | 'prev' | 'search' | 'tag'-

当前文档与被链接文档之间的关系。可选值包括:

  • alternate:当前文档的替代版本
  • author:当前文档或文章的作者
  • bookmark:永久链接到最近的祖先章节
  • external:引用的文档与当前文档不在同一站点
  • help:链接到相关的帮助文档
  • license:当前文档的主要内容由被引用文件的版权许可覆盖
  • me:当前文档代表链接内容的所有者
  • next:当前文档是系列中的一部分,被引用的文档是系列的下一个文档
  • nofollow:当前文档的作者或发布者不认可被引用的文件
  • noreferrer:不包含 Referer 头。类似于 noopener 的效果
  • opener:如果超链接会创建一个顶级浏览上下文(即 target 属性值为 _blank),则创建一个辅助浏览上下文
  • prev:当前文档是系列的一部分,被引用的文档是系列的上一个文档
  • search:提供一个资源链接,可用于搜索当前文件及其相关页面
  • tag:提供一个适用于当前文档的标签(由给定地址识别)

Note:仅在指定了 href 属性时可用。

autofocusautofocusbooleanfalse

是否在页面加载完成后自动获取焦点

tabindextabIndexnumber-

元素在使用 Tab 键切换焦点时的顺序

disableddisabledbooleanfalse

是否禁用

loadingloadingbooleanfalse

是否处于加载中状态

namenamestring''

按钮的名称,将与表单数据一起提交。

Note:仅在未设置 href 属性时,此属性才有效。

valuevaluestring''

按钮的初始值,将与表单数据一起提交。

Note:仅在未设置 href 属性时,此属性才有效。

typetype'submit' | 'reset' | 'button''button'

按钮的类型。默认类型为 button。可选类型包括:

  • submit:点击按钮会提交表单数据到服务器
  • reset:点击按钮会将表单中的所有字段重置为初始值
  • button:此类型的按钮没有默认行为

Note:仅在未指定 href 属性时,此属性才有效。

formformstring-

关联的 <form> 元素。此属性值应为同一页面中的一个 <form> 元素的 id

如果未指定此属性,则该元素必须是 <form> 元素的子元素。通过此属性,你可以将元素放置在页面的任何位置,而不仅仅是 <form> 元素的子元素。

Note:仅在未指定 href 属性时,此属性才有效。

formactionformActionstring-

指定提交表单的 URL。

如果指定了此属性,将覆盖 <form> 元素的 action 属性。

Note:仅在未指定 href 属性且 type="submit" 时,此属性才有效。

formenctypeformEnctype'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain'-

指定提交表单到服务器的内容类型。可选值包括:

  • application/x-www-form-urlencoded:未指定该属性时的默认值
  • multipart/form-data:当表单包含 <input type="file"> 元素时使用
  • text/plain:HTML5 新增,用于调试

如果指定了此属性,将覆盖 <form> 元素的 enctype 属性。

Note:仅在未指定 href 属性且 type="submit" 时,此属性才有效。

formmethodformMethod'post' | 'get'-

指定提交表单时使用的 HTTP 方法。可选值包括:

  • post:表单数据包含在表单内容中,发送到服务器
  • get:表单数据以 ? 作为分隔符附加到表单的 URI 属性中,生成的 URI 发送到服务器。当表单没有副作用,并且仅包含 ASCII 字符时,使用此方法

如果设置了此属性,将覆盖 <form> 元素的 method 属性。

Note:仅在未设置 href 属性且 type="submit" 时,此属性才有效。

formnovalidateformNoValidatebooleanfalse

如果设置了此属性,表单提交时将不执行表单验证。

如果设置了此属性,将覆盖 <form> 元素的 novalidate 属性。

Note:仅在未设置 href 属性且 type="submit" 时,此属性才有效。

formtargetformTarget'_self' | '_blank' | '_parent' | '_top'-

提交表单后接收到的响应应显示在何处。可选值包括:

  • _self:默认选项,在当前框架中打开
  • _blank:在新窗口中打开
  • _parent:在父框架中打开
  • _top:在整个窗口中打开

如果设置了此属性,将覆盖 <form> 元素的 target 属性。

Note:仅在未设置 href 属性且 type="submit" 时,此属性才有效。

validityValidityState-

表单验证状态对象,具体参见 ValidityState

validationMessagestring-

如果表单验证未通过,此属性将包含提示信息。如果验证通过,此属性将为空字符串

方法

名称参数返回值
click
void

模拟鼠标点击元素

focus
  • options: FocusOptions (可选)
void

将焦点设置到当前元素。

可以传入一个对象作为参数,该对象的属性包括:

  • preventScroll:默认情况下,元素获取焦点后,页面会滚动以将该元素滚动到视图中。如果不希望页面滚动,可以将此属性设置为 true
blur
void

移除当前元素的焦点

checkValidity
boolean

检查表单字段是否通过验证。如果未通过,返回 false 并触发 invalid 事件;如果通过,返回 true

reportValidity
boolean

检查表单字段是否通过验证。如果未通过,返回 false 并触发 invalid 事件;如果通过,返回 true

如果验证未通过,还会在组件上显示验证失败的提示。

setCustomValidity
  • message: string
void

设置自定义的错误提示文本。只要这个文本不为空,就表示字段未通过验证

事件

名称
focus

获得焦点时触发

blur

失去焦点时触发

invalid

表单字段验证未通过时触发

Slots

名称
默认

分段按钮项的文本内容

icon

分段按钮项的左侧图标

selected-icon

选中状态的左侧图标

end-icon

分段按钮项的右侧图标

CSS Parts

名称
button

内部的 <button><a> 元素

icon

左侧的图标

selected-icon

选中状态的左侧图标

end-icon

右侧的图标

label

文本内容

loading

加载中状态的 <mdui-circular-progress> 元素

MDUI文档English简体中文亮色模式暗色模式跟随系统
预设颜色
自选颜色
从壁纸提取颜色
请选择一张壁纸
开发指南
概述 安装 快速入门 TypeScript 支持 IDE 支持 本地化 常见问题
样式
暗色模式 动态配色 文章排版 设计令牌
与框架集成
React Vue Angular
组件
Button 按钮ButtonIcon 图标按钮Fab 浮动操作按钮SegmentedButton 分段按钮Chip 纸片Card 卡片Checkbox 复选框Radio 单选框Switch 开关切换Slider 滑块RangeSlider 范围滑块List 列表Collapse 折叠面板Tabs 选项卡Dropdown 下拉组件Menu 菜单Select 选择框TextField 文本框LinearProgress 线性进度指示器CircularProgress 圆形进度指示器Dialog 对话框Divider 分割线Avatar 头像Badge 徽标Icon 图标Tooltip 工具提示Snackbar 消息条NavigationBar 底部导航栏NavigationDrawer 侧边抽屉栏NavigationRail 侧边导航栏BottomAppBar 底部应用栏TopAppBar 顶部应用栏Layout 布局
工具函数
jq 工具库 dialog alert confirm prompt snackbar getTheme setTheme getColorFromImage setColorScheme removeColorScheme loadLocale setLocale getLocale throttle observeResize breakpoint
独立包
@mdui/icons 图标组件库