Material Web Select 组件完全指南：下拉菜单的两种形态、表单集成与主题定制

Material Web Select 组件完全指南下拉菜单的两种形态、表单集成与主题定制【免费下载链接】material-webMaterial Design Web Components项目地址: https://gitcode.com/gh_mirrors/ma/material-web导读本文以 Material WebMaterial Design Web Components开源仓库中的md-select组件为主题系统讲解md-outlined-select/md-filled-select两种下拉菜单的用法、required必填校验、md-select-option选项配置、与原生表单的深度集成以及基于 Design Token 的颜色 / 形状 / 字体定制方案。读完本文你将能够直接在项目中搭建符合 Material Design 3 规范的 Select 组件并通过源码理解其字段 菜单的底层实现原理。Select又称下拉菜单 / dropdown menu在 Material Design 3 规范中用于在临时浮层上展示一组选项并在菜单上方展示当前选中的菜单项。在 Material Web 中它被实现为一系列 Web Components与原生 HTMLselect元素定位类似但提供了更丰富的视觉形态filled / outlined、可主题化的 Token 体系以及与表单验证 API 的无缝对接。组件构成三种元素一个整体从仓库源码看Select 功能由三个层面协作完成md-outlined-select/md-filled-select容器组件负责管理选中状态、展开菜单、分发事件与表单联动。公共逻辑集中在 select/internal/select.ts 的抽象类Select中两种形态分别继承它select/internal/filled-select.ts 通过fieldTag literal\md-filled-field 选用填充式字段select/internal/outlined-select.ts 则使用描边式字段。md-select-option单个选项继承自列表项 / 菜单项能力md-list-itemmd-menu-item实现位于 select/internal/selectoption/select-option.ts。内部隐藏的md-menu承载选项浮层Select 通过partmenu暴露其样式入口因此可以使用 menu 组件的 Token 直接定制下拉菜单外观详见下文 Theming 一节。三种元素在render()中被组织为字段 菜单的结构见 select/internal/select.ts外层是带rolecombobox、aria-haspopuplistbox、aria-expanded等 ARIA 属性的字段内层是rolelistbox的md-menu两者通过anchorfield建立定位关联。快速开始引入并注册组件Material Web 的每个组件都提供独立的注册入口。以本项目仓库结构为例直接引入对应源码即可完成自定义元素注册// 方式一按需引入推荐 import ./select/outlined-select.js; import ./select/filled-select.js; import ./select/select-option.js; // 方式二一次性引入全部组件 import ./all.js;注册后即可在 HTML 中使用md-outlined-select、md-filled-select与md-select-optionTypeScript 环境下它们会被写入HTMLElementTagNameMap见 select/outlined-select.ts获得完整的类型提示。基本用法Select 通过md-select-option子元素定义选项列表选项的展示文本放在headline插槽中value属性则是提交到表单或通过select.value读取的值。官方文档给出了两种形态的完整示例md-outlined-select md-select-option aria-labelblank/md-select-option md-select-option selected valueapple div slotheadlineApple/div /md-select-option md-select-option valueapricot div slotheadlineApricot/div /md-select-option /md-outlined-select md-filled-select md-select-option aria-labelblank/md-select-option md-select-option valueapple div slotheadlineApple/div /md-select-option md-select-option valueapricot div slotheadlineApricot/div /md-select-option /md-filled-select几个值得注意的细节空选项占位示例中的第一个md-select-option aria-labelblank/md-select-option是一个空选项。在 select/filled-select.ts 的 JSDoc 示例中同样保留了!-- An empty selected option will give select an un-filled state --注释给一个没有value的空选项加上selected可以让 Select 呈现未填充 / 未选择的初始状态同时避免aria-label缺失导致的辅助技术问题。selected属性标记默认选中项。渲染时 Select 会扫描 DOM 中带有[selected]的选项将其value与displayText同步到字段见下文表单与校验中对initUserSelection()的说明。displayText与typeaheadText当选中的选项展示在字段中时默认取headline插槽文本若需覆盖可在md-select-option上分别设置display-text与typeahead-text默认取 headline 的innerText。源码中由SelectOptionController统一计算select/internal/selectoption/select-option.ts。可选插槽除headline外md-select-option还支持start前导图标、end、overline、supporting-text、trailing-supporting-text等插槽其渲染逻辑见 select/internal/selectoption/select-option.ts。md-select-option自身也支持disabled属性用于禁用单个选项select/internal/selectoption/select-option.ts。Required select必选当选项必须被选择时给 Select 添加required属性即可。字段会随之进入必填视觉状态并在表单校验时阻止未选择值的提交md-filled-select required md-select-option valueone div slotheadlineOne/div /md-select-option md-select-option valuetwo div slotheadlineTwo/div /md-select-option /md-filled-selectrequired属性在源码中由property({type: Boolean})声明并透传给内部字段select/internal/select.ts同时字段的浮动标签在必填状态下默认显示星号*若需隐藏星号可额外添加no-asterisk属性。表单集成与约束校验Select 是标准的表单关联组件通过ElementInternals机制参与表单提交与校验相关能力由labs/behaviors下的混入提供。其基类组合如下select/internal/select.tsconst selectBaseClass mixinDelegatesAria( mixinOnReportValidity( mixinConstraintValidation( mixinFormAssociated(mixinElementInternals(LitElement)), ), ), );由此可以获得表单提交值name属性参与表单提交提交值为当前选中选项的value[getFormValue]()返回this.value见 select/internal/select.ts。约束校验checkValidity()、reportValidity()、setCustomValidity()、validationMessage、willValidate、validity等 API 一应俱全与原生表单校验行为对齐校验逻辑由SelectValidator实现select/internal/select.ts其校验锚点getValidityAnchor指向内部字段保证错误提示定位正确。表单生命周期formResetCallback()调用reset()将选项恢复到[selected]属性标记的默认状态select/internal/select.tsformStateRestoreCallback(state)支持表单状态恢复。错误态error属性强制视觉错误态error-text提供自定义错误文案若errorText为空字符串则继续显示supporting-text。由reportValidity()触发的原生错误文本与手动error状态会叠加显示源码中hasError this.error || this.nativeError。源码中还实现了三类程序化选值的初始化逻辑initUserSelection()select/internal/select.ts优先处理直接设置.value或.selectedIndex的场景否则回退到扫描 DOM 中的[selected]属性。因此在 SSR / 首屏渲染场景下官方建议直接在目标选项上写[selected]并配合display-text而不是设置value属性因为后者会触发一次 DOM 查询见 select/internal/select.ts 中关于value的注释。编程式操作 API方法参数说明select(value)value: string根据选项的value选中对应选项并同步 Select 的valueselectIndex(index)index: number根据选项索引选中对应选项reset()无重置为默认值[selected]标记的状态showPicker()无打开下拉菜单已打开时为空操作checkValidity()无返回元素是否通过约束校验非法时派发invalid事件reportValidity()无校验并报告错误返回是否有效非法时派发可取消的invalid事件setCustomValidity(error)error: string设置自定义校验错误消息非空时validity.customError为true属性方面value、selectedIndex、options、selectedOptions、form、labels、validity、validationMessage、willValidate、disabled、name均可直接读写行为与原生表单控件保持一致。注意md-select仅支持单选selectedOptions的 JSDoc 明确注明 NOTE: md-select only supports single selection。键盘交互与 typeahead 输入Select 内置了完整的键盘导航与边输入边筛选的 typeahead 能力实现在handleKeydown中select/internal/select.ts打开菜单当菜单关闭且非 typeahead 输入中时按下Space、ArrowDown、Enter、End、Home、ArrowUp均可打开菜单其中ArrowUp/Home打开后聚焦第一项End聚焦最后一项其余按键聚焦上次选中项。该行为遵循 WAI-ARIA comboboxselect-only模式。关闭菜单输入菜单未打开时直接输入可打印字符会命中底层菜单的typeaheadController实现输入字母定位匹配项并通过aria-livepolite播报匹配结果会立即反映到字段显示并触发input/change事件。关闭逻辑焦点移出 Select 子树时菜单关闭handleFocusout选项被点击或按可选中键isSelectableKey触发close-menu事件后关闭并提交选中handleCloseMenu见 select/internal/select.ts按Esc则关闭且不改变选中。事件派发任何用户交互导致的选中变化都会派发原生inputbubbles: true, composed: true与changebubbles: true事件select/internal/select.ts。事件一览事件类型BubblesComposed触发时机changeEvent是否用户改变选中项对标原生input的 changeinputInputEvent是是用户改变选中项对标原生input的 inputopeningEvent否否菜单即将打开openedEvent否否菜单动画完成并已打开closingEvent否否菜单即将关闭closedEvent否否菜单动画完成并已关闭常用属性速查属性对应 HTML 属性类型默认值说明quickquickbooleanfalse同步打开菜单、无动画requiredrequiredbooleanfalse是否为必填errorTexterror-textstringerror为真时替换辅助文本的错误消息空串则继续显示辅助文本。优先级高于reportValidity()的消息labellabelstring字段浮动标签noAsteriskno-asteriskbooleanfalse必填时隐藏浮动标签上的星号supportingTextsupporting-textstring字段下方的辅助信息errorerrorbooleanfalse视觉错误状态优先于reportValidity()控制的错误态menuPositioningmenu-positioningabsolute \| fixed \| popoverpopover底层md-menu的定位方式fixed适用于嵌套在存在层叠上下文 / 隐藏溢出的容器如md-dialog中的场景clampMenuWidthclamp-menu-widthbooleanfalse将菜单宽度限制为 Select 的宽度typeaheadDelaytypeahead-delaynumberDEFAULT_TYPEAHEAD_BUFFER_TIMEtypeahead 两次按键之间的最大间隔超过则清空缓冲区常量由menu内部定义hasLeadingIconhas-leading-iconbooleanfalse字段是否有前导图标仅 SSR 使用displayTextdisplay-textstring字段中显示的文本仅 SSR 设置menuAlignmenu-alignstart \| endstart菜单相对文本框的起始 / 结束对齐valuevaluestringundefined当前选中选项的值selectedIndexselected-indexnumberundefined当前选中选项的索引namenamestringundefined表单提交时的 namedisableddisabledbooleanundefined是否禁用前导图标通过leading-icon插槽注入span slotleading-icon…/span尾随图标默认使用内置的下拉箭头 SVG也可用trailing-icon插槽替换select/internal/select.ts。md-select-option选项组件 API属性类型默认值说明disabledbooleanfalse禁用选项不可选中、不可交互selectedbooleanfalse选中视觉状态valuestring选项的表单值typestringoption as const自标识类型typeaheadTextstringundefinedtypeahead 匹配文本未设置时取headline的innerTextdisplayTextstringundefined选中后字段显示的文本未设置时取headline的textContent选项内部通过SelectOptionController与父级 Select 通信向外派发三个自定义事件事件类型Bubbles / Composed触发时机close-menuCustomEvent{initiator, reason, itemPath}是 / 是可关闭的交互点击 / 选中键发生时请求关闭外层菜单request-selectionEvent是 / 是selected变为true时请求父级选中自身单选时取消其他选项request-deselectionEvent是 / 是selected变为false时请求父级取消选中父级Select通过监听request-selection/request-deselection维护单选状态selectItem会先取消其他已选项见 select/internal/select.ts。Theming颜色、字体与形状定制Select 完整支持 Material Design 3 的 theming 体系可通过 CSS 自定义属性Design Token定制颜色、排版与圆角。两种形态的 Token 命名都遵循--md-variant-select-text-field-*前缀默认值全部映射到md-sys-*系统 Token。Filled Select 核心 TokenToken默认值--md-filled-select-text-field-container-color--md-sys-color-surface-container-highest--md-filled-select-text-field-container-shape--md-sys-shape-corner-extra-small--md-filled-select-text-field-input-text-color--md-sys-color-on-surface--md-filled-select-text-field-input-text-font--md-sys-typescale-body-large-font完整 Token 集含 hover / focus / disabled / error 各状态的指示线、图标、标签、辅助文本颜色定义于 tokens/_md-comp-filled-select.scss 的$supported-tokens映射中。Filled Select 定制示例下拉菜单本身是md-menu因此通过::part(menu)使用md-menu的 Token 进行主题化style :root { --md-filled-select-text-field-container-shape: 0px; --md-filled-select-text-field-container-color: #f7faf9; --md-filled-select-text-field-input-text-color: #005353; --md-filled-select-text-field-input-text-font: system-ui; } md-filled-select::part(menu) { --md-menu-container-color: #f4fbfa; --md-menu-container-shape: 0px; } /style md-filled-select md-select-option selected valueapple div slotheadlineApple/div /md-select-option md-select-option valuetomato div slotheadlineTomato/div /md-select-option /md-filled-selectOutlined Select 核心 TokenToken默认值--md-outlined-select-text-field-outline-color--md-sys-color-outline--md-outlined-select-text-field-container-shape--md-sys-shape-corner-extra-small--md-outlined-select-text-field-input-text-color--md-sys-color-on-surface--md-outlined-select-text-field-input-text-font--md-sys-typescale-body-large-font完整 Token 集位于 tokens/_md-comp-outlined-select.scss。Outlined Select 定制示例style :root { --md-outlined-select-text-field-outline-color: #6e7979; --md-outlined-select-text-field-container-shape: 0px; --md-outlined-select-text-field-input-text-color: #005353; --md-outlined-select-text-field-input-text-font: system-ui; } md-outlined-select::part(menu) { --md-menu-container-color: #f4fbfa; --md-menu-container-shape: 0px; } /style md-outlined-select md-select-option selected valueapple div slotheadlineApple/div /md-select-option md-select-option valuetomato div slotheadlineTomato/div /md-select-option /md-outlined-select定制提示Token 值既可以是md-sys-*系统 Token跟随全局主题联动也可以是任意 CSS 值如示例中的具体色值 /0px直角 /system-ui字体。放在:root上可全局生效放在选择器上如md-filled-select { … }则只影响局部组件。深入阅读源码结构导航核心逻辑select/internal/select.ts —— 抽象类Select包含全部属性、键盘交互、typeahead、选择同步、表单联动与事件派发。两种形态select/filled-select.ts、select/outlined-select.ts 及其internal实现仅通过fieldTag切换内部字段组件。选项组件select/internal/selectoption/select-option.ts 与 select/internal/selectoption/selectOptionController.ts。样式与 Token样式入口 select/internal/filled-select-styles.scss / select/internal/outlined-select-styles.scssToken 定义见 tokens/_md-comp-filled-select.scss 与 tokens/_md-comp-outlined-select.scss。测试参考select/select_test.ts 覆盖了选择、校验、键盘与表单行为可作为自定义扩展的行为规范。Demo 与 Harnessselect/demo/demo.ts 提供可视化示例select/harness.ts 是测试驱动交互的 Harness 入口。Material Web 的 Select 组件把原生下拉选择的交互细节键盘导航、typeahead、ARIA、表单校验完整封装进了标准 Web Components 之中同时保留了通过 Token 深度定制的弹性——无论是快速接入一个表单下拉框还是在md-dialog等复杂容器中精确控制浮层定位都能在 select 目录的源码与本文的示例中找到对应答案。【免费下载链接】material-webMaterial Design Web Components项目地址: https://gitcode.com/gh_mirrors/ma/material-web创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考