# 概述 让我们通过 mdui 的 CDN 和一个最简单的页面模板来开始使用 mdui。 > 你正在阅读的是 mdui 2 的文档！ > > 若要阅读 mdui 1 的文档，请访问 [www.mdui.org/docs/](https://www.mdui.org/docs/)。 ## 快速入门 {#getting-started} 使用 mdui 最简单的方式是直接从 CDN 引入 CSS 和 JS 文件。 如果你想使用 npm 安装 mdui，请参考 [安装](/zh-cn/docs/2/getting-started/installation) 章节。 **引入文件** 将下面代码添加到页面的 `` 标签中： ```html ``` 如果你需要使用组件的图标属性（例如 `` 中的 `icon` 属性），则还需要引入图标的 CSS 文件，参见 [使用 Material Icons 图标](/zh-cn/docs/2/components/icon#usage-material-icons)。 mdui 不依赖任何第三方库，引入上述文件后，就能正常工作了。 ## 最简单的页面模板 {#template} 下面是一个最简单的页面模板，你可以在其中添加更多组件和内容，来构建一个网站。 ```html Hello, world! Hello, world! ``` # 安装 你可以选择通过 npm 安装 mdui，或者从 CDN 引入 mdui。推荐使用 npm 进行安装。 ## npm 安装 {#npm} ```bash npm install mdui --save ``` ### 全量导入 {#full-import} 在项目的入口文件中导入下面两个文件，即可使用所有 mdui 组件： ```js import 'mdui/mdui.css'; import 'mdui'; ``` 也可以直接从 mdui 导入需要使用的函数。例如，要导入 [`snackbar`](/zh-cn/docs/2/functions/snackbar) 函数，可以这样做： ```js import { snackbar } from 'mdui'; ``` 显示所有支持从 mdui 导入的函数 
import {
  $,
  dialog,
  alert,
  confirm,
  prompt,
  snackbar,
  getTheme,
  setTheme,
  getColorFromImage,
  setColorScheme,
  removeColorScheme,
  loadLocale,
  setLocale,
  getLocale,
  throttle,
  observeResize,
  breakpoint
} from 'mdui';
 ### 按需导入 {#cherry-picking} 为了优化项目体积，可以仅导入需要的组件和函数。例如，如果你只需要使用 [``](/zh-cn/docs/2/components/button) 组件和 [`snackbar`](/zh-cn/docs/2/functions/snackbar) 函数，可以按照以下方式导入： ```js // CSS 文件始终需要导入 import 'mdui/mdui.css'; // 导入 组件 import 'mdui/components/button.js'; // 导入 snackbar 函数 import { snackbar } from 'mdui/functions/snackbar.js'; ``` 每个组件或函数的文档页面都会详细说明如何进行按需导入。 显示所有支持按需导入的组件和函数 
import 'mdui/components/avatar.js';
import 'mdui/components/badge.js';
import 'mdui/components/bottom-app-bar.js';
import 'mdui/components/button.js';
import 'mdui/components/button-icon.js';
import 'mdui/components/card.js';
import 'mdui/components/checkbox.js';
import 'mdui/components/chip.js';
import 'mdui/components/circular-progress.js';
import 'mdui/components/collapse/collapse.js';
import 'mdui/components/collapse/collapse-item.js';
import 'mdui/components/dialog.js';
import 'mdui/components/divider.js';
import 'mdui/components/dropdown.js';
import 'mdui/components/fab.js';
import 'mdui/components/icon.js';
import 'mdui/components/layout.js';
import 'mdui/components/layout-item.js';
import 'mdui/components/layout-main.js';
import 'mdui/components/linear-progress.js';
import 'mdui/components/list-item.js';
import 'mdui/components/list-subheader.js';
import 'mdui/components/list.js';
import 'mdui/components/menu-item.js';
import 'mdui/components/menu.js';
import 'mdui/components/navigation-bar-item.js';
import 'mdui/components/navigation-bar.js';
import 'mdui/components/navigation-drawer.js';
import 'mdui/components/navigation-rail.js';
import 'mdui/components/navigation-rail-item.js';
import 'mdui/components/radio.js';
import 'mdui/components/radio-group.js';
import 'mdui/components/range-slider.js';
import 'mdui/components/ripple.js';
import 'mdui/components/segmented-button.js';
import 'mdui/components/segmented-button-group.js';
import 'mdui/components/select.js';
import 'mdui/components/slider.js';
import 'mdui/components/snackbar.js';
import 'mdui/components/switch.js';
import 'mdui/components/tab.js';
import 'mdui/components/tab-panel.js';
import 'mdui/components/tabs.js';
import 'mdui/components/text-field.js';
import 'mdui/components/tooltip.js';
import 'mdui/components/top-app-bar-title.js';
import 'mdui/components/top-app-bar.js';
import { $ } from 'mdui/jq.js';
import { alert } from 'mdui/functions/alert.js';
import { breakpoint } from 'mdui/functions/breakpoint.js';
import { confirm } from 'mdui/functions/confirm.js';
import { dialog } from 'mdui/functions/dialog.js';
import { getColorFromImage } from 'mdui/functions/getColorFromImage.js';
import { getLocale } from 'mdui/functions/getLocale.js';
import { getTheme } from 'mdui/functions/getTheme.js';
import { loadLocale } from 'mdui/functions/loadLocale.js';
import { observeResize } from 'mdui/functions/observeResize.js';
import { prompt } from 'mdui/functions/prompt.js';
import { removeColorScheme } from 'mdui/functions/removeColorScheme.js';
import { setColorScheme } from 'mdui/functions/setColorScheme.js';
import { setLocale } from 'mdui/functions/setLocale.js';
import { setTheme } from 'mdui/functions/setTheme.js';
import { snackbar } from 'mdui/functions/snackbar.js';
import { throttle } from 'mdui/functions/throttle.js';
 ## CDN {#cdn} 你可以使用 `` 和 ` 点我 ``` ### 使用 ES 模块构建版本 {#es-module} 下面的例子展示了如何使用 ES 模块构建版本的 mdui。在这个版本中，你可以使用 ES 模块语法从 CDN 导入 mdui： ```html 点我 ``` # 快速入门 mdui 的组件都是标准的 Web Components 组件，你可以像使用 `
` 标签一样使用 mdui 组件。每个组件的文档中都详细描述了其完整的 API，包括属性、方法、事件、slot、CSS Part、CSS 自定义属性等。 本章文档将向你介绍 Web Components 的使用方法。 ## 属性 {#attribute} 属性分为 HTML 属性和 JavaScript 属性，它们通常是一一对应的，并且会保持同步。也就是说，当你更新 HTML 属性值时，JavaScript 属性值也会随之更新；反之亦然。 HTML 属性可以直接在组件的 HTML 字符串中设置，并通过 `getAttribute` 和 `setAttribute` 方法进行读取和修改： ```html 点我 ``` JavaScript 属性则可以直接读取或设置组件实例的属性值： ```html 点我 ``` 某些属性值是 boolean 类型，这些属性的 HTML 属性存在时，JavaScript 属性为 `true`，否则为 `false`。但是，为了兼容某些框架，mdui 会把字符串 `false` 值也判定为 boolean 值 `false`。 ```html ``` 有时属性值是数组、对象或函数，这时只有 JavaScript 属性，没有对应的 HTML 属性，例如 [``](/zh-cn/docs/2/components/slider) 组件的 [`labelFormatter`](/zh-cn/docs/2/components/slider#attributes-labelFormatter) 属性是一个函数，你只能通过 JavaScript 来设置该属性： ```html ``` 下面以 [``](/zh-cn/docs/2/components/slider) 组件属性文档的一部分进行举例说明： | HTML 属性 | JavaScript 属性 | reflect | | --------- | ---------------- | -------------------------------------------------------------------------------------- | | `name` | `name` | | | `value` | `value` | | | | `labelFormatter` | | 这个组件的 `name` 属性具有 HTML 属性和 JavaScript 属性，且 reflect 一栏表明更新 JavaScript 属性时会同步更新 HTML 属性。而 `value` 属性在更新 JavaScript 属性时不会更新 HTML 属性。`labelFormatter` 属性则只有 JavaScript 属性。 ## 方法 {#method} 部分组件提供了公共方法，你可以通过调用这些方法来实现不同的功能。例如，[``](/zh-cn/docs/2/components/text-field) 组件的 [`focus()`](/zh-cn/docs/2/components/text-field#methods-focus) 方法可以使文本框获得焦点。 ```html ``` 可以在各个组件的文档页面查看所有可用的方法及其参数。 ## 事件 {#event} 部分组件在执行特定操作时会触发事件。例如，[``](/zh-cn/docs/2/components/dialog) 组件在打开时会触发 [`open`](/zh-cn/docs/2/components/dialog#events-open) 事件，你可以监听这个事件来执行自定义操作。 ```html Dialog ``` 可以在各个组件的文档页面查看所有可用的事件及其参数。 如果你在其他框架（如 Vue、React、Angular 等）中使用 mdui，你可以使用框架提供的语法来绑定事件。但是，一些框架（如 React）的事件绑定语法只能用于绑定标准事件（如 `click` 事件），而无法用于绑定自定义事件（如 `open` 事件）。因此，在 React 中绑定自定义事件时，你需要先获取元素的引用，然后使用 `addEventListener` 方法来绑定事件。 关于在 React 中使用 mdui 的更多信息，参见 [与框架集成 - React](/zh-cn/docs/2/frameworks/react)。 ## Slot {#slot} 许多组件都提供了 slot，用于将自定义的 HTML 内容插入到组件内部。 最常见的是默认 slot，它是位于组件内部的一段普通 HTML 或纯文本。例如 [``](/zh-cn/docs/2/components/button) 组件的默认 slot 用于设置按钮的文本。示例中的“点我”就是默认 slot 的内容： ```html 点我 ``` 部分组件还提供了具名 slot，具名 slot 需要在 HTML 的 `slot` 属性中指定 slot 名称。下面的示例中，[``](/zh-cn/docs/2/components/icon) 组件指定了 `slot="start"`，表示这是名为 [`start`](/zh-cn/docs/2/components/button#slots-icon) 的具名 slot，即这个图标将被插入到组件内部的左侧： ```html 设置 ``` 如果一个组件使用了多个具名 slot，那么各个具名 slot 之间的顺序并不重要，只要它们位于组件内部，浏览器就会自动将它们放置到正确的位置。 可以在各个组件的文档页面查看所有支持的 Slot。 ## CSS 自定义属性 {#css-custom-properties} CSS 自定义属性是 CSS 中的变量。mdui 定义了一系列[全局 CSS 自定义属性](/zh-cn/docs/2/styles/design-tokens)，这些属性在各个组件内部被引用，因此你可以通过修改这些 CSS 自定义属性来全局修改 mdui 组件的样式。 例如，下面的代码会缩小所有组件的圆角大小： ```css :root { --mdui-shape-corner-extra-small: 0.125rem; --mdui-shape-corner-small: 0.25rem; --mdui-shape-corner-medium: 0.375rem; --mdui-shape-corner-large: 0.5rem; --mdui-shape-corner-extra-large: 0.875rem; } ``` 也可以在局部作用域上修改 CSS 自定义属性。例如，下面的代码只会在含 `class="sharp"` 的元素及其子元素中缩小圆角大小： ```css .sharp { --mdui-shape-corner-extra-small: 0.125rem; --mdui-shape-corner-small: 0.25rem; --mdui-shape-corner-medium: 0.375rem; --mdui-shape-corner-large: 0.5rem; --mdui-shape-corner-extra-large: 0.875rem; } ``` 一些组件还提供了该组件特有的 CSS 自定义属性，这些属性的作用域为特定组件，所以不包含 `--mdui` 前缀。例如，下面的代码通过修改 [``](/zh-cn/docs/2/components/dialog) 组件的 `--z-index` 属性，实现了修改 `z-index` 样式： ```css mdui-dialog { --z-index: 3000; } ``` 可以在各个组件的文档页面查看组件支持的 CSS 自定义属性。 ## CSS Part {#css-part} mdui 组件使用 shadow DOM 来封装样式和行为，但是常规 CSS 选择器无法选择到 shadow DOM 内部的元素。因此，一些组件为 Shadow DOM 元素添加了 `part` 属性，你可以使用 `::part` CSS 选择器来选择到对应的元素，并重写部分样式。 例如，下面的代码使用 [`button`](/zh-cn/docs/2/components/button#cssParts-button) part 修改了按钮的内边距，且使用 [`label`](/zh-cn/docs/2/components/button#cssParts-label)、[`icon`](/zh-cn/docs/2/components/button#cssParts-icon)、[`end-icon`](/zh-cn/docs/2/components/button#cssParts-end-icon) part 分别修改了文本、左右图标的颜色： ```html Button ``` 关于组件 shadow DOM 元素的结构和默认样式，你可以打开浏览器的开发人员工具进行查看。 在使用 CSS Part 之前，你应该先判断使用全局 CSS 自定义属性、及组件特有的 CSS 自定义属性能否满足你的需求，如果能满足需求，则应优先使用 CSS 自定义属性来定制样式。 可以在各个组件的文档页面查看组件公开的所有 `part` 属性。 ## 组件更新机制 {#update-mechanism} mdui 组件是基于 [Lit](https://lit.dev/) 开发的。Lit 是一个轻量级的库，它使 Web Components 的开发更加简单。在使用 mdui 组件时，你可能需要了解其渲染和更新机制。 当你修改 mdui 组件的属性时，组件会进行重新渲染。但是，这个重新渲染过程并不是同步进行的。当你同时修改了多个属性值时，Lit 会将这些变更缓存起来，直到下一个更新周期，以确保无论你修改了多少次属性值，每个组件只会重新渲染一次。并且，只有 shadow DOM 中发生变更的部分会被重新渲染。 在下面的示例中，我们将按钮的 `disabled` JavaScript 属性值设置为 `true`，然后立即查询其 HTML 属性。但是，由于此时组件还没有进行重新渲染，因此查询到的 HTML 属性仍然是 `false`： ```js const button = document.querySelector('mdui-button'); button.disabled = true; console.log(button.hasAttribute('disabled')); // false ``` 如果要等待一个属性值变更后的重新渲染完成，可以使用组件的 `updateComplete` 属性。该属性返回一个 Promise，在 Promise 被 resolve 后，即表示组件已经完成了重新渲染： ```js const button = document.querySelector('mdui-button'); button.disabled = true; button.updateComplete.then(() => { console.log(button.hasAttribute('disabled')); // true }); ``` # TypeScript 支持 mdui 是用 TypeScript 开发的，因此对 TypeScript 提供了良好的支持。所有的 mdui 官方库都自带类型声明文件，可以直接使用。 ## 组件的实例类型 {#instance} 有时，你可能需要将一个 JavaScript 变量断言为 mdui 的组件实例，这时你可以直接从 mdui 中导入对应的组件类型。 例如，从组件文件中导入 Tooltip 组件的类型： ```ts import type { Tooltip } from 'mdui/components/tooltip.js'; ``` 或者直接从 mdui 导入 Tooltip 组件的类型： ```ts import type { Tooltip } from 'mdui'; ``` 然后，你就可以将一个 JavaScript 变量断言成 Tooltip 类型： ```ts const tooltip = document.querySelector('mdui-tooltip') as Tooltip; ``` 此时，你的 IDE 会自动提示 `tooltip` 变量的属性和方法。 如果在 `tooltip` 变量上添加事件监听，也会自动提示事件名称，事件类型，以及回调函数中 `this` 的指向： ```ts tooltip.addEventListener('open', function(event) { }); ``` ## 事件类型 {#event} 每个组件都会导出一个接口，它映射了组件的事件名和它对应的事件对象类型，接口名为 `${组件名}EventMap`。 例如，Tooltip 组件会导出一个名为 `TooltipEventMap` 的接口： ```ts export interface TooltipEventMap { open: CustomEvent; opened: CustomEvent; close: CustomEvent; closed: CustomEvent; } ``` 你可以从组件文件中导入该接口： ```ts import type { TooltipEventMap } from 'mdui/components/tooltip.js'; ``` 或者直接从 mdui 导入该接口： ```ts import type { TooltipEventMap } from 'mdui'; ``` 请注意，该接口只包含组件特有的事件，但 mdui 组件都继承自 `HTMLElement`，所以也支持 `HTMLElement` 的事件，你可以使用交叉类型来获取组件的所有事件类型： ```ts type TooltipAndHTMLElementEventMap = TooltipEventMap & HTMLElementEventMap; ``` # IDE 支持 mdui 专门为 VS Code 和 WebStorm 进行了优化，在这些 IDE 中可以获得代码自动完成、悬停提示等功能。 ## VS Code {#vscode} ### 通过 npm 安装的 mdui {#vscode-npm} 如果你通过 npm 安装了 mdui，可以按照以下步骤在当前项目中启用 VS Code 的 IDE 支持： 1. 在项目的根目录中创建 `.vscode` 目录。 2. 在 `.vscode` 目录中创建 `settings.json` 文件。 3. 将以下代码添加到 `settings.json` 文件中： ```json { "html.customData": ["./node_modules/mdui/html-data.zh-cn.json"], "css.customData": ["./node_modules/mdui/css-data.zh-cn.json"] } ``` 如果 `settings.json` 文件已经存在，只需将上述两行代码添加到 JSON 文档的根节点即可。修改完成后，重启 VS Code。 ### 通过 CDN 使用的 mdui {#vscode-cdn} 如果你是通过 CDN 引入的 mdui，可以通过安装 mdui 的 VS Code 扩展来获得 IDE 支持。 在 VS Code 的扩展商店中搜索 `mdui`，选择第一条搜索结果进行安装，或者[点击此处安装](vscode:extension/zdhxiong.mdui)。安装完成后，所有项目都将启用 mdui 的 IDE 支持。 建议优先通过 npm 安装并设置 `settings.json` 文件，而非安装 VS Code 扩展，以确保 IDE 支持与当前使用的 mdui 版本保持一致。 ## WebStorm {#webstorm} ### 通过 npm 安装的 mdui {#webstorm-npm} 如果你通过 npm 安装了 mdui，可以按照以下步骤在当前项目中启用 WebStorm 的 IDE 支持： 1. 在项目根目录的 `package.json` 文件的根节点中添加以下代码： ``` web-types: ["./node_modules/mdui/web-types.zh-cn.json"] ``` 如果 `package.json` 文件的根节点已存在 `web-types` 属性，只需将 `./node_modules/mdui/web-types.zh-cn.json` 添加到 `web-types` 数组中即可。修改完成后，重启 WebStorm。 ### 通过 CDN 使用的 mdui {#webstorm-cdn} 如果你是通过 CDN 引入的 mdui，可以通过安装 mdui 的 WebStorm 插件来获得 IDE 支持。 在 WebStorm 的插件市场中搜索 `mdui`，选择第一条搜索结果进行安装。安装完成后，所有项目都将启用 mdui 的 IDE 支持。 建议优先通过 npm 安装来获取 IDE 支持，而非安装 WebStorm 插件，以确保 IDE 支持与当前使用的 mdui 版本保持一致。 ## 对 VS Code 和 WebStorm 支持的差异 {#difference} mdui 对 VS Code 和 WebStorm 的支持存在一些差异。以下表格列出了详细的差异： | 具有代码自动完成及悬浮提示的位置 | VS Code | WebStorm | | ---------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | HTML 标签名 | | | | HTML 标签中的属性名 | | | | HTML 标签中属性值的枚举值 | | （不支持显示枚举值的注释） | | HTML 标签中的事件名 | | | | HTML 中 slot 的 `name` 属性值 | | | | CSS 中 `::part()` 选择器的 `part` 属性名 | | （需要 WebStorm 2023.2 及以上版本） | | CSS 中组件内的 CSS 自定义属性名 | | | | CSS 中的全局 CSS 自定义属性名 | | | | CSS 中的全局 class 名 | | | # 本地化 mdui 内部默认使用英文，如果需要使用其他语言，则需要进行多语言配置。 ## 使用方法 {#usage} mdui 提供了三个函数来实现多语言功能： * [`loadLocale`](/zh-cn/docs/2/functions/loadLocale)：加载语言包。参数为一个函数，接收一个语言代码作为参数，返回 Promise，当语言包加载完成时，Promise 被 resolve 为对应的语言包。请确保在项目的入口文件中调用该函数。 * [`setLocale`](/zh-cn/docs/2/functions/setLocale)：切换到指定的语言。参数为新的语言代码，返回 Promise，在新的语言包加载完成后 resolve。 * [`getLocale`](/zh-cn/docs/2/functions/getLocale)：获取当前的语言代码。 使用示例如下： ```js import { loadLocale } from 'mdui/functions/loadLocale.js'; import { setLocale } from 'mdui/functions/setLocale.js'; import { getLocale } from 'mdui/functions/getLocale.js'; // 在项目入口处调用 loadLocale 加载语言包 loadLocale((locale) => import(`../node_modules/mdui/locales/${locale}.js`)); // 在需要切换语言时调用该函数。在 Promise resolve 后，语言切换成功 setLocale('zh-cn').then(() => { // 调用 getLocale 可获取当前的语言代码 console.log(getLocale()); // zh-cn }); ``` ## 状态事件 {#event} 在语言切换的开始、结束、失败时，会在 `window` 上触发 `mdui-localize-status` 事件，你可以监听该事件来执行自定义操作，例如在语言切换成功后将语言代码写入 Cookie。 事件的 `detail.status` 属性描述了当前发生了何种状态的变更，可能的值包括：`loading`、`ready`、`error`：
detail.status 描述
loading

开始加载新的语言包。

detail 对象包含：

  • loadingLocale：新加载语言的语言代码。
ready

新的语言包加载成功。

detail 对象包含：

  • readyLocale：新加载语言的语言代码。
error

新的语言包加载失败。

detail 对象包含：

  • errorLocale：加载失败的语言的语言代码。
  • errorMessage：加载失败的错误信息。
使用示例如下： ```js window.addEventListener('mdui-localize-status', (event) => { if (event.detail.status === 'loading') { console.log(`开始加载新的语言包：${event.detail.loadingLocale}`); } else if (event.detail.status === 'ready') { console.log(`新语言包 ${event.detail.readyLocale} 加载成功`); } else if (event.detail.status === 'error') { console.error(`新语言包 ${event.detail.errorLocale} 加载失败：${event.detail.errorMessage}`); } }); ``` ## 语言包加载方式 {#load-locale} ### 懒加载 {#lazy-load} 使用[动态导入](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import)可以在切换到对应语言时，才下载对应的语言包。这是最为推荐的方法。 ```js import { loadLocale } from 'mdui/functions/loadLocale.js'; loadLocale((locale) => import(`../node_modules/mdui/locales/${locale}.js`)); ``` ### 预加载 {#pre-load} 在页面加载时，先下载好所有需要的语言包。这使得在切换语言时，无需再进行下载，从而使切换语言更加快速。 ```js import { loadLocale } from 'mdui/functions/loadLocale.js'; const localizedTemplates = new Map([ ['zh-cn', import(`../node_modules/mdui/locales/zh-cn.js`)], ['zh-tw', import(`../node_modules/mdui/locales/zh-tw.js`)] ]); loadLocale(async (locale) => localizedTemplates.get(locale)); ``` ### 静态导入 {#static-imports} 使用该方法可以把所有需要的语言包和你的项目代码打包到同一个文件里，不再需要单独下载语言包。 ```js import { loadLocale } from 'mdui/functions/loadLocale.js'; import * as locale_zh_cn from 'mdui/locales/zh-cn.js'; import * as locale_zh_tw from 'mdui/locales/zh-tw.js'; const localizedTemplates = new Map([ ['zh-cn', locale_zh_cn], ['zh-tw', locale_zh_tw] ]); loadLocale(async (locale) => localizedTemplates.get(locale)); ``` ## 通过 CDN 加载语言包 {#cdn} 如果你是通过 CDN 来使用 mdui 的，可以直接从 CDN 加载语言包。使用示例如下： ```html ``` ## 支持的语言 {#languages} 目前，mdui 支持以下语言： | 语言 | 语言代码 | | -------------------- | -------- | | 阿拉伯语 | ar-eg | | 阿塞拜疆语 | az-az | | 保加利亚语 | bg-bg | | 孟加拉语（孟加拉国） | bn-bd | | 白俄罗斯语 | be-by | | 加泰罗尼亚语 | ca-es | | 捷克语 | cs-cz | | 丹麦语 | da-dk | | 德语 | de-de | | 希腊语 | el-gr | | 英语 | en-gb | | 英语（美式） | en-us | | 西班牙语 | es-es | | 爱沙尼亚语 | et-ee | | 波斯语 | fa-ir | | 芬兰语 | fi-fi | | 法语（比利时） | fr-be | | 法语（加拿大） | fr-ca | | 法语（法国） | fr-fr | | 爱尔兰语 | ga-ie | | 加利西亚语（西班牙） | gl-es | | 希伯来语 | he-il | | 印地语 | hi-in | | 克罗地亚语 | hr-hr | | 匈牙利语 | hu-hu | | 亚美尼亚 | hy-am | | 印度尼西亚语 | id-id | | 意大利语 | it-it | | 冰岛语 | is-is | | 日语 | ja-jp | | 格鲁吉亚语 | ka-ge | | 高棉语 | km-kh | | 北库尔德语 | kmr-iq | | 卡纳达语 | kn-in | | 哈萨克语 | kk-kz | | 韩语/朝鲜语 | ko-kr | | 立陶宛语 | lt-lt | | 拉脱维亚语 | lv-lv | | 马其顿语 | mk-mk | | 马拉雅拉姆语 | ml-in | | 蒙古语 | mn-mn | | 马来语（马来西亚） | ms-my | | 挪威语 | nb-no | | 尼泊尔语 | ne-np | | 荷兰语（比利时） | nl-be | | 荷兰语 | nl-nl | | 波兰语 | pl-pl | | 葡萄牙语（巴西） | pt-br | | 葡萄牙语 | pt-pt | | 罗马尼亚语 | ro-ro | | 俄罗斯语 | ru-ru | | 斯洛伐克语 | sk-sk | | 塞尔维亚语 | sr-rs | | 斯洛文尼亚语 | sl-si | | 瑞典语 | sv-se | | 泰米尔语 | ta-in | | 泰语 | th-th | | 土耳其语 | tr-tr | | 乌尔都语（巴基斯坦） | ur-pk | | 乌克兰语 | uk-ua | | 越南语 | vi-vn | | 简体中文 | zh-cn | | 繁体中文（中国香港） | zh-hk | | 繁体中文（中国台湾） | zh-tw | ## 提交新的翻译 {#contribute} 要贡献新的翻译、或对现有翻译进行改进，请在 Github 上发起一个 Pull Request。语言包位于 [`packages/mdui/src/xliff`](https://github.com/zdhxiong/mdui/tree/v2/packages/mdui/src/xliff)，你可以直接在 Github 上进行编辑。 # 常见问题 ## 使用自闭合标签为何无法显示组件？ {#no-self-closing} mdui 是基于 Web Components 开发的组件库，Web Components 规范不支持自闭合标签，因此请确保为 mdui 组件添加结束标签。 ```html ``` ## 如何在组件加载完成前隐藏组件？ {#waiting-load} 由于 mdui 组件是通过 JavaScript 进行注册的，因此在 js 文件加载并注册组件之前，组件可能会暂时显示为无样式状态。以下两种方法可以解决这个问题： 一种方法是使用 CSS 的 [`:defined`](https://developer.mozilla.org/zh-CN/docs/Web/CSS/:defined) 伪类来隐藏未注册的 mdui 组件。以下 CSS 代码将隐藏所有未注册的 mdui 组件，并在组件注册完成后立即显示： ```css :not(:defined) { visibility: hidden; } ``` 另一种方法是使用 JavaScript 的 [`customElements.whenDefined()`](https://developer.mozilla.org/zh-CN/docs/Web/API/CustomElementRegistry/whenDefined) 方法。这个方法返回一个 promise，当指定的组件注册完成后，该 promise 将被 resolve。为了处理某些组件由于特殊原因无法加载的情况，你可以配合使用 [`Promise.allSettled()`](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled) 方法。 以下示例首先通过 `opacity: 0` 将 `` 隐藏，然后在组件注册完成后，使页面淡入显示。同时，示例使用了 `Promise.allSettled()` 来等待所有 promise 完成，确保即使某个组件无法加载，页面也能正常显示： ```html ``` # LLMs.txt mdui 提供了 `llms.txt` 与 `llms-full.txt`，用于为 LLM（大语言模型）提供准确、可引用的上下文，帮助 AI 更可靠地回答 mdui 相关问题。 ## 使用 llms.txt 为 AI 提供上下文 {#context} 两个入口： - `llms.txt`：https://www.mdui.org/zh-cn/docs/2/llms.txt - `llms-full.txt`：https://www.mdui.org/zh-cn/docs/2/llms-full.txt `llms.txt` 是精简索引，适合供可联网的模型按链接抓取所需 Markdown 页面，或先提供项目概览。 `llms-full.txt` 含完整上下文，包含 `llms.txt` 中的所有页面内容，适合模型无法联网或需一次性提供完整上下文。 ## 文档的 Markdown 版本 {#md-mirror} 每个文档页面都提供了对应的 Markdown 版本：在页面 URL 末尾追加 `.md` 即可（首页追加 `index.md`）。 例如： https://www.mdui.org/zh-cn/docs/2/components/button → https://www.mdui.org/zh-cn/docs/2/components/button.md https://www.mdui.org/zh-cn/docs/2/ → https://www.mdui.org/zh-cn/docs/2/index.md 可直接把该 Markdown 链接或其纯文本作为上下文，获得更聚焦、准确的回答。 ## 在 ChatGPT、Claude 等 LLM 中如何使用 {#how-to-use} 根据模型是否支持联网/文件上传，选择以下一种或组合使用： 1. 直接粘贴：将 `llms-full.txt` 的内容作为系统提示或首条消息。 示例：“以下是 mdui 的上下文。请严格依据它回答后续问题；若有冲突，以该上下文为准：\n\n[粘贴 llms-full.txt 内容]”。 2. 上传文件：上传 `llms-full.txt`（或 `llms.txt`），并在首条提示说明“以附件为主要上下文”。 示例：“基于附件中的 mdui 文档，给出 `` 的用法与常见坑”。 3. 在线读取：在对话中给出 `llms.txt` 或 `llms-full.txt` 的链接。 示例：“请读取并遵循 https://www.mdui.org/zh-cn/docs/2/llms-full.txt 作为上下文，回答我关于 mdui 的问题”。 4. 指向具体页面：只讨论特定组件/函数时，直接给出该页面的 Markdown 地址。 示例：“请阅读 https://www.mdui.org/zh-cn/docs/2/components/button.md ，并基于该文档给出三段最佳实践”。 **提示**：可点击页面右上角的 图标，支持一键复制上述链接、打开当前页面的 Markdown 版本，或将当前页面、或 `llms-full.txt` 作为上下文在 ChatGPT 中打开。 # 暗色模式 mdui 的所有组件都支持暗色模式，并且支持根据操作系统的设置自动切换主题。 你可以随时点击文档页面右上角的 图标来切换主题，以查看各个组件在不同主题下的显示效果。 如果要使用暗色模式，只需在 `` 标签上添加 `mdui-theme-dark` 类即可： ```html ``` 如果要让主题根据操作系统设置自动切换，只需在 `` 标签上添加 `mdui-theme-auto` 类即可： ```html ``` 也可以在页面的不同部分使用不同的主题。例如下面的示例，在 `` 上设置暗色模式，但在页面中的一个 `
` 上添加了 `mdui-theme-light` 类，这样该 div 中的元素将显示为亮色模式，而页面其余部分则为暗色模式： ```html
``` 除了直接添加 CSS 类外，mdui 还提供了两个函数，可以更便捷的操作主题： * [`getTheme`](/zh-cn/docs/2/functions/getTheme)：获取当前页面、或指定元素上的主题。 * [`setTheme`](/zh-cn/docs/2/functions/setTheme)：设置当前页面、或指定元素上的主题。 ---- 需要注意的是，mdui 在 `:root` 及 `.mdui-theme-light`、`.mdui-theme-dark`、`.mdui-theme-auto` 选择器上设置了 `color` 和 `background-color` 样式，如果你不喜欢这些默认样式，可以自行进行覆盖。 下面示例将亮色模式下的页面背景设为纯白，文字设为纯黑；且暗色模式下页面背景设为纯黑，文字设为纯白： ```css :root, .mdui-theme-light { color: #000; background-color: #fff; } .mdui-theme-dark { color: #fff; background-color: #000; } @media (prefers-color-scheme: dark) { .mdui-theme-auto { color: #fff; background-color: #000; } } ``` # 动态配色 mdui 提供了动态配色功能。只需提供一个颜色值，mdui 就能自动生成一套完整的配色方案。此外，mdui 还支持从指定的壁纸中提取主色调，并据此生成配色方案。 你可以随时点击文档页面右上角的 图标，切换配色方案，查看各个组件在不同配色方案下的显示效果。 一套配色方案实际上是一组 CSS 自定义属性。mdui 组件中的颜色值都引用了这一组 CSS 自定义属性，因此可以一次性更新所有组件的配色方案。完整的 CSS 自定义属性列表请参见 [设计令牌 - 颜色](/zh-cn/docs/2/styles/design-tokens#color)。 ## 生成配色方案 {#color-scheme} 你可以使用 [`setColorScheme`](/zh-cn/docs/2/functions/setColorScheme) 函数来生成配色方案。该函数接受一个十六进制颜色值作为参数，生成一套配色方案，并将页面的 `` 元素设置为该配色方案。例如： ```js import { setColorScheme } from 'mdui/functions/setColorScheme.js'; // 根据 #0061a4 生成一套配色方案，并将 设置为该配色方案 setColorScheme('#0061a4'); ``` 你还可以在第二个参数中指定 `target` 属性，用于指明在哪个元素上设置配色方案。例如： ```js import { setColorScheme } from 'mdui/functions/setColorScheme.js'; // 根据 #0061a4 生成一套配色方案，并将 .foo 元素设置为该配色方案 setColorScheme('#0061a4', { target: document.querySelector('.foo') }); ``` 默认情况下生成的配色方案仅包含 [设计令牌 - 颜色](/zh-cn/docs/2/styles/design-tokens#color) 中所列出的颜色。你可以在第二个参数中指定 `customColors` 属性，mdui 会根据你给出的自定义颜色名和颜色值生成一组自定义颜色组。例如： ```js import { setColorScheme } from 'mdui/functions/setColorScheme.js'; // 根据 #0061a4 生成一套配色方案，并修改了原有的 error 颜色组的值，并添加了一组新的 music 颜色组 setColorScheme('#0061a4', { customColors: [ { name: 'error', value: '#69F0AE' }, { name: 'music', value: '#FFC107' } ] }); ``` 一组自定义颜色组包含四个 CSS 自定义属性： * `--mdui-color-{name}` * `--mdui-color-on-{name}` * `--mdui-color-{name}-container` * `--mdui-color-on-{name}-container` 其中的 `{name}` 为你传入的 `customColors` 中的 `name` 字段名，即自定义颜色名。 自定义颜色名可以是默认配色方案中的已有颜色名，如 `primary`、`secondary`、`tertiary`、`error` 这些都是默认配色方案中已包含的。如果你指定了这些值作为自定义颜色名，则生成的配色方案中对应的四个 CSS 自定义属性，将用你指定的颜色值来生成。例如上面示例中指定了名为 `error` 的自定义颜色名，因为 `error` 是默认配色方案中已有的颜色名，且其对应的 CSS 自定义属性被 mdui 组件用于表示错误状态，因为现在颜色值被设置为一个绿色的值，所以 mdui 组件中的错误状态也将变为绿色。 自定义颜色名也可以是新增的，例如上面示例中的 `music`，是默认配色方案中不存在的，则生成的配色方案将额外包含四个 CSS 自定义属性。可以在你自己的样式中引用这些 CSS 自定义属性： ```html
Music
Music Container
``` 你还可以使用 [`removeColorScheme`](/zh-cn/docs/2/functions/removeColorScheme) 函数来移除通过上述方法生成的配色方案。你可以传入参数来指定移除哪个元素上的配色方案，默认情况下，它会移除 `` 上的配色方案。 ## 从壁纸中提取颜色 {#from-wallpaper} mdui 提供了 [`getColorFromImage`](/zh-cn/docs/2/functions/getColorFromImage) 函数，用于从一个给定的 `Image` 实例中提取主色调。该函数返回一个 Promise，resolve 的值即为提取的十六进制颜色值。 你可以使用从该函数获得的颜色值，然后调用上述文档中介绍的 [`setColorScheme`](/zh-cn/docs/2/functions/setColorScheme) 函数来设置配色方案。例如： ```js import { getColorFromImage } from 'mdui/functions/getColorFromImage.js'; import { setColorScheme } from 'mdui/functions/setColorScheme.js'; const image = new Image(); image.src = 'image1.png'; getColorFromImage(image).then(color => setColorScheme(color)); ``` # 文章排版 mdui 提供了 `mdui-prose` 和 `mdui-table` CSS 类，专门用于优化文章和表格的样式。 ## 文章排版 {#prose} 可以在文章的父元素上添加 `mdui-prose` 类，这样可以优化整篇文章的显示样式，包括文章中的 `` 表格样式。例如： ```html

标题

正文

``` ## 表格样式 {#table} 在 `` 元素上添加 `mdui-table` 类，可以优化表格的显示样式。例如： ```html
``` 如果你希望表格能在其父元素内横向滚动，可以在 `` 元素的父元素上添加 `mdui-table` 类。例如： ```html
``` # 设计令牌 设计令牌（Design Tokens）是一种用于管理设计系统的策略。 它将设计系统中的所有可复用元素（例如颜色、字体、间距等）抽象为独立的变量，以便在整个设计系统中进行统一的管理和应用。 mdui 使用全局 CSS 自定义属性来实现设计令牌。这意味着，你只需修改 CSS 自定义属性，就能全局修改所有 mdui 组件的样式。同时，对于你自己开发的样式，也推荐优先引用 CSS 自定义属性，以确保你的样式与 mdui 组件的样式保持统一，此外，在修改动态配色时，你自己的样式也能同步更新配色。 ## 颜色 {#color} mdui 为亮色模式和暗色模式分别提供了一组 CSS 自定义属性。在亮色模式下，CSS 自定义属性名为 `--mdui-color-{name}-light`，其中 `{name}` 为颜色名称；在暗色模式下则为 `--mdui-color-{name}-dark`。 此外，mdui 还提供了一组名为 `--mdui-color-{name}` 的 CSS 自定义属性，该属性在亮色模式下会引用 `--mdui-color-{name}-light`，在暗色模式下会引用 `--mdui-color-{name}-dark`，因此能根据当前亮、暗色模式自动切换颜色。 如果你需要修改部分颜色的 CSS 自定义属性，需要同时修改 `--mdui-color-{name}-light` 和 `--mdui-color-{name}-dark` 两个属性。而在读取 CSS 自定义属性时，直接使用 `--mdui-color-{name}` 属性即可。 CSS 自定义属性的属性值为 RGB 的三个颜色使用 `,` 分隔，下面的示例演示了颜色的 CSS 自定义属性的用法： ```css /* 修改 primary 的颜色值 */ :root { --mdui-color-primary-light: 103, 80, 164; --mdui-color-primary-dark: 208, 188, 255; } /* 把 foo 元素的背景色设置为 primary */ .foo { background-color: rgb(var(--mdui-color-primary)); } /* 把 bar 元素的背景色设置为含 0.8 不透明度的 primary */ .bar { background-color: rgba(var(--mdui-color-primary), 0.8); } ``` 如果你需要创建一套全新的配色，推荐使用 [`setColorScheme`](/zh-cn/docs/2/functions/setColorScheme) 函数，该函数能根据你给定的一个颜色值生成一整套配色方案。
颜色名 CSS 自定义属性 默认值 示例
Primary --mdui-color-primary-light 103, 80, 164
--mdui-color-primary-dark 208, 188, 255
--mdui-color-primary
Primary container --mdui-color-primary-container-light 234, 221, 255
--mdui-color-primary-container-dark 79, 55, 139
--mdui-color-primary-container
On primary --mdui-color-on-primary-light 255, 255, 255
--mdui-color-on-primary-dark 55, 30, 115
--mdui-color-on-primary
On primary container --mdui-color-on-primary-container-light 33, 0, 94
--mdui-color-on-primary-container-dark 234, 221, 255
--mdui-color-on-primary-container
Inverse primary --mdui-color-inverse-primary-light 208, 188, 255
--mdui-color-inverse-primary-dark 103, 80, 164
--mdui-color-inverse-primary
Secondary --mdui-color-secondary-light 98, 91, 113
--mdui-color-secondary-dark 204, 194, 220
--mdui-color-secondary
Secondary container --mdui-color-secondary-container-light 232, 222, 248
--mdui-color-secondary-container-dark 74, 68, 88
--mdui-color-secondary-container
On secondary --mdui-color-on-secondary-light 255, 255, 255
--mdui-color-on-secondary-dark 51, 45, 65
--mdui-color-on-secondary
On secondary container --mdui-color-on-secondary-container-light 30, 25, 43
--mdui-color-on-secondary-container-dark 232, 222, 248
--mdui-color-on-secondary-container
Tertiary --mdui-color-tertiary-light 125, 82, 96
--mdui-color-tertiary-dark 239, 184, 200
--mdui-color-tertiary
Tertiary container --mdui-color-tertiary-container-light 255, 216, 228
--mdui-color-tertiary-container-dark 99, 59, 72
--mdui-color-tertiary-container
On tertiary --mdui-color-on-tertiary-light 255, 255, 255
--mdui-color-on-tertiary-dark 73, 37, 50
--mdui-color-on-tertiary
On tertiary container --mdui-color-on-tertiary-container-light 55, 11, 30
--mdui-color-on-tertiary-container-dark 255, 216, 228
--mdui-color-on-tertiary-container
Surface --mdui-color-surface-light 254, 247, 255
--mdui-color-surface-dark 20, 18, 24
--mdui-color-surface
Surface dim --mdui-color-surface-dim-light 222, 216, 225
--mdui-color-surface-dim-dark 20, 18, 24
--mdui-color-surface-dim
Surface bright --mdui-color-surface-bright-light 254, 247, 255
--mdui-color-surface-bright-dark 59, 56, 62
--mdui-color-surface-bright
Surface container lowest --mdui-color-surface-container-lowest-light 255, 255, 255
--mdui-color-surface-container-lowest-dark 15, 13, 19
--mdui-color-surface-container-lowest
Surface container low --mdui-color-surface-container-low-light 247, 242, 250
--mdui-color-surface-container-low-dark 29, 27, 32
--mdui-color-surface-container-low
Surface container --mdui-color-surface-container-light 243, 237, 247
--mdui-color-surface-container-dark 33, 31, 38
--mdui-color-surface-container
Surface container high --mdui-color-surface-container-high-light 236, 230, 240
--mdui-color-surface-container-high-dark 43, 41, 48
--mdui-color-surface-container-high
Surface container highest --mdui-color-surface-container-highest-light 230, 224, 233
--mdui-color-surface-container-highest-dark 54, 52, 59
--mdui-color-surface-container-highest
Surface variant --mdui-color-surface-variant-light 231, 224, 236
--mdui-color-surface-variant-dark 73, 69, 79
--mdui-color-surface-variant
On surface --mdui-color-on-surface-light 28, 27, 31
--mdui-color-on-surface-dark 230, 225, 229
--mdui-color-on-surface
On surface variant --mdui-color-on-surface-variant-light 73, 69, 78
--mdui-color-on-surface-variant-dark 202, 196, 208
--mdui-color-on-surface-variant
Inverse surface --mdui-color-inverse-surface-light 49, 48, 51
--mdui-color-inverse-surface-dark 230, 225, 229
--mdui-color-inverse-surface
Inverse on surface --mdui-color-inverse-on-surface-light 244, 239, 244
--mdui-color-inverse-on-surface-dark 49, 48, 51
--mdui-color-inverse-on-surface
Background --mdui-color-background-light 254, 247, 255
--mdui-color-background-dark 20, 18, 24
--mdui-color-background
On background --mdui-color-on-background-light 28, 27, 31
--mdui-color-on-background-dark 230, 225, 229
--mdui-color-on-background
Error --mdui-color-error-light 179, 38, 30
--mdui-color-error-dark 242, 184, 181
--mdui-color-error
Error container --mdui-color-error-container-light 249, 222, 220
--mdui-color-error-container-dark 140, 29, 24
--mdui-color-error-container
On error --mdui-color-on-error-light 255, 255, 255
--mdui-color-on-error-dark 96, 20, 16
--mdui-color-on-error
On error container --mdui-color-on-error-container-light 65, 14, 11
--mdui-color-on-error-container-dark 249, 222, 220
--mdui-color-on-error-container
Outline --mdui-color-outline-light 121, 116, 126
--mdui-color-outline-dark 147, 143, 153
--mdui-color-outline
Outline variant --mdui-color-outline-variant-light 196, 199, 197
--mdui-color-outline-variant-dark 68, 71, 70
--mdui-color-outline-variant
Shadow --mdui-color-shadow-light 0, 0, 0
--mdui-color-shadow-dark 0, 0, 0
--mdui-color-shadow
Surface tint --mdui-color-surface-tint-color-light 103, 80, 164
--mdui-color-surface-tint-color-dark 208, 188, 255
--mdui-color-surface-tint-color
Scrim --mdui-color-scrim-light 0, 0, 0
--mdui-color-scrim-dark 0, 0, 0
--mdui-color-scrim
## 圆角 {#shape-corner} mdui 提供了 7 种不同大小的圆角。以下是如何使用这些圆角的 CSS 自定义属性的示例： ```css /* 修改 extra-small 的圆角大小 */ :root { --mdui-shape-corner-extra-small: 0.3rem; } /* 把 foo 元素的圆角设置为 extra-small */ .foo { border-radius: var(--mdui-shape-corner-extra-small); } ``` | CSS 自定义属性 | 默认值 | 示例 | | --------------------------------- | --------- | --------------------------------------------------------------------------------------------------------- | | `--mdui-shape-corner-none` | `0` |
| | `--mdui-shape-corner-extra-small` | `0.25rem` |
| | `--mdui-shape-corner-small` | `0.5rem` |
| | `--mdui-shape-corner-medium` | `0.75rem` |
| | `--mdui-shape-corner-large` | `1rem` |
| | `--mdui-shape-corner-extra-large` | `1.75rem` |
| | `--mdui-shape-corner-full` | `1000rem` |
| ## 排版 {#typescale} mdui 提供了 15 种不同的文字样式，包括 Display large、Display medium、Display small、Headline large、Headline medium、Headline small、Title large、Title medium、Title small、Label large、Label medium、Label small、Body large、Body medium、Body small。 下面是使用示例： ```css /* 修改 Body large 的文字样式 */ :root { --mdui-typescale-body-large-line-height: 1.6rem; --mdui-typescale-body-large-size: 1.2rem; --mdui-typescale-body-large-tracking: 0.01rem; --mdui-typescale-body-large-weight: 400; } /* 把 foo 元素的文字样式设置为 Body large */ .foo { line-height: var(--mdui-typescale-body-large-line-height); font-size: var(--mdui-typescale-body-large-size); letter-spacing: var(--mdui-typescale-body-large-tracking); font-weight: var(--mdui-typescale-body-large-weight); } ```
CSS 自定义属性 默认值 示例
--mdui-typescale-display-large-line-height 4rem
Display large
--mdui-typescale-display-large-size 3.5625rem
--mdui-typescale-display-large-tracking 0
--mdui-typescale-display-large-weight 400
--mdui-typescale-display-medium-line-height 3.25rem
Display medium
--mdui-typescale-display-medium-size 2.8125rem
--mdui-typescale-display-medium-tracking 0
--mdui-typescale-display-medium-weight 400
--mdui-typescale-display-small-line-height 2.75rem
Display small
--mdui-typescale-display-small-size 2.25rem
--mdui-typescale-display-small-tracking 0
--mdui-typescale-display-small-weight 400
--mdui-typescale-headline-large-line-height 2.5rem
Headline large
--mdui-typescale-headline-large-size 2rem
--mdui-typescale-headline-large-tracking 0
--mdui-typescale-headline-large-weight 400
--mdui-typescale-headline-medium-line-height 2.25rem
Headline medium
--mdui-typescale-headline-medium-size 1.75rem
--mdui-typescale-headline-medium-tracking 0
--mdui-typescale-headline-medium-weight 400
--mdui-typescale-headline-small-line-height 2rem
Headline small
--mdui-typescale-headline-small-size 1.5rem
--mdui-typescale-headline-small-tracking 0
--mdui-typescale-headline-small-weight 400
--mdui-typescale-title-large-line-height 1.75rem
Title large
--mdui-typescale-title-large-size 1.375rem
--mdui-typescale-title-large-tracking 0
--mdui-typescale-title-large-weight 400
--mdui-typescale-title-medium-line-height 1.5rem
Title medium
--mdui-typescale-title-medium-size 1rem
--mdui-typescale-title-medium-tracking 0.009375rem
--mdui-typescale-title-medium-weight 500
--mdui-typescale-title-small-line-height 1.25rem
Title small
--mdui-typescale-title-small-size 0.875rem
--mdui-typescale-title-small-tracking 0.00625rem
--mdui-typescale-title-small-weight 500
--mdui-typescale-label-large-line-height 1.25rem
Label large
--mdui-typescale-label-large-size 0.875rem
--mdui-typescale-label-large-tracking 0.00625rem
--mdui-typescale-label-large-weight 500
--mdui-typescale-label-medium-line-height 1rem
Label medium
--mdui-typescale-label-medium-size 0.75rem
--mdui-typescale-label-medium-tracking 0.03125rem
--mdui-typescale-label-medium-weight 500
--mdui-typescale-label-small-line-height 0.375rem
Label small
--mdui-typescale-label-small-size 0.6875rem
--mdui-typescale-label-small-tracking 0.03125rem
--mdui-typescale-label-small-weight 500
--mdui-typescale-body-large-line-height 1.5rem
Body large
--mdui-typescale-body-large-size 1rem
--mdui-typescale-body-large-tracking 0.009375rem
--mdui-typescale-body-large-weight 400
--mdui-typescale-body-medium-line-height 1.25rem
Body medium
--mdui-typescale-body-medium-size 0.875rem
--mdui-typescale-body-medium-tracking 0.015625rem
--mdui-typescale-body-medium-weight 400
--mdui-typescale-body-small-line-height 1rem
Body small
--mdui-typescale-body-small-size 0.75rem
--mdui-typescale-body-small-tracking 0.025rem
--mdui-typescale-body-small-weight 400
## 状态层不透明度 {#state-layer} 部分 mdui 组件在交互时会在其上添加一层半透明遮罩。例如 [``](/zh-cn/docs/2/components/button) 组件，在鼠标悬浮、聚焦、按下或拖动时，都会出现半透明遮罩。你可以通过修改 CSS 自定义属性来调整这些遮罩的不透明度。 下面是使用示例： ```css /* 修改状态层不透明度 */ :root { --mdui-state-layer-hover: 0.08; --mdui-state-layer-focus: 0.12; --mdui-state-layer-pressed: 0.12; --mdui-state-layer-dragged: 0.16; } ``` | CSS 自定义属性 | 默认值 | 示例 | | ---------------------------- | ------ | ------------------------------------------------------------------------------------------------------------ | | `--mdui-state-layer-hover` | `0.08` |
| | `--mdui-state-layer-focus` | `0.12` |
| | `--mdui-state-layer-pressed` | `0.12` |
| | `--mdui-state-layer-dragged` | `0.16` |
| ## 抬升高度（阴影） {#elevation} 部分 mdui 组件具有阴影效果，以模拟组件在页面上的抬升感。你可以通过修改 CSS 自定义属性来调整组件的阴影效果。 下面是使用示例： ```css /* 修改 level1 级别的阴影 */ :root { --mdui-elevation-level1: 0 0.5px 1.5px 0 rgba(var(--mdui-color-shadow), 19%), 0 0 1px 0 rgba(var(--mdui-color-shadow), 3.9%); } /* 把 foo 元素的阴影设置为 level1 */ .foo { box-shadow: var(--mdui-elevation-level1); } ``` | CSS 自定义属性 | 默认值 | 示例 | | ------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `--mdui-elevation-level0` | `none` |
| | `--mdui-elevation-level1` | `0 0.5px 1.5px 0 rgba(var(--mdui-color-shadow), 19%), 0 0 1px 0 rgba(var(--mdui-color-shadow), 3.9%)` |
| | `--mdui-elevation-level2` | `0 0.85px 3px 0 rgba(var(--mdui-color-shadow), 19%), 0 0.25px 1px 0 rgba(var(--mdui-color-shadow), 3.9%)` |
| | `--mdui-elevation-level3` | `0 1.25px 5px 0 rgba(var(--mdui-color-shadow), 19%), 0 0.3333px 1.5px 0 rgba(var(--mdui-color-shadow), 3.9%)` |
| | `--mdui-elevation-level4` | `0 1.85px 6.25px 0 rgba(var(--mdui-color-shadow), 19%), 0 0.5px 1.75px 0 rgba(var(--mdui-color-shadow), 3.9%)` |
| | `--mdui-elevation-level5` | `0 2.75px 9px 0 rgba(var(--mdui-color-shadow), 19%), 0 0.25px 3px 0 rgba(var(--mdui-color-shadow), 3.9%)` |
| ## 动画 {#motion} mdui 组件中的动画缓动曲线和持续时间可以通过 CSS 自定义属性进行配置。 下面是使用示例： ```css /* 修改 standard 的缓动曲线、及 short1 的持续时间 */ :root { --mdui-motion-easing-standard: cubic-bezier(0.2, 0, 0, 1); --mdui-motion-duration-short1: 40ms; } /* 设置 foo 元素的过渡效果使用 standard 的缓动曲线、及 short1 的持续时间 */ .foo { transition: all var(--mdui-motion-duration-short1) var(--mdui-motion-easing-standard); } ```
类型 CSS 自定义属性 默认值
缓动曲线 --mdui-motion-easing-linear cubic-bezier(0, 0, 1, 1)
--mdui-motion-easing-standard cubic-bezier(0.2, 0, 0, 1)
--mdui-motion-easing-standard-accelerate cubic-bezier(0.3, 0, 1, 1)
--mdui-motion-easing-standard-decelerate cubic-bezier(0, 0, 0, 1)
--mdui-motion-easing-emphasized var(--mdui-motion-easing-standard)
--mdui-motion-easing-emphasized-accelerate cubic-bezier(0.3, 0, 0.8, 0.15)
--mdui-motion-easing-emphasized-decelerate cubic-bezier(0.05, 0.7, 0.1, 1)
持续时间 --mdui-motion-duration-short1 50ms
--mdui-motion-duration-short2 100ms
--mdui-motion-duration-short3 150ms
--mdui-motion-duration-short4 200ms
--mdui-motion-duration-medium1 250ms
--mdui-motion-duration-medium2 300ms
--mdui-motion-duration-medium3 350ms
--mdui-motion-duration-medium4 400ms
--mdui-motion-duration-long1 450ms
--mdui-motion-duration-long2 500ms
--mdui-motion-duration-long3 550ms
--mdui-motion-duration-long4 600ms
--mdui-motion-duration-extra-long1 700ms
--mdui-motion-duration-extra-long2 800ms
--mdui-motion-duration-extra-long3 900ms
--mdui-motion-duration-extra-long4 1000ms
## 响应式断点 {#breakpoint} mdui 提供了一系列的响应式断点，这些断点可以通过 CSS 自定义属性进行配置。下面是使用示例： ```css /* 修改 sm 的断点值 */ :root { --mdui-breakpoint-sm: 560px; } ``` 需要注意的是，这些 CSS 自定义属性不能在 CSS 媒体查询中使用。以下是一个错误的示例： ```css /* 错误用法。媒体查询中无法使用 CSS 自定义属性 */ @media (min-width: var(--mdui-breakpoint-sm)) { } ``` 如果你需要在 JavaScript 中进行断点判断，可以使用 [`breakpoint`](/zh-cn/docs/2/functions/breakpoint) 函数。 | CSS 自定义属性 | 默认值 | | ----------------------- | -------- | | `--mdui-breakpoint-xs` | `0px` | | `--mdui-breakpoint-sm` | `600px` | | `--mdui-breakpoint-md` | `840px` | | `--mdui-breakpoint-lg` | `1080px` | | `--mdui-breakpoint-xl` | `1440px` | | `--mdui-breakpoint-xxl` | `1920px` | # 与 React 集成 在 React 中使用 mdui 时，只需要按照 [安装](/zh-cn/docs/2/getting-started/installation#npm) 页面的步骤完成安装即可。 ## 注意事项 {#notes} 在 React 中使用 mdui 时，存在一些限制。这些限制是在 React 中使用 Web Components 的通用限制，而非 mdui 组件库本身的限制。 ### 事件绑定 {#event-binding} 由于 React 不支持自定义事件，因此在使用 mdui 组件提供的事件时，需要先使用 `ref` 属性获取组件的引用。 以下是在 React 中使用 mdui 组件事件的示例： ```js import { useEffect, useRef } from 'react'; import 'mdui/mdui.css'; import 'mdui/components/switch.js'; function App() { const switchRef = useRef(null); useEffect(() => { const handleToggle = () => { console.log("switch is toggled"); }; switchRef.current.addEventListener('change', handleToggle); return () => { switchRef.current.removeEventListener('change', handleToggle); }; }, []); return ( ); } export default App; ``` ### JSX TypeScript 类型声明 {#jsx-typescript} 如果你在 TypeScript 文件（.tsx）中使用 mdui，需要添加 TypeScript 类型声明。你需要在项目的 .d.ts 文件中手动引入 mdui 的类型声明文件： ```ts /// ``` # 与 Vue 集成 在 Vue 中使用 mdui 时，首先需要按照 [安装](/zh-cn/docs/2/getting-started/installation#npm) 页面的指引完成安装，然后进行一些必要的配置。 ## 配置 {#configuration} 你需要配置 Vue，使其不将 mdui 组件解析为 Vue 组件。在 `vite.config` 文件中，设置 `compilerOptions.isCustomElement` 选项即可： ```js // vite.config.js import vue from '@vitejs/plugin-vue' export default { plugins: [ vue({ template: { compilerOptions: { // 所有以 mdui- 开头的标签名都是 mdui 组件 isCustomElement: (tag) => tag.startsWith('mdui-') } } }) ] } ``` 关于这个配置的详细信息，你可以参考 [Vue 官方文档](https://cn.vuejs.org/guide/extras/web-components.html#using-custom-elements-in-vue)。 ## 注意事项 {#notes} ### 双向数据绑定 {#data-binding} 在 mdui 组件上，你不能使用 `v-model` 进行双向数据绑定。你需要自行处理数据的绑定与更新。例如： ```html ``` ### eslint 配置 {#eslint} 如果你使用了 [`eslint-plugin-vue`](https://www.npmjs.com/package/eslint-plugin-vue)，需要在 `.eslintrc.js` 中添加以下规则： ```js rules: { 'vue/no-deprecated-slot-attribute': 'off' } ``` # 与 Angular 集成 在 Angular 中使用 mdui 时，首先需要按照 [安装](/zh-cn/docs/2/getting-started/installation#npm) 页面的指引完成安装，然后进行一些必要的配置。 ## 配置 {#configuration} 首先，我们需要在 Angular 中启用 Web Components 的支持。示例如下： ```js import { BrowserModule } from '@angular/platform-browser'; import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'; import { AppComponent } from './app.component'; @NgModule({ declarations: [AppComponent], imports: [BrowserModule], providers: [], bootstrap: [AppComponent], schemas: [CUSTOM_ELEMENTS_SCHEMA] }) export class AppModule {} ``` 配置完成后，我们就可以在 Angular 组件代码中引入并使用 mdui 组件了： ```js import { Dialog } from 'mdui/components/dialog.js'; @Component({ selector: 'app-dialog-example', template: `
Dialog Content
` }) export class DialogExampleComponent implements OnInit { // 使用 @ViewChild 获取 #dialog 元素的引用 @ViewChild('dialog') dialog?: ElementRef; ... constructor(...) { } ngOnInit() { } ... openDialog() { // 使用 nativeElement 访问 mdui 组件 this.dialog?.nativeElement.open = true; } } ``` # 与其他框架集成 mdui 使用浏览器原生支持的 Web Components 开发，因此能在所有 Web 框架中使用。下面列举了在常用框架中使用 mdui 的方法。 ## Aurelia {#Aurelia} 在按照 [安装](/zh-cn/docs/2/getting-started/installation#npm) 页面的指引完成安装后，还需要安装和配置一个额外的包（仅适用于 Aurelia 2）： ```bash npm install aurelia-mdui --save ``` 然后将其注册到应用中： ```typescript import { MduiWebTask } from 'aurelia-mdui'; Aurelia .register(MduiWebTask) .app(MyApp) .start(); ``` **注意** 请将错误报告发送到 [https://github.com/mreiche/aurelia-mdui](https://github.com/mreiche/aurelia-mdui) ## WebCell {#WebCell} 在 [WebCell](https://web-cell.dev/) 中使用 mdui 时，只需要按照 [安装](/zh-cn/docs/2/getting-started/installation#npm) 页面的步骤完成安装即可，Web Components、TypeScript 和 JSX 支持是一级特性且开箱即用的。 或者，您可用 [官方 GitHub 模板仓库](https://github.com/EasyWebApp/WebCell-mobile) 来 [一键创建新项目](https://github.com/new?template_name=WebCell-mobile&template_owner=EasyWebApp)。 # 头像组件 Avatar 头像用于表示用户或事物，支持多种形式，包括图片、图标或字符等。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/avatar.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { Avatar } from 'mdui/components/avatar.js'; ``` 使用示例： ```html ``` ## 示例 {#examples} ### 图片头像 {#example-src} 可以使用 `src` 属性指定一个图片链接作为头像，或者在 default slot 中提供一个 `` 元素作为头像。 ```html 图片头像示例 ``` 可以使用 `fit` 属性定义图片如何适应容器框，类似于原生的 [`object-fit`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit)。 ### 图标头像 {#example-icon} 可以使用 `icon` 属性指定一个 Material Icons 图标作为头像，或者在 default slot 中提供一个图标元素作为头像。 ```html ``` ### 字符头像 {#example-char} 可以在 default slot 中使用任意文字作为头像。 ```html A ``` ## mdui-avatar API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
src src true string

头像图片的 URL 地址
fit fit true 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'

图片如何适应容器框，与原生的 object-fit 属性相同。可选值包括：

  • contain：保持图片原有尺寸比例，内容会被等比例缩放
  • cover：保持图片原有尺寸比例，但部分内容可能被剪切
  • fill：默认值，不保持图片原有尺寸比例，内容会被拉伸以填充整个容器
  • none：保留图片原有尺寸，内容不会被缩放或拉伸
  • scale-down：保持图片原有尺寸比例，内容尺寸与 none 或 contain 中较小的一个相同
icon icon true string

头像的 Material Icons 图标名
label label true string

头像的替代文本描述
### Slots
名称 描述
默认

自定义头像内容，可以为字母、汉字、<img> 元素、图标等
### CSS Parts
名称 描述
image

使用图片作为头像时，组件内部的 <img> 元素
icon

使用图标作为头像时，组件内部的 <mdui-icon> 元素
### CSS 自定义属性
名称 描述
--shape-corner

组件的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
# 徽标组件 Badge 徽标用于展示动态信息，如计数或状态指示。它可以包含文字或数字。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/badge.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { Badge } from 'mdui/components/badge.js'; ``` 使用示例： ```html 12 ``` ## 示例 {#examples} ### 形状 {#example-variant} 使用 `variant` 属性来设置徽标的形状。当 `variant` 为 `large` 时，将显示大型徽标。你可以在 default slot 中指定要显示的文本。 ```html 99+ ``` ## mdui-badge API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
variant variant true 'small' | 'large' 'large'

徽标的形状。可选值包括：

  • small：小型徽标，不显示文本
  • large：大型徽标，会显示文本
### Slots
名称 描述
默认

徽标中显示的文本
### CSS 自定义属性
名称 描述
--shape-corner

组件的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
# 底部应用栏组件 BottomAppBar 底部应用栏主要用于在移动端页面底部展示导航项和其他重要操作。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/bottom-app-bar.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { BottomAppBar } from 'mdui/components/bottom-app-bar.js'; ``` 使用示例：（注意：示例中的 `style="position: relative"` 是为了演示需要，实际使用时请移除该样式。） ```html
``` **注意事项：** 该组件默认使用 `position: fixed` 定位，并会自动在 `body` 上添加 `padding-bottom` 样式，以防止页面内容被该组件遮挡。 但在以下两种情况下，会默认使用 `position: absolute` 定位： 1. 当指定了 `scroll-target` 属性时。此时会在 `scroll-target` 的元素上添加 `padding-bottom` 样式。 2. 当位于 [``](/zh-cn/docs/2/components/layout) 组件中时。此时不会添加 `padding-bottom` 样式。 ## 示例 {#examples} ### 位于指定容器内 {#example-scroll-target} 默认情况下，底部应用栏会相对于当前窗口，在页面底部显示。 如果你希望将底部应用栏放在指定的容器内，可以指定 `scroll-target` 属性，其值为可滚动内容的容器的 CSS 选择器或 DOM 元素。此时，底部应用栏会相对于父元素显示（你需要自行在父元素上添加 `position: relative; overflow: hidden` 样式）。 ```html
Content
``` ### 滚动时隐藏 {#example-scroll-behavior} 设置 `scroll-behavior` 属性为 `hide`，可以在页面向下滚动时隐藏底部应用栏，向上滚动时显示底部应用栏。 使用 `scroll-threshold` 属性，可以设置滚动多少像素后开始隐藏底部应用栏。 ```html
Content
``` ### 固定浮动操作按钮 {#example-fab-detach} 如果底部应用栏中包含了[浮动操作按钮](/zh-cn/docs/2/components/fab)，则可以添加 `fab-detach` 属性，使得在页面滚动，底部应用栏隐藏时，浮动操作按钮仍然停留在页面右下角。 ```html
``` ## mdui-bottom-app-bar API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
hide hide true boolean false

是否隐藏
fab-detach fabDetach true boolean false

是否让底部应用栏中的 <mdui-fab> 组件脱离应用栏。如果为 true，则当应用栏隐藏后，<mdui-fab> 仍会停留在页面上
scroll-behavior scrollBehavior true 'hide' | 'shrink' | 'elevate'

滚动行为。可选值为：

  • hide：滚动时隐藏
scroll-target scrollTarget false string | HTMLElement | JQ<HTMLElement>

需要监听其滚动事件的元素。值可以是 CSS 选择器、DOM 元素、或 JQ 对象。默认监听 window 的滚动事件
scroll-threshold scrollThreshold true number

在滚动多少距离之后触发滚动行为，单位为 px
order order true number

该组件在 <mdui-layout> 中的布局顺序，按从小到大排序。默认为 0
### 事件
名称 描述
show

开始显示时，事件被触发。可以通过调用 event.preventDefault() 阻止显示
shown

显示动画完成时，事件被触发
hide

开始隐藏时，事件被触发。可以通过调用 event.preventDefault() 阻止隐藏
hidden

隐藏动画完成时，事件被触发
### Slots
名称 描述
默认

底部应用栏内部的元素
### CSS 自定义属性
名称 描述
--shape-corner

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

组件的 CSS z-index 值
# 按钮组件 Button 按钮主要用于执行一些操作，例如发送邮件、分享文档或点赞评论等。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/button.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { Button } from 'mdui/components/button.js'; ``` 使用示例： ```html Button ``` ## 示例 {#examples} ### 形状 {#example-variant} 使用 `variant` 属性设置按钮的形状。 ```html Elevated Filled Tonal Outlined Text ``` ### 全宽 {#example-full-width} 添加 `full-width` 属性可以使按钮显示为块状元素，即占据全部宽度。 ```html Button ``` ### 图标 {#example-icon} 设置 `icon`、`end-icon` 属性，可以分别在按钮左侧、右侧添加 Material Icons 图标。也可以通过 `icon`、`end-icon` slot 在按钮左侧、右侧添加元素。 ```html Icon Slot ``` ### 链接 {#example-link} 设置 `href` 属性，可以使按钮变为链接，此时还可以使用这些和链接相关的属性：`download`、`target`、`rel`。 ```html Link ``` ### 禁用及 loading 状态 {#example-disabled} 添加 `disabled` 属性可以禁用按钮；添加 `loading` 属性可以为按钮添加加载中状态。 ```html Disabled Loading Loading & Disabled ``` ## mdui-button API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
variant variant true 'elevated' | 'filled' | 'tonal' | 'outlined' | 'text' 'filled'

按钮的形状。可选值包括：

  • elevated：带阴影的按钮，适用于需要将按钮与背景视觉分离的场景
  • filled：视觉效果强烈，适用于重要流程的最终操作，如“保存”、“确认”等
  • tonal：视觉效果介于 filled 和 outlined 之间，适用于中高优先级的操作，如流程中的“下一步”
  • outlined：带边框的按钮，适用于中等优先级，且次要的操作，如“返回”
  • text：文本按钮，适用于最低优先级的操作
full-width fullWidth true boolean false

是否填满父元素宽度
icon icon true string

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

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

链接的目标 URL。

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

下载链接的目标。

Note：仅在设置了 href 属性时，此属性才有效。
target target true '_blank' | '_parent' | '_self' | '_top'

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

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

Note：仅在设置了 href 属性时，此属性才有效。
rel rel true '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 属性时可用。
autofocus autofocus true boolean false

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

元素在使用 Tab 键切换焦点时的顺序
disabled disabled true boolean false

是否禁用
loading loading true boolean false

是否处于加载中状态
name name true string ''

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

Note：仅在未设置 href 属性时，此属性才有效。
value value true string ''

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

Note：仅在未设置 href 属性时，此属性才有效。
type type true 'submit' | 'reset' | 'button' 'button'

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

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

Note：仅在未指定 href 属性时，此属性才有效。
form form true string

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

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

Note：仅在未指定 href 属性时，此属性才有效。
formaction formAction true string

指定提交表单的 URL。

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

Note：仅在未指定 href 属性且 type="submit" 时，此属性才有效。
formenctype formEnctype true '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" 时，此属性才有效。
formmethod formMethod true 'post' | 'get'

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

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

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

Note：仅在未设置 href 属性且 type="submit" 时，此属性才有效。
formnovalidate formNoValidate true boolean false

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

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

Note：仅在未设置 href 属性且 type="submit" 时，此属性才有效。
formtarget formTarget true '_self' | '_blank' | '_parent' | '_top'

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

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

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

Note：仅在未设置 href 属性且 type="submit" 时，此属性才有效。
undefined validity false ValidityState

表单验证状态对象，具体参见 ValidityState
undefined validationMessage false string

如果表单验证未通过，此属性将包含提示信息。如果验证通过，此属性将为空字符串
### 方法
名称 描述
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

按钮左侧的元素
end-icon

按钮右侧的元素
### CSS Parts
名称 描述
button

内部的 <button> 或 <a> 元素
label

按钮的文本
icon

按钮左侧的图标
end-icon

按钮右侧的图标
loading

加载中状态的 <mdui-circular-progress> 元素
### CSS 自定义属性
名称 描述
--shape-corner

组件的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
# 图标按钮组件 ButtonIcon 图标按钮主要用于执行一些次要的操作。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/button-icon.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { ButtonIcon } from 'mdui/components/button-icon.js'; ``` 使用示例： ```html ``` ## 示例 {#examples} ### 图标 {#example-icon} 使用 `icon` 属性指定 Material Icons 图标名称。也可以通过 default slot 指定图标元素。 ```html ``` ### 形状 {#example-variant} 使用 `variant` 属性设置图标按钮的形状。 ```html ``` ### 可选中 {#example-selectable} 添加 `selectable` 属性使图标按钮可被选中。 ```html ``` 使用 `selected-icon` 属性指定选中状态的 Material Icons 图标名称。也可以通过 `selected-icon` slot 指定选中状态的图标元素。 ```html ``` 图标按钮被选中后，`selected` 属性变为 `true`。也可以通过添加 `selected` 属性，使图标按钮默认处于选中状态。 ```html ``` ### 链接 {#example-link} 添加 `href` 属性，可使图标按钮变为链接，此时还可使用这些和链接相关的属性：`download`、`target`、`rel`。 ```html ``` ### 禁用及 loading 状态 {#example-disabled} 添加 `disabled` 属性可禁用图标按钮；添加 `loading` 属性可为图标按钮添加加载中状态。 ```html ``` ## mdui-button-icon API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
variant variant true 'standard' | 'filled' | 'tonal' | 'outlined' 'standard'

图标按钮的形状。可选值包括：

  • standard：适用于最低优先级的操作
  • filled：视觉效果强烈，适用于高优先级的操作
  • tonal：视觉效果介于 filled 和 outlined 之间，适用于中高优先级的操作
  • outlined：适用于中等优先级的操作
icon icon true string

Material Icons 图标名。也可以通过 default slot 设置
selected-icon selectedIcon true string

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

是否可选中
selected selected true boolean false

是否已被选中
href href true string

链接的目标 URL。

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

下载链接的目标。

Note：仅在设置了 href 属性时，此属性才有效。
target target true '_blank' | '_parent' | '_self' | '_top'

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

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

Note：仅在设置了 href 属性时，此属性才有效。
rel rel true '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 属性时可用。
autofocus autofocus true boolean false

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

元素在使用 Tab 键切换焦点时的顺序
disabled disabled true boolean false

是否禁用
loading loading true boolean false

是否处于加载中状态
name name true string ''

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

Note：仅在未设置 href 属性时，此属性才有效。
value value true string ''

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

Note：仅在未设置 href 属性时，此属性才有效。
type type true 'submit' | 'reset' | 'button' 'button'

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

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

Note：仅在未指定 href 属性时，此属性才有效。
form form true string

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

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

Note：仅在未指定 href 属性时，此属性才有效。
formaction formAction true string

指定提交表单的 URL。

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

Note：仅在未指定 href 属性且 type="submit" 时，此属性才有效。
formenctype formEnctype true '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" 时，此属性才有效。
formmethod formMethod true 'post' | 'get'

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

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

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

Note：仅在未设置 href 属性且 type="submit" 时，此属性才有效。
formnovalidate formNoValidate true boolean false

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

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

Note：仅在未设置 href 属性且 type="submit" 时，此属性才有效。
formtarget formTarget true '_self' | '_blank' | '_parent' | '_top'

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

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

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

Note：仅在未设置 href 属性且 type="submit" 时，此属性才有效。
undefined validity false ValidityState

表单验证状态对象，具体参见 ValidityState
undefined validationMessage false string

如果表单验证未通过，此属性将包含提示信息。如果验证通过，此属性将为空字符串
### 方法
名称 描述
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

失去焦点时触发
change

选中状态变更时触发
invalid

表单字段验证未通过时触发
### Slots
名称 描述
默认

图标组件
selected-icon

选中状态显示的图标元素
### CSS Parts
名称 描述
button

内部的 <button> 或 <a> 元素
icon

未选中状态的图标
selected-icon

选中状态的图标
loading

加载中状态的 <mdui-circular-progress> 元素
### CSS 自定义属性
名称 描述
--shape-corner

组件的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
# 卡片组件 Card 卡片是一个多功能组件，用于承载与单一主题相关的内容和操作。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/card.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { Card } from 'mdui/components/card.js'; ``` 使用示例： ```html Card ``` ## 示例 {#examples} ### 形状 {#example-variant} 使用 `variant` 属性设置卡片的形状。 ```html ``` ### 可点击 {#example-clickable} 添加 `clickable` 属性可以使卡片可点击，此时会添加鼠标悬浮效果和点击涟漪效果。 ```html ``` ### 链接 {#example-link} 添加 `href` 属性，可以使卡片变为链接，此时还可以使用这些和链接相关的属性：`download`、`target`、`rel`。 ```html ``` ### 禁用状态 {#example-disabled} 添加 `disabled` 属性可以禁用卡片。 ```html ``` ## mdui-card API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
variant variant true 'elevated' | 'filled' | 'outlined' 'elevated'

卡片的形状。可选值包括：

  • elevated：带阴影的卡片，与背景的视觉分离度较高
  • filled：带填充色的卡片，与背景的视觉分离度较低
  • outlined：带边框的卡片，与背景的视觉分离度最高
clickable clickable true boolean false

是否可点击。为 true 时，卡片将具有鼠标悬浮效果和点击涟漪效果
disabled disabled true boolean false

是否禁用
href href true string

链接的目标 URL。

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

下载链接的目标。

Note：仅在设置了 href 属性时，此属性才有效。
target target true '_blank' | '_parent' | '_self' | '_top'

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

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

Note：仅在设置了 href 属性时，此属性才有效。
rel rel true '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 属性时可用。
autofocus autofocus true boolean false

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

元素在使用 Tab 键切换焦点时的顺序
### 方法
名称 描述
click(): void

模拟鼠标点击元素
focus(options?: FocusOptions): void

将焦点设置到当前元素。

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

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

移除当前元素的焦点
### 事件
名称 描述
focus

获得焦点时触发
blur

失去焦点时触发
### Slots
名称 描述
默认

卡片的内容
### CSS 自定义属性
名称 描述
--shape-corner

组件的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
# 复选框组件 Checkbox 复选框允许用户从一组选项中选择一个或多个选项，或者切换单个选项的开/关状态。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/checkbox.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { Checkbox } from 'mdui/components/checkbox.js'; ``` 使用示例： ```html Checkbox ``` ## 示例 {#examples} ### 选中状态 {#example-checked} 复选框选中时，`checked` 属性值为 `true`。添加 `checked` 属性可以使复选框默认处于选中状态。 ```html Checkbox ``` ### 禁用状态 {#example-disabled} 添加 `disabled` 属性可以禁用复选框。 ```html Checkbox Checkbox ``` ### 不确定状态 {#example-indeterminate} 添加 `indeterminate` 属性表示复选框处于不确定状态。 ```html Checkbox ``` ### 图标 {#example-icon} 通过设置 `unchecked-icon`、`checked-icon`、`indeterminate-icon` 属性，可以分别设置未选中、选中、不确定状态时的复选框的 Material Icons 图标。也可以通过 `unchecked-icon`、`checked-icon`、`indeterminate-icon` slot 进行设置。 ```html Checkbox Checkbox
Checkbox Checkbox ``` ## mdui-checkbox API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
disabled disabled true boolean false

是否为禁用状态
checked checked true boolean false

是否为选中状态
undefined defaultChecked false boolean false

默认选中状态。在重置表单时，将恢复为此状态。此属性只能通过 JavaScript 属性设置
indeterminate indeterminate true boolean false

是否处于不确定状态
required required true boolean false

提交表单时，是否必须选中此复选框
form form true string

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

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

复选框名称，将与表单数据一起提交
value value true string 'on'

复选框的值，将于表单数据一起提交
unchecked-icon uncheckedIcon true string

未选中状态的 Material Icons 图标名。也可以通过 slot="unchecked-icon" 设置
checked-icon checkedIcon true string

选中状态的 Material Icons 图标名。也可以通过 slot="checked-icon" 设置
indeterminate-icon indeterminateIcon true string

不确定状态的 Material Icons 图标名。也可以通过 slot="indeterminate-icon" 设置
undefined validity false ValidityState

表单验证状态对象，具体参见 ValidityState
undefined validationMessage false string

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

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

元素在使用 Tab 键切换焦点时的顺序
### 方法
名称 描述
checkValidity(): boolean

检查表单字段是否通过验证。如果未通过，返回 false 并触发 invalid 事件；如果通过，返回 true
reportValidity(): boolean

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

如果验证未通过，还会在组件上显示验证失败的提示。
setCustomValidity(message: string): void

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

模拟鼠标点击元素
focus(options?: FocusOptions): void

将焦点设置到当前元素。

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

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

移除当前元素的焦点
### 事件
名称 描述
focus

获得焦点时触发
blur

失去焦点时触发
change

选中状态变更时触发
input

选中状态变更时触发
invalid

表单字段验证未通过时触发
### Slots
名称 描述
默认

复选框文本
unchecked-icon

未选中状态的图标
checked-icon

选中状态的图标
indeterminate-icon

不确定状态的图标
### CSS Parts
名称 描述
control

左侧图标容器
unchecked-icon

未选中状态的图标
checked-icon

选中状态的图标
indeterminate-icon

不确定状态的图标
label

复选框文本
# 纸片组件 Chip 纸片组件用于辅助用户输入信息、进行选择、筛选内容或执行相关操作。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/chip.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { Chip } from 'mdui/components/chip.js'; ``` 使用示例： ```html Chip ``` ## 示例 {#examples} ### 形状 {#example-variant} 使用 `variant` 属性设置纸片的形状。纸片有 4 种形状，可以根据用途选择： * `assist`：用于显示与当前上下文相关的辅助操作。例如，在点餐页面，提供分享，收藏等功能。 * `filter`：用于对内容进行筛选。例如，在搜索结果页，对搜索结果进行过滤。 * `input`：用于表示用户输入的信息片段。例如，在 Gmail 中的“收件人”字段中的联系人。 * `suggestion`：用于提供动态生成的推荐信息，以简化用户操作。例如，在聊天应用中猜测用户可能想发送的信息，供用户选择。 ```html Assist Filter Input Suggestion ``` ### 阴影 {#example-elevated} 添加 `elevated` 属性可以使纸片拥有阴影。 ```html Chip ``` ### 图标 {#example-icon} 添加 `icon`、`end-icon` 属性，可以分别在纸片左侧、右侧添加 Material Icons 图标。也可以通过 `icon`、`end-icon` slot 在纸片左侧、右侧添加元素。 ```html Icon End Icon Slot ``` ### 链接 {#example-link} 添加 `href` 属性，可以使纸片变为链接，此时还可以使用这些和链接相关的属性：`download`、`target`、`rel`。 ```html Link ``` ### 禁用及加载中状态 {#example-disabled} 添加 `disabled` 属性可以禁用纸片；添加 `loading` 属性可以为纸片添加加载中状态。 ```html Disabled Loading Loading & Disabled ``` ### 可选中 {#example-selectable} 添加 `selectable` 属性可以使纸片可被选中。 ```html Chip ``` 使用 `selected-icon` 属性可以指定选中状态的 Material Icons 图标名称。也可以通过 `selected-icon` slot 指定选中状态的图标元素。 ```html Chip Chip ``` 纸片被选中后，`selected` 属性变为 `true`。也可以通过添加 `selected` 属性，使纸片默认处于选中状态。 ```html Chip ``` ### 可删除 {#example-deletable} 添加 `deletable` 属性后，纸片右侧会出现一个删除图标。点击该图标会触发 `delete` 事件。您可以通过 `delete-icon` 属性指定删除图标的 Material Icons 图标名，或者通过 `delete-icon` slot 指定删除图标的元素。 ```html Chip Chip Chip ``` ## mdui-chip API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
variant variant true 'assist' | 'filter' | 'input' | 'suggestion' 'assist'

纸片的形状。可选值包括：

  • assist：用于显示与当前上下文相关的辅助操作，如在点餐页面提供分享、收藏等功能
  • filter：用于对内容进行筛选，如在搜索结果页过滤搜索结果
  • input：用于表示用户输入的信息片段，如在 Gmail 的“收件人”字段中的联系人
  • suggestion：用于提供动态生成的推荐信息，以简化用户操作，如在聊天应用中预测用户可能想发送的信息
elevated elevated true boolean false

是否显示阴影
selectable selectable true boolean false

是否可选中
selected selected true boolean false

是否已选中
deletable deletable true boolean false

是否可删除。为 true 时，纸片右侧会显示删除图标
icon icon true string

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

选中状态下左侧的 Material Icons 图标名。也可以通过 slot="selected-icon" 设置
end-icon endIcon true string

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

可删除时，右侧删除图标的 Material Icons 图标名。也可以通过 slot="delete-icon" 设置
href href true string

链接的目标 URL。

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

下载链接的目标。

Note：仅在设置了 href 属性时，此属性才有效。
target target true '_blank' | '_parent' | '_self' | '_top'

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

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

Note：仅在设置了 href 属性时，此属性才有效。
rel rel true '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 属性时可用。
autofocus autofocus true boolean false

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

元素在使用 Tab 键切换焦点时的顺序
disabled disabled true boolean false

是否禁用
loading loading true boolean false

是否处于加载中状态
name name true string ''

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

Note：仅在未设置 href 属性时，此属性才有效。
value value true string ''

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

Note：仅在未设置 href 属性时，此属性才有效。
type type true 'submit' | 'reset' | 'button' 'button'

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

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

Note：仅在未指定 href 属性时，此属性才有效。
form form true string

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

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

Note：仅在未指定 href 属性时，此属性才有效。
formaction formAction true string

指定提交表单的 URL。

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

Note：仅在未指定 href 属性且 type="submit" 时，此属性才有效。
formenctype formEnctype true '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" 时，此属性才有效。
formmethod formMethod true 'post' | 'get'

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

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

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

Note：仅在未设置 href 属性且 type="submit" 时，此属性才有效。
formnovalidate formNoValidate true boolean false

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

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

Note：仅在未设置 href 属性且 type="submit" 时，此属性才有效。
formtarget formTarget true '_self' | '_blank' | '_parent' | '_top'

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

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

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

Note：仅在未设置 href 属性且 type="submit" 时，此属性才有效。
undefined validity false ValidityState

表单验证状态对象，具体参见 ValidityState
undefined validationMessage false string

如果表单验证未通过，此属性将包含提示信息。如果验证通过，此属性将为空字符串
### 方法
名称 描述
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

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

选中状态变更时触发
delete

点击删除图标时触发
### Slots
名称 描述
默认

纸片文本
icon

左侧元素
end-icon

右侧元素
selected-icon

选中状态下的左侧元素
delete-icon

可删除时的右侧删除元素
### CSS Parts
名称 描述
button

内部的 <button> 或 <a> 元素
label

纸片文本
icon

左侧图标
end-icon

右侧图标
selected-icon

选中状态下的左侧图标
delete-icon

可删除时的右侧删除图标
loading

加载中状态的 <mdui-circular-progress> 元素
### CSS 自定义属性
名称 描述
--shape-corner

组件的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
# 圆形进度指示器组件 CircularProgress 圆形进度指示器是一个用于显示任务进度的圆形组件，例如数据加载或表单提交等。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/circular-progress.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { CircularProgress } from 'mdui/components/circular-progress.js'; ``` 使用示例： ```html ``` ## 示例 {#examples} ### 固定进度 {#example-value} 圆形进度指示器默认为不确定的进度，可以通过 `value` 属性设置当前进度，默认进度最大值为 `1`。 ```html ``` 可以通过 `max` 属性设置进度的最大值。 ```html ``` ## mdui-circular-progress API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
max max true number 1

进度指示器的最大值。默认为 1
value value false number

进度指示器的当前值。如果未指定该值，则显示为不确定状态
# 折叠面板组件 Collapse 折叠面板组件用于将复杂的内容区域进行分组和隐藏，以保持页面的整洁。 请注意，折叠面板组件本身不包含任何样式，你需要自行添加样式，或者与其他组件一起使用。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/collapse.js'; import 'mdui/components/collapse-item.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { Collapse } from 'mdui/components/collapse.js'; import type { CollapseItem } from 'mdui/components/collapse-item.js'; ``` 使用示例： ```html first content second content ``` ## 示例 {#examples} ### 面板标题与内容 {#example-header} 通过 `` 组件的 `header` 属性可以设置面板头部的文本，也可以通过 `header` slot 来指定面板头部元素。组件的 default slot 用于面板内容。 ```html Item 1
Item 1 - subitem
Item 2
Item 2 - subitem
``` ### 手风琴模式 {#example-accordion} 在 `` 组件上添加 `accordion` 属性可以启用手风琴模式，这样一次只会有一个面板处于打开状态。 ```html Item 1
Item 1 - subitem
Item 2
Item 2 - subitem
``` ### 设置激活的面板 {#example-value} 通过 `` 组件的 `value` 属性，你可以获取当前打开的面板，或设置需要打开的面板。 在手风琴模式下，`value` 属性的值为字符串，你可以使用 HTML 属性或 JavaScript 属性来操作该属性；在非手风琴模式下，`value` 属性的值为数组，此时只能通过 JavaScript 属性进行操作。 ```html 手风琴模式 Item 1
Item 1 - subitem
Item 2
Item 2 - subitem
非手风琴模式 Item 1
Item 1 - subitem
Item 2
Item 2 - subitem
``` ### 禁用状态 {#example-disabled} 通过在 `` 组件上添加 `disabled` 属性，可以禁用整个折叠面板组。同样，通过在 `` 组件上添加 `disabled` 属性，可以禁用特定的折叠面板。 ```html 全部禁用 Item 1
Item 1 - subitem
Item 2
Item 2 - subitem
禁用第一个面板 Item 1
Item 1 - subitem
Item 2
Item 2 - subitem
``` ### 触发折叠的元素 {#example-trigger} 默认情况下，点击整个面板头部区域会触发折叠。你可以通过设置 `` 组件的 `trigger` 属性来指定触发折叠的元素。`trigger` 属性可以是 CSS 选择器或 DOM 元素。 ```html Item 1
Item 1 - subitem
``` ## mdui-collapse-item API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
value value true string

此折叠面板项的值
header header true string

此折叠面板项的头部文本
disabled disabled true boolean false

是否禁用此折叠面板项
trigger trigger false string | HTMLElement | JQ<HTMLElement>

点击该元素时触发折叠，值可以是 CSS 选择器、DOM 元素、或 JQ 对象。默认为点击整个 header 区域触发
### 事件
名称 描述
open

开始打开时，事件被触发
opened

打开动画完成时，事件被触发
close

开始关闭时，事件被触发
closed

关闭动画完成时，事件被触发
### Slots
名称 描述
默认

折叠面板项的正文内容
header

折叠面板项的头部内容
### CSS Parts
名称 描述
header

折叠面板的头部内容
body

折叠面板的正文内容
## mdui-collapse API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
accordion accordion true boolean false

是否启用手风琴模式
value value false string | string[]

当前展开的 <mdui-collapse-item> 的值

Note：该属性的 HTML 属性始终为字符串，只有在 accordion 为 true 时，才能设置初始值；该属性的 JavaScript 属性值在 accordion 为 true 时为字符串，在 accordion 为 false 时为字符串数组。因此，当 accordion 为 false 时，只能通过修改 JavaScript 属性值来改变此值。
disabled disabled true boolean false

是否禁用此折叠面板
### 事件
名称 描述
change

当前展开的折叠面板项变化时触发
### Slots
名称 描述
默认

<mdui-collapse-item> 组件
# 对话框组件 Dialog 对话框用于在用户的操作流程中提供重要提示。 除了直接使用该组件外，mdui 还提供了四个函数：[`mdui.dialog`](/zh-cn/docs/2/functions/dialog)、[`mdui.alert`](/zh-cn/docs/2/functions/alert)、[`mdui.confirm`](/zh-cn/docs/2/functions/confirm)、[`mdui.prompt`](/zh-cn/docs/2/functions/prompt)。这些函数可以简化 Dialog 组件的使用。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/dialog.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { Dialog } from 'mdui/components/dialog.js'; ``` 使用示例： ```html Dialog 关闭 打开对话框 ``` ## 示例 {#examples} ### 点击遮罩关闭 {#example-close-on-overlay-click} 添加 `close-on-overlay-click` 属性，点击遮罩层时会关闭对话框。 ```html Dialog 打开对话框 ``` ### 按下 ESC 键关闭 {#example-close-on-esc} 添加 `close-on-esc` 属性，按下 ESC 键时会关闭对话框。 ```html Dialog 打开对话框 ``` ### 全屏 {#example-fullscreen} 添加 `fullscreen` 属性，对话框会全屏显示。 ```html Dialog 关闭 打开对话框 ``` ### 图标 {#example-icon} 设置 `icon` 属性，对话框上方会添加 Material Icons 图标。 ```html Dialog 打开对话框 ``` 也可以通过 `icon` slot 在对话框上方添加图标元素。 ```html Dialog 打开对话框 ``` ### 标题与描述 {#example-headline} 通过 `headline` 和 `description` 属性设置对话框的标题和描述。 ```html 打开对话框 ``` 也可以通过 `headline` 和 `description` slot 来设置对话框的标题元素和描述元素。 ```html Delete selected images? Images will be permenantly removed from you account and all synced devices. 打开对话框 ``` ### 底部操作按钮 {#example-action} 可以通过 `action` slot 添加底部操作按钮。 ```html 取消 删除 打开对话框 ``` 添加 `stacked-actions` 属性，使底部操作按钮垂直排列。 ```html Turn on speed boost No thanks 打开对话框 ``` ### 顶部内容 {#example-header} 可以通过 `header` slot 设置对话框顶部内容。 ```html Title Save
打开对话框 ``` ## mdui-dialog API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
icon icon true string

顶部的 Material Icons 图标名。也可以通过 slot="icon" 设置
headline headline true string

标题。也可以通过 slot="headline" 设置
description description true string

标题下方的文本。也可以通过 slot="description" 设置
open open true boolean false

是否打开对话框
fullscreen fullscreen true boolean false

是否全屏显示对话框
close-on-esc closeOnEsc true boolean false

是否允许按下 ESC 键关闭对话框
close-on-overlay-click closeOnOverlayClick true boolean false

是否允许点击遮罩层关闭对话框
stacked-actions stackedActions true boolean false

是否垂直排列底部操作按钮
### 事件
名称 描述
open

对话框开始打开时触发。可以通过调用 event.preventDefault() 阻止对话框打开
opened

对话框打开动画完成后触发
close

对话框开始关闭时触发。可以通过调用 event.preventDefault() 阻止对话框关闭
closed

对话框关闭动画完成后触发
overlay-click

点击遮罩层时触发
### Slots
名称 描述
header

顶部元素，默认包含 icon slot 和 headline slot
icon

顶部图标
headline

顶部标题
description

标题下方的文本
默认

对话框主体内容
action

底部操作栏中的元素
### CSS Parts
名称 描述
overlay

遮罩层
panel

对话框容器
header

对话框 header 部分，包含 icon 和 headline
icon

顶部图标，位于 header 中
headline

顶部标题，位于 header 中
body

对话框 body 部分
description

副文本部分，位于 body 中
action

底部操作按钮
### CSS 自定义属性
名称 描述
--shape-corner

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

组件的 CSS z-index 值
# 分割线组件 Divider 分隔线是一条细线，用于在列表和容器中对内容进行分组。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/divider.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { Divider } from 'mdui/components/divider.js'; ``` 使用示例： ```html ``` ## 示例 {#examples} ### 垂直分割线 {#example-vertical} 添加 `vertical` 属性，可以使分割线垂直显示。 ```html
``` ### 左侧缩进 {#example-inset} 添加 `inset` 属性，可以使分割线左侧缩进。这通常用于列表中，以使分割线和左侧文本对齐。 ```html Item 1 Item 2 ``` ### 两侧缩进 {#example-middle} 添加 `middle` 属性，可以使分割线两侧缩进。 ```html Item 1 Item 2 ``` ## mdui-divider API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
vertical vertical true boolean false

是否为垂直分割线
inset inset true boolean false

是否进行左侧缩进
middle middle true boolean false

是否进行左右两侧缩进
# 下拉组件 Dropdown 下拉组件用于在一个弹出的控件中展示特定内容，通常与菜单组件一起使用。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/dropdown.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { Dropdown } from 'mdui/components/dropdown.js'; ``` 使用示例： ```html open dropdown Item 1 Item 2 ``` ## 示例 {#examples} ### 禁用状态 {#example-disabled} 添加 `disabled` 属性可以禁用下拉组件。 ```html open dropdown Item 1 Item 2 ``` ### 打开位置 {#example-placement} 使用 `placement` 属性可以设置下拉组件的打开位置。 ```html open dropdown Item 1 Item 2 ``` ### 触发方式 {#example-trigger} 使用 `trigger` 属性可以设置下拉组件的触发方式。 ```html open dropdown Item 1 Item 2 ``` ### 在光标处打开 {#example-open-on-pointer} 添加 `open-on-pointer` 属性可以在光标处打开下拉组件。通常与 `trigger="contextmenu"` 配合使用，实现用鼠标右键打开菜单。 ```html 在此区域使用鼠标右键打开菜单 Item 1 Item 2 ``` ### 保持菜单打开状态 {#example-stay-open-on-click} 在下拉组件中使用菜单时，默认点击菜单项后，会自动关闭下拉组件。通过添加 `stay-open-on-click` 属性，可以在点击菜单项时，保持下拉组件的打开状态。 ```html open dropdown Item 1 Item 2 ``` ### 打开/关闭的延时 {#example-delay} 在设置了 `trigger="hover"` 时，可以通过 `open-delay`、`close-delay` 属性设置打开和关闭的延时。 ```html open dropdown Item 1 Item 2 ``` ## mdui-dropdown API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
open open true boolean false

是否打开下拉组件
disabled disabled true boolean false

是否禁用下拉组件
trigger trigger true 'click' | 'hover' | 'focus' | 'contextmenu' | 'manual' | string 'click'

下拉组件的触发方式，支持多个值，用空格分隔。可选值包括：

  • click：点击触发
  • hover：鼠标悬浮触发
  • focus：聚焦触发
  • contextmenu：鼠标右键点击、或触摸长按触发
  • manual：仅能通过编程方式打开和关闭下拉组件，不能再指定其他触发方式
placement placement true 'auto' | 'top-start' | 'top' | 'top-end' | 'bottom-start' | 'bottom' | 'bottom-end' | 'left-start' | 'left' | 'left-end' | 'right-start' | 'right' | 'right-end' 'auto'

下拉组件内容的位置。可选值包括：

  • auto：自动判断位置
  • top-start：上方左对齐
  • top：上方居中
  • top-end：上方右对齐
  • bottom-start：下方左对齐
  • bottom：下方居中
  • bottom-end：下方右对齐
  • left-start：左侧顶部对齐
  • left：左侧居中
  • left-end：左侧底部对齐
  • right-start：右侧顶部对齐
  • right：右侧居中
  • right-end：右侧底部对齐
stay-open-on-click stayOpenOnClick true boolean false

点击 <mdui-menu-item> 后，下拉组件是否保持打开状态
open-delay openDelay true number 150

鼠标悬浮触发下拉组件打开的延时，单位为毫秒
close-delay closeDelay true number 150

鼠标悬浮触发下拉组件关闭的延时，单位为毫秒
open-on-pointer openOnPointer true boolean false

是否在触发下拉组件的光标位置打开下拉组件，常用于打开鼠标右键菜单
### 事件
名称 描述
open

下拉组件开始打开时，事件被触发。可以通过调用 event.preventDefault() 阻止下拉组件打开
opened

下拉组件打开动画完成时，事件被触发
close

下拉组件开始关闭时，事件被触发。可以通过调用 event.preventDefault() 阻止下拉组件关闭
closed

下拉组件关闭动画完成时，事件被触发
### Slots
名称 描述
默认

下拉组件的内容
trigger

触发下拉组件的元素，例如 <mdui-button> 元素
### CSS Parts
名称 描述
trigger

触发下拉组件的元素的容器，即 trigger slot 的容器
panel

下拉组件内容的容器
### CSS 自定义属性
名称 描述
--z-index

组件的 CSS z-index 值
# 浮动操作按钮组件 Fab 浮动操作按钮（FAB）用于突出显示页面上的主要操作，它将关键操作置于易于访问的位置。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/fab.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { Fab } from 'mdui/components/fab.js'; ``` 使用示例： ```html ``` ## 示例 {#examples} ### 图标 {#example-icon} 使用 `icon` 属性指定 Material Icons 图标名称。也可以通过 `icon` slot 指定图标元素。 ```html ``` ### 展开状态 {#example-extended} 添加 `extended` 属性可以将 FAB 设置为展开状态，此时 default slot 中的文本将显示出来。 ```html Compose ``` ### 形状 {#example-variant} 使用 `variant` 属性可以设置 FAB 的形状。 ```html ``` ### 大小 {#example-size} 使用 `size` 属性可以设置 FAB 的大小。 ```html ``` ### 链接 {#example-link} 添加 `href` 属性，可以使 FAB 具有链接功能，此时还可以使用与链接相关的属性：`download`、`target`、`rel`。 ```html ``` ### 禁用及加载中状态 {#example-disabled} 添加 `disabled` 属性可以禁用 FAB；添加 `loading` 属性可以为 FAB 添加加载中状态。 ```html ``` ## mdui-fab API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
variant variant true 'primary' | 'surface' | 'secondary' | 'tertiary' 'primary'

FAB 的形状，此组件的不同形状之间只有颜色不一样。可选值包括：

  • primary：使用 Primary container 背景色
  • surface：使用 Surface container high 背景色
  • secondary：使用 Secondary container 背景色
  • tertiary：使用 Tertiary container 背景色
size size true 'normal' | 'small' | 'large' 'normal'

FAB 的大小。可选值包括：

  • normal：普通大小 FAB
  • small：小型 FAB
  • large：大型 FAB
icon icon true string

Material Icons 图标名。也可以通过 slot="icon" 设置
extended extended true boolean false

是否为展开状态
href href true string

链接的目标 URL。

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

下载链接的目标。

Note：仅在设置了 href 属性时，此属性才有效。
target target true '_blank' | '_parent' | '_self' | '_top'

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

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

Note：仅在设置了 href 属性时，此属性才有效。
rel rel true '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 属性时可用。
autofocus autofocus true boolean false

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

元素在使用 Tab 键切换焦点时的顺序
disabled disabled true boolean false

是否禁用
loading loading true boolean false

是否处于加载中状态
name name true string ''

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

Note：仅在未设置 href 属性时，此属性才有效。
value value true string ''

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

Note：仅在未设置 href 属性时，此属性才有效。
type type true 'submit' | 'reset' | 'button' 'button'

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

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

Note：仅在未指定 href 属性时，此属性才有效。
form form true string

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

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

Note：仅在未指定 href 属性时，此属性才有效。
formaction formAction true string

指定提交表单的 URL。

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

Note：仅在未指定 href 属性且 type="submit" 时，此属性才有效。
formenctype formEnctype true '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" 时，此属性才有效。
formmethod formMethod true 'post' | 'get'

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

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

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

Note：仅在未设置 href 属性且 type="submit" 时，此属性才有效。
formnovalidate formNoValidate true boolean false

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

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

Note：仅在未设置 href 属性且 type="submit" 时，此属性才有效。
formtarget formTarget true '_self' | '_blank' | '_parent' | '_top'

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

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

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

Note：仅在未设置 href 属性且 type="submit" 时，此属性才有效。
undefined validity false ValidityState

表单验证状态对象，具体参见 ValidityState
undefined validationMessage false string

如果表单验证未通过，此属性将包含提示信息。如果验证通过，此属性将为空字符串
### 方法
名称 描述
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

图标
### CSS Parts
名称 描述
button

内部的 <button> 或 <a> 元素
label

右侧的文本
icon

左侧的图标
loading

加载中状态的 <mdui-circular-progress> 元素
### CSS 自定义属性
名称 描述
--shape-corner-small

size="small" 时，组件的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
--shape-corner-normal

size="normal" 时，组件的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
--shape-corner-large

size="large" 时，组件的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
# 图标组件 Icon 图标用于表示常见的操作。它支持 Material Icons 图标，也支持使用 SVG 图标。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/icon.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { Icon } from 'mdui/components/icon.js'; ``` 使用示例： ```html ``` ### 使用 Material Icons 图标 {#usage-material-icons} 如果需要通过该组件使用 Material Icons 图标，你需要单独导入 Material Icons 的 CSS 文件。Material Icons 共有 5 种变体，分别为：Filled、Outlined、Rounded、Sharp、Two Tone，请根据你要使用的图标变体，导入对应的 CSS 文件： ```html ``` 使用组件时，在 `name` 属性中传入图标名称，并以图标变体名称为后缀（Filled 变体无需添加后缀），下面是 `delete` 图标的 5 种变体的使用方式： ```html ``` 你可以直接在页面下方的 [Material Icons 图标搜索](/zh-cn/docs/2/components/icon#search) 工具中搜索图标，然后点击需要使用的图标，就会自动将图标代码复制到剪贴板。 另外，mdui 还提供了一个独立的包 [`@mdui/icons`](/zh-cn/docs/2/libraries/icons)，这个包里每一个图标组件都是一个独立的文件，使你可以按需导入需要的图标组件，而无需导入整个图标库。 ### 使用 SVG 图标 {#usage-svg} 该组件也支持使用 SVG 图标作为图标内容。可通过组件的 `src` 属性传入 SVG 图标的链接。例如： ```html ``` 也可以在组件的 default slot 中传入 SVG 的内容。例如： ```html ``` ## 示例 {#examples} ### 设置颜色 {#example-color} 设置 `` 元素或父元素的 `color` CSS 样式修改图标颜色。 ```html ``` ### 设置大小 {#example-size} 设置 `` 元素或父元素的 `font-size` CSS 样式修改图标大小。 ```html ``` ## mdui-icon API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
name name true string

Material Icons 图标名
src src true string

svg 图标的路径
### Slots
名称 描述
默认

svg 图标的内容
# 布局组件 Layout 布局组件提供了一个灵活的布局系统，用于创建复杂的页面布局。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/layout.js'; import 'mdui/components/layout-item.js'; import 'mdui/components/layout-main.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { Layout } from 'mdui/components/layout.js'; import type { LayoutItem } from 'mdui/components/layout-item.js'; import type { LayoutMain } from 'mdui/components/layout-main.js'; ``` **介绍：** 布局系统遵循从外向内的原则构建，每个布局组件（`` 组件）都会在四个方向（上、下、左、右）之一的位置占据空间，随后的布局组件会在剩余空间中继续占据空间。 以下组件直接继承自 `` 组件，因此也可以作为布局组件使用： * [``](/zh-cn/docs/2/components/navigation-bar) * [``](/zh-cn/docs/2/components/navigation-drawer) * [``](/zh-cn/docs/2/components/navigation-rail) * [``](/zh-cn/docs/2/components/bottom-app-bar) * [``](/zh-cn/docs/2/components/top-app-bar) 布局系统的最后一部分是 `` 组件，它会占据剩余空间，你可以在该组件内放置页面内容。 ## 示例 {#examples} ### 布局组件顺序 {#layout-default-order} 默认情况下，布局组件会按照在代码中出现的顺序来占据空间。你可以从下面两个示例来理解这个概念，这两个示例中，[``](/zh-cn/docs/2/components/top-app-bar) 和 [``](/zh-cn/docs/2/components/navigation-drawer) 在代码中出现的顺序不同。

请在大屏显示器上查看该示例。

```html Top App Bar Navigation drawer Main ``` ```html Navigation drawer Top App Bar Main ``` 可以发现，将 [``](/zh-cn/docs/2/components/top-app-bar) 放在 [``](/zh-cn/docs/2/components/navigation-drawer) 之前时，[``](/zh-cn/docs/2/components/top-app-bar) 会率先占满屏幕的宽度，而 [``](/zh-cn/docs/2/components/navigation-drawer) 只能在剩余的空间内占满高度。调换二者顺序后，[``](/zh-cn/docs/2/components/navigation-drawer) 会率先占满屏幕的高度，而 [``](/zh-cn/docs/2/components/top-app-bar) 只能在剩余的空间内占满宽度。 ### 布局组件位置 {#example-placement} 对于 `` 组件，你可以使用 `placement` 属性来指定其在布局中的上、下、左、右位置。 对于 [``](/zh-cn/docs/2/components/navigation-drawer) 和 [``](/zh-cn/docs/2/components/navigation-rail) 组件，你也可以使用 `placement` 属性来指定其在布局中的左、右位置。 下面的示例中，我们将两个 `` 组件放在了应用的两侧。 ```html Top App Bar Layout Item Layout Item Main ``` ### 自定义布局组件顺序 {#example-order} 在大多数情况下，只要按顺序放置布局组件就能实现你想要的布局。 你也可以使用 `order` 属性来指定布局顺序，系统将按 `order` 的值从小到大排列组件，`order` 相同时则按代码顺序排列。所有布局组件的默认 `order` 都为 `0`。 ```html Layout Item Top App Bar
order="-1" Main ``` ## mdui-layout-item API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
placement placement true 'top' | 'bottom' | 'left' | 'right' 'top'

组件的位置。可选值包括：

  • top：上方
  • bottom：下方
  • left：左侧
  • right：右侧
order order true number

该组件在 <mdui-layout> 中的布局顺序，按从小到大排序。默认为 0
### Slots
名称 描述
默认

可以包含任意内容
## mdui-layout-main API ### Slots
名称 描述
默认

可以包含任意内容
## mdui-layout API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
full-height fullHeight true boolean false

设置当前布局的高度为 100%
### Slots
名称 描述
默认

可以包含 <mdui-top-app-bar>、<mdui-bottom-app-bar>、<mdui-navigation-bar>、<mdui-navigation-drawer>、<mdui-navigation-rail>、<mdui-layout-item>、<mdui-layout-main> 元素
# 线性进度指示器组件 LinearProgress 线性进度指示器是一种横向的指示器，用于向用户展示任务的执行进度，如数据加载或表单提交等。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/linear-progress.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { LinearProgress } from 'mdui/components/linear-progress.js'; ``` 使用示例： ```html ``` ## 示例 {#examples} ### 设定进度 {#example-value} 线性进度指示器默认为不确定的进度，你可以通过 `value` 属性来设定当前的进度，默认的进度最大值为 `1`。 ```html ``` 你也可以通过 `max` 属性来设定进度的最大值。 ```html ``` ## mdui-linear-progress API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
max max true number 1

进度指示器的最大值。默认为 1
value value false number

进度指示器的当前值。如果未指定该值，则处于不确定状态
### CSS Parts
名称 描述
indicator

指示器部分
### CSS 自定义属性
名称 描述
--shape-corner

组件的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
# 列表组件 List 列表是一种垂直排列的索引，用于展示文本或图片，便于用户快速浏览和访问相关信息。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/list.js'; import 'mdui/components/list-item.js'; import 'mdui/components/list-subheader.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { List } from 'mdui/components/list.js'; import type { ListItem } from 'mdui/components/list-item.js'; import type { ListSubheader } from 'mdui/components/list-subheader.js'; ``` 使用示例： ```html Subheader Item 1 Item 2 ``` ## 示例 {#examples} ### 文本内容 {#example-text} 在 `` 组件上设置 `headline` 属性，可以设定列表项的主文本，设置 `description` 属性，可以设定副文本。 ```html ``` 也可以通过 default slot 设定主文本，通过 `description` slot 设定副文本。 ```html Headline Headline Supporting text ``` 默认情况下，主文本和副文本无论长度如何，都会完全显示。你可以通过设置 `headline-line` 和 `description-line` 属性为主文本和副文本添加行数限制，最多可以限制为 3 行。 ```html Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text ``` ### 两侧内容 {#example-side} 在 `` 组件上设置 `icon` 和 `end-icon` 属性，可以在列表项的左侧和右侧添加 Material Icons 图标。 ```html Headline ``` 也可以通过 `icon` 和 `end-icon` slot 在列表项的左侧和右侧添加元素。 ```html Headline ``` ### 链接 {#example-link} 通过设置 `href` 属性，可以将列表项转换为链接。此时，你还可以使用与链接相关的属性，如：`download`、`target` 和 `rel`。 ```html Headline ``` ### 禁用状态 {#example-disabled} 在 `` 组件上添加 `disabled` 属性，可以禁用该列表项。此时，列表项中的 checkbox、radio、switch 等组件也会被禁用。 ```html Headline Headline ``` ### 激活状态 {#example-active} 在 `` 组件上添加 `active` 属性，可以激活该列表项。 ```html Headline Headline ``` ### 不可点击状态 {#example-nonclickable} 在 `` 组件上添加 `nonclickable` 属性，可以移除列表项上的鼠标悬浮和点击涟漪效果。 ```html Headline Headline ``` ### 圆角形状 {#example-rounded} 在 `` 组件上添加 `rounded` 属性，可以使该列表项呈现圆角形状。 ```html Headline Headline ``` ### 垂直对齐方式 {#example-alignment} 在 `` 组件上设置 `alignment` 属性，可以调整列表项左右两侧元素与列表项的对齐方式。其值可以为： * `start`：顶部对齐 * `center`：居中对齐 * `end`：底部对齐 ```html Headline Headline Headline ``` ### 自定义内容 {#example-custom} 在 `` 组件中使用 `custom` slot，可以完全自定义列表项的内容。 ```html
test
 ``` ## mdui-list-item API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
headline headline true string

主文本。也可以通过 default slot 设置
headline-line headlineLine true 1 | 2 | 3

主文本行数，超过限制后将截断显示。默认无行数限制。可选值包括：

  • 1：显示单行，超出后截断
  • 2：显示两行，超出后截断
  • 3：显示三行，超出后截断
description description true string

副文本。也可以通过 slot="description" 设置
description-line descriptionLine true 1 | 2 | 3

副文本行数，超过限制后将截断显示。默认无行数限制。可选值包括：

  • 1：显示单行，超出后截断
  • 2：显示两行，超出后截断
  • 3：显示三行，超出后截断
icon icon true string

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

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

是否禁用该列表项，禁用后，列表项将变为灰色，且其中的 <mdui-checkbox>、<mdui-radio>、<mdui-switch> 等也将禁用
active active true boolean false

是否激活该列表项
nonclickable nonclickable true boolean false

是否使列表项不可点击。设置后，列表项中的 <mdui-checkbox>、<mdui-radio>、<mdui-switch> 等仍可交互
rounded rounded true boolean false

是否使用圆角形状的列表项
alignment alignment true 'start' | 'center' | 'end' 'center'

列表项的垂直对齐方式。可选值包括：

  • start：顶部对齐
  • center：居中对齐
  • end：底部对齐
href href true string

链接的目标 URL。

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

下载链接的目标。

Note：仅在设置了 href 属性时，此属性才有效。
target target true '_blank' | '_parent' | '_self' | '_top'

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

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

Note：仅在设置了 href 属性时，此属性才有效。
rel rel true '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 属性时可用。
autofocus autofocus true boolean false

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

元素在使用 Tab 键切换焦点时的顺序
### 方法
名称 描述
click(): void

模拟鼠标点击元素
focus(options?: FocusOptions): void

将焦点设置到当前元素。

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

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

移除当前元素的焦点
### 事件
名称 描述
focus

获得焦点时触发
blur

失去焦点时触发
### Slots
名称 描述
默认

主文本
description

副文本
icon

列表项左侧的元素
end-icon

列表项右侧的元素
custom

任意自定义内容
### CSS Parts
名称 描述
container

列表项容器
icon

左侧图标
end-icon

右侧图标
body

中间部分
headline

主标题
description

副标题
### CSS 自定义属性
名称 描述
--shape-corner

列表项的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
--shape-corner-rounded

指定了 rounded 属性时，列表项的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
## mdui-list-subheader API ### Slots
名称 描述
默认

列表标题文本
## mdui-list API ### Slots
名称 描述
默认

<mdui-list-item> 元素
# 菜单组件 Menu 菜单组件提供了一系列垂直排列的选项。当用户与按钮、或其他控件交互时，将显示菜单。 如果你需要实现下拉菜单，可以配合 [``](/zh-cn/docs/2/components/dropdown) 组件。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/menu.js'; import 'mdui/components/menu-item.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { Menu } from 'mdui/components/menu.js'; import type { MenuItem } from 'mdui/components/menu-item.js'; ``` 使用示例： ```html Item 1 Item 2 ``` ## 示例 {#examples} ### 下拉菜单 {#example-dropdown} 配合 [``](/zh-cn/docs/2/components/dropdown) 组件实现下拉菜单。 ```html open dropdown Item 1 Item 2 ``` ### 紧凑布局 {#example-dense} 在 `` 组件上添加 `dense` 属性，可以实现紧凑布局。 ```html Item 1 Item 2 Item 3 ``` ### 禁用菜单项 {#example-disabled} 在 `` 组件上添加 `disabled` 属性，可以禁用菜单项。 ```html Item 1 Item 2 Item 3 ``` ### 支持单选 {#example-selects-single} 在 `` 组件上指定 `selects` 属性为 `single`，可以实现单选功能。此时 `` 的 `value` 值即为当前选中的 `` 的 `value` 值。 ```html Item 1 Item 2 ``` ### 支持多选 {#example-selects-multiple} 在 `` 组件上指定 `selects` 属性为 `multiple`，可以实现多选功能。此时 `` 的 `value` 值即为当前选中的 `` 的 `value` 值组成的数组。 注意：在多选模式下，`` 的 `value` 值为数组，只能通过 JavaScript 属性来读取和设置该值。 ```html Item 1 Item 2 Item 3 ``` ### 图标 {#example-icon} 在 `` 组件上，通过设置 `icon` 和 `end-icon` 属性，可以分别在菜单项的左侧和右侧添加 Material Icons 图标。通过设置 `end-text` 属性，可以在右侧添加文本。此外，也可以通过 `icon`、`end-icon` 和 `end-text` slot 在菜单项的左侧和右侧添加图标和文本。 如果需要在菜单项左侧空出一个图标的位置以保持与其他菜单项的对齐，可以将 `icon` 属性设置为空字符串。 ```html Item 1 Item 2 Ctrl+X Item 3 ``` 在单选或多选模式下，可以通过 `selected-icon` 属性或 `selected-icon` slot 设置选中状态的图标。 ```html Item 1 Item 2 ``` ### 链接 {#example-link} 在 `` 组件上设置 `href` 属性，可以将菜单项转换为链接。此时，还可以使用与链接相关的属性，如：`download`、`target` 和 `rel`。 ```html Item 1 Item 2 ``` ### 子菜单 {#example-submenu} 在 `` 组件中，可以使用 `submenu` slot 来指定子菜单项的元素。 ```html Line spacing Single 1.5 Double Custom: 1.2 Paragraph style ``` 在 `` 组件上，可以通过 `submenu-trigger` 属性设置子菜单的触发方式。 ```html Line spacing Single 1.5 Double Custom: 1.2 Paragraph style ``` 当 `submenu-trigger` 属性设置为 `hover` 时，可以在 `` 组件上通过 `submenu-open-delay` 和 `submenu-close-delay` 属性设置子菜单的打开延时和关闭延时。 ```html Line spacing Single 1.5 Double Custom: 1.2 Paragraph style ``` ### 自定义内容 {#example-custom} 在 `` 组件中，你可以使用 `custom` slot 来完全自定义菜单项的内容。 ```html
ABS
取数值的绝对值
ACOS
数值的反余弦值，以弧度表示
ACOSH
数值的反双曲余弦值
 ``` ## mdui-menu-item API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
value value true string

菜单项的值
disabled disabled true boolean false

是否禁用菜单项
icon icon true string

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

如果左侧不需要显示图标，但需要预留一个图标的位置，可传入空字符串进行占位
end-icon endIcon true string

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

右侧的文本。也可以通过 slot="end-text" 设置
selected-icon selectedIcon true string

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

是否打开子菜单
href href true string

链接的目标 URL。

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

下载链接的目标。

Note：仅在设置了 href 属性时，此属性才有效。
target target true '_blank' | '_parent' | '_self' | '_top'

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

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

Note：仅在设置了 href 属性时，此属性才有效。
rel rel true '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 属性时可用。
autofocus autofocus true boolean false

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

元素在使用 Tab 键切换焦点时的顺序
### 方法
名称 描述
click(): void

模拟鼠标点击元素
focus(options?: FocusOptions): void

将焦点设置到当前元素。

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

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

移除当前元素的焦点
### 事件
名称 描述
focus

获得焦点时触发
blur

失去焦点时触发
submenu-open

子菜单开始打开时，事件被触发。可以通过调用 event.preventDefault() 阻止子菜单打开
submenu-opened

子菜单打开动画完成时，事件被触发
submenu-close

子菜单开始关闭时，事件被触发。可以通过调用 event.preventDefault() 阻止子菜单关闭
submenu-closed

子菜单关闭动画完成时，事件被触发
### Slots
名称 描述
默认

菜单项的文本
icon

菜单项左侧图标
end-icon

菜单项右侧图标
end-text

菜单右侧的文本
selected-icon

选中状态的图标
submenu

子菜单
custom

任意自定义内容
### CSS Parts
名称 描述
container

菜单项的容器
icon

左侧的图标
label

文本内容
end-icon

右侧的图标
end-text

右侧的文本
selected-icon

选中状态的图标
submenu

子菜单元素
## mdui-menu API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
selects selects true 'single' | 'multiple'

菜单项的可选状态。默认不可选。可选值包括：

  • single：单选
  • multiple：多选
value value false string | string[]

当前选中的 <mdui-menu-item> 的值。

Note：该属性的 HTML 属性始终为字符串，仅在 selects="single" 时可通过 HTML 属性设置初始值；该属性的 JavaScript 属性值在 selects="single" 时为字符串，在 selects="multiple" 时为字符串数组。因此，在 selects="multiple" 时，若要修改该值，只能通过修改 JavaScript 属性值实现。
dense dense true boolean false

菜单项是否使用紧凑布局
submenu-trigger submenuTrigger true 'click' | 'hover' | 'focus' | 'manual' | string 'click hover'

子菜单的触发方式，支持多个值，用空格分隔。可选值包括：

  • click：点击菜单项时打开子菜单
  • hover：鼠标悬浮到菜单项上时打开子菜单
  • focus：聚焦到菜单项上时打开子菜单
  • manual：仅能通过编程方式打开和关闭子菜单，不能再指定其他触发方式
submenu-open-delay submenuOpenDelay true number 200

鼠标悬浮触发子菜单打开的延时，单位毫秒
submenu-close-delay submenuCloseDelay true number 200

鼠标悬浮触发子菜单关闭的延时，单位毫秒
### 方法
名称 描述
focus(options?: FocusOptions): void

将焦点设置在当前元素上
blur(): void

从当前元素中移除焦点
### 事件
名称 描述
change

菜单项选中状态变化时触发
### Slots
名称 描述
默认

子菜单项（<mdui-menu-item>）、分割线（<mdui-divider>）等元素
### CSS 自定义属性
名称 描述
--shape-corner

组件的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
# 底部导航栏组件 NavigationBar 导航栏用于在移动端页面中方便地在几个主要页面之间进行切换。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/navigation-bar.js'; import 'mdui/components/navigation-bar-item.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { NavigationBar } from 'mdui/components/navigation-bar.js'; import type { NavigationBarItem } from 'mdui/components/navigation-bar-item.js'; ``` 使用示例：（示例中的 `style="position: relative"` 仅用于演示，实际使用时请移除该样式。） ```html Item 1 Item 2 Item 3 ``` **注意事项：** 该组件默认使用 `position: fixed` 定位，并会自动在 `body` 上添加 `padding-bottom` 样式，以防止页面内容被组件遮挡。但在以下两种情况下，会默认使用 `position: absolute` 定位： 1. 当指定了 `scroll-target` 属性时。此时会在 `scroll-target` 的元素上添加 `padding-bottom` 样式。 2. 当组件位于 [``](/zh-cn/docs/2/components/layout) 中时。此时不会添加 `padding-bottom` 样式。 ## 示例 {#examples} ### 文本标签显示状态 {#example-label-visibility} 导航栏中的文本标签默认在导航项小于等于 3 个时始终显示；当导航项大于 3 个时，仅显示选中状态的文本。 ```html Item 1 Item 2 Item 3
Item 1 Item 2 Item 3 Item 4 ``` 你可以通过在 `` 组件上设置 `label-visibility` 属性来调整文本标签的显示状态。可选值有： * `selected`：仅显示选中状态的文本 * `labeled`：始终显示文本 * `unlabeled`：始终不显示文本 ```html Item 1 Item 2 Item 3 selected labeled unlabeled ``` ### 位于指定容器内 {#example-scroll-target} 默认情况下，导航栏会相对于当前窗口，在页面底部显示。 如果你希望将导航栏放在指定的容器内，可以在 `` 组件上指定 `scroll-target` 属性。该属性的值应为可滚动内容的容器的 CSS 选择器或 DOM 元素。此时，导航栏会相对于父元素显示（你需要自行在父元素上添加 `position: relative; overflow: hidden` 样式）。 ```html
Item 1 Item 2 Item 3
页面内容
``` ### 滚动时隐藏 {#example-scroll-behavior} 通过在 `` 组件上设置 `scroll-behavior` 属性为 `hide`，可以实现页面向下滚动时隐藏导航栏，向上滚动时显示导航栏的效果。 使用 `scroll-threshold` 属性，可以设置滚动多少像素后开始隐藏导航栏。 ```html
Item 1 Item 2 Item 3
页面内容
``` ### 图标 {#example-icon} 在 `` 组件上，`icon` 属性用于设置未激活状态的导航项图标，`active-icon` 属性用于设置激活状态的导航项图标。也可以通过 `icon` 和 `active-icon` slot 来设置未激活和激活状态的图标元素。 ```html Item 1 Item 2 ``` ### 链接 {#example-link} 在 `` 组件上设置 `href` 属性，可以将导航项变为链接。此时，还可以使用与链接相关的属性：`download`、`target`、`rel`。 ```html Item 1 Item 2 ``` ### 徽标 {#example-badge} 在 `` 组件中，可以通过 `badge` slot 添加徽章。 ```html Item 1 99+ Item 2 ``` ## mdui-navigation-bar-item API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
icon icon true string

未激活状态的 Material Icons 图标名。也可以通过 slot="icon" 设置
active-icon activeIcon true string

激活状态的 Material Icons 图标名。也可以通过 slot="active-icon" 设置
value value true string

导航项的值
href href true string

链接的目标 URL。

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

下载链接的目标。

Note：仅在设置了 href 属性时，此属性才有效。
target target true '_blank' | '_parent' | '_self' | '_top'

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

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

Note：仅在设置了 href 属性时，此属性才有效。
rel rel true '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 属性时可用。
autofocus autofocus true boolean false

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

元素在使用 Tab 键切换焦点时的顺序
### 方法
名称 描述
click(): void

模拟鼠标点击元素
focus(options?: FocusOptions): void

将焦点设置到当前元素。

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

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

移除当前元素的焦点
### 事件
名称 描述
focus

获得焦点时触发
blur

失去焦点时触发
### Slots
名称 描述
默认

导航项文本
icon

图标
active-icon

激活状态的图标元素
badge

徽标
### CSS Parts
名称 描述
container

导航项容器
indicator

指示器
badge

徽标
icon

图标
active-icon

激活状态的图标
label

导航项文本
### CSS 自定义属性
名称 描述
--shape-corner-indicator

指示器的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
## mdui-navigation-bar API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
hide hide true boolean false

是否隐藏
label-visibility labelVisibility true 'auto' | 'selected' | 'labeled' | 'unlabeled' 'auto'

文本的可视状态。可选值包括：

  • auto：当选项小于等于3个时，始终显示文本；当选项大于3个时，仅显示选中状态的文本
  • selected：仅在选中状态显示文本
  • labeled：始终显示文本
  • unlabeled：始终不显示文本
value value true string

当前选中的 <mdui-navigation-bar-item> 的值
scroll-behavior scrollBehavior true 'hide' | 'shrink' | 'elevate'

滚动行为。可选值包括：

  • hide：滚动时隐藏
scroll-target scrollTarget false string | HTMLElement | JQ<HTMLElement>

需要监听其滚动事件的元素。值可以是 CSS 选择器、DOM 元素、或 JQ 对象。默认监听 window 的滚动事件
scroll-threshold scrollThreshold true number

在滚动多少距离之后触发滚动行为，单位为 px
order order true number

该组件在 <mdui-layout> 中的布局顺序，按从小到大排序。默认为 0
### 事件
名称 描述
change

值变化时触发
show

开始显示时，事件被触发。可以通过调用 event.preventDefault() 阻止显示
shown

显示动画完成时，事件被触发
hide

开始隐藏时，事件被触发。可以通过调用 event.preventDefault() 阻止隐藏
hidden

隐藏动画完成时，事件被触发
### Slots
名称 描述
默认

<mdui-navigation-bar-item> 组件
### CSS 自定义属性
名称 描述
--shape-corner

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

组件的 CSS z-index 值
# 侧边抽屉栏组件 NavigationDrawer 侧边抽屉栏用于在页面侧边提供导航功能，使用户能够快速访问不同的页面或内容。 通常，可以在侧边抽屉栏中使用 [``](/zh-cn/docs/2/components/list) 组件来添加导航项。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/navigation-drawer.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { NavigationDrawer } from 'mdui/components/navigation-drawer.js'; ``` 使用示例： ```html 关闭侧边抽屉栏 打开侧边抽屉栏 ``` **注意事项：** 该组件默认使用 `position: fixed` 定位。 当 `modal` 属性为 `false`，且断点大于等于 [`--mdui-breakpoint-md`](/zh-cn/docs/2/styles/design-tokens#breakpoint) 时，会自动在 `body` 上添加 `padding-left` 或 `padding-right` 样式，以避免页面内容被该组件遮挡。 但在以下两种情况下，会默认使用 `position: absolute` 定位： 1. `contained` 属性为 `true` 时。 2. 当组件位于 [``](/zh-cn/docs/2/components/layout) 中时。此时不会添加 `padding-left` 或 `padding-right` 样式。 ## 示例 {#examples} ### 位于指定容器内 {#example-contained} 默认情况下，侧边抽屉栏会相对于当前窗口，在页面左侧或右侧显示。如果你希望把侧边抽屉栏放在指定容器内，可以添加 `contained` 属性，此时侧边抽屉栏会相对于父元素显示（你需要自行在父元素上添加样式 `position: relative; overflow: hidden;`）。 ```html
关闭侧边抽屉栏
打开侧边抽屉栏
``` ### 模态化 {#example-modal} 添加 `modal` 属性可以在打开侧边抽屉栏时显示遮罩层。注意在窗口或父元素宽度小于 [`--mdui-breakpoint-md`](/zh-cn/docs/2/styles/design-tokens#breakpoint) 时，会无视该参数，始终会显示遮罩层。 添加 `close-on-esc` 属性，可以在按下 ESC 键时关闭侧边抽屉栏。 添加 `close-on-overlay-click` 属性，可以在点击遮罩层时关闭侧边抽屉栏。 ```html
关闭侧边抽屉栏
打开侧边抽屉栏
``` ### 位于右侧 {#example-placement} 通过将 `placement` 属性设置为 `right`，可以将侧边抽屉栏显示在页面右侧。 ```html
关闭侧边抽屉栏
打开侧边抽屉栏
``` ## mdui-navigation-drawer API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
open open true boolean false

是否打开抽屉栏
modal modal true boolean false

抽屉栏打开时，是否显示遮罩层

在窄屏设备上（屏幕宽度小于 --mdui-breakpoint-md），会始终显示遮罩层，无视该参数
close-on-esc closeOnEsc true boolean false

在有遮罩层的情况下，按下 ESC 键是否关闭抽屉栏
close-on-overlay-click closeOnOverlayClick true boolean false

点击遮罩层时，是否关闭抽屉栏
placement placement true 'left' | 'right' 'left'

抽屉栏的位置。可选值包括：

  • left：左侧
  • right：右侧
contained contained true boolean false

默认情况下，抽屉栏相对于 body 元素显示。当该参数设置为 true 时，抽屉栏将相对于其父元素显示。

Note：设置该属性时，必须在父元素上手动设置样式 position: relative; overflow: hidden;。
order order true number

该组件在 <mdui-layout> 中的布局顺序，按从小到大排序。默认为 0
### 事件
名称 描述
open

抽屉栏打开之前触发。可以通过调用 event.preventDefault() 阻止抽屉栏打开
opened

抽屉栏打开动画完成之后触发
close

抽屉栏关闭之前触发。可以通过调用 event.preventDefault() 阻止抽屉栏关闭
closed

抽屉栏关闭动画完成之后触发
overlay-click

点击遮罩层时触发
### Slots
名称 描述
默认

抽屉栏中的内容
### CSS Parts
名称 描述
overlay

遮罩层
panel

抽屉栏容器
### CSS 自定义属性
名称 描述
--shape-corner

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

组件的 CSS z-index 值
# 侧边导航栏组件 NavigationRail 侧边导航栏为平板电脑和桌面电脑提供了访问不同主页面的方式。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/navigation-rail.js'; import 'mdui/components/navigation-rail-item.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { NavigationRail } from 'mdui/components/navigation-rail.js'; import type { NavigationRailItem } from 'mdui/components/navigation-rail-item.js'; ``` 使用示例：（示例中的 `style="position: relative"` 是为了演示需要，实际使用时请移除该样式。） ```html Recent Images Library ``` **注意事项：** 该组件默认使用 `position: fixed` 定位，并会自动在 `body` 上添加 `padding-left` 或 `padding-right` 样式，以防止页面内容被该组件遮挡。 但在以下两种情况下，会默认使用 `position: absolute` 定位： 1. `` 组件的 `contained` 属性为 `true` 时。此时会在父元素上添加 `padding-left` 或 `padding-right` 样式。 2. 当位于 [``](/zh-cn/docs/2/components/layout) 组件中时。此时不会添加 `padding-left` 或 `padding-right` 样式。 ## 样式 {#examples} ### 位于指定容器内 {#example-contained} 默认情况下，侧边导航栏会相对于当前窗口，在页面左侧或右侧显示。如果你希望将侧边导航栏放在指定的容器内，可以在 `` 组件上添加 `contained` 属性，此时侧边导航栏会相对于其父元素显示（你需要自行在父元素上添加 `position: relative` 样式）。 ```html
Recent Images Library
页面内容
``` ### 位于右侧 {#example-placement} 在 `` 组件上设置 `placement` 属性为 `right`，可以将侧边导航栏显示在右侧。 ```html
Recent Images Library
页面内容
``` ### 显示分割线 {#example-divider} 在 `` 组件上添加 `divider` 属性，可以在侧边导航栏上添加一条分割线，以便和页面内容区分开。 ```html
Recent Images Library
页面内容
``` ### 在顶部/底部添加元素 {#example-top-bottom} 可以在 `` 组件内通过 `top`、`bottom` slot 在顶部和底部添加元素。 ```html
Recent Images Library
页面内容
``` ### 导航项垂直对齐方式 {#example-alignment} 通过设置 `` 组件的 `alignment` 属性，可以修改导航项的垂直对齐方式。 ```html
Recent Images Library
start center end
``` ### 图标 {#example-icon} 在 `` 组件上，可以使用 `icon` 属性设置未激活状态的导航项图标，使用 `active-icon` 属性设置激活状态的导航项图标。也可以用 `icon` 和 `active-icon` slot 设置未激活和激活状态的图标元素。 ```html
Recent Images Library
页面内容
``` ### 仅使用图标 {#example-no-label} `` 组件可以仅使用图标，不添加文本。 ```html
页面内容
``` ### 链接 {#example-link} 在 `` 组件上设置 `href` 属性，可以使导航项变为链接。此时，您还可以使用这些和链接相关的属性：`download`、`target`、`rel`。 ```html
Recent Images Library
页面内容
``` ### 徽标 {#example-badge} 在 `` 组件中，可以通过 `badge` slot 添加徽标。 ```html
Recent 99+ Images Library
页面内容
``` ## mdui-navigation-rail-item API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
icon icon true string

未激活状态下的 Material Icons 图标名。也可以通过 slot="icon" 设置
active-icon activeIcon true string

激活状态下的 Material Icons 图标名。也可以通过 slot="active-icon" 设置
value value true string

导航项的值
href href true string

链接的目标 URL。

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

下载链接的目标。

Note：仅在设置了 href 属性时，此属性才有效。
target target true '_blank' | '_parent' | '_self' | '_top'

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

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

Note：仅在设置了 href 属性时，此属性才有效。
rel rel true '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 属性时可用。
autofocus autofocus true boolean false

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

元素在使用 Tab 键切换焦点时的顺序
### 方法
名称 描述
click(): void

模拟鼠标点击元素
focus(options?: FocusOptions): void

将焦点设置到当前元素。

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

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

移除当前元素的焦点
### 事件
名称 描述
focus

获得焦点时触发
blur

失去焦点时触发
### Slots
名称 描述
默认

文本内容
icon

图标
active-icon

激活状态的图标
badge

徽标
### CSS Parts
名称 描述
container

导航项容器
indicator

指示器
badge

徽标
icon

图标
active-icon

激活状态的图标
label

文本内容
### CSS 自定义属性
名称 描述
--shape-corner-indicator

指示器的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
## mdui-navigation-rail API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
value value true string

当前选中的 <mdui-navigation-rail-item> 的值
placement placement true 'left' | 'right' 'left'

导航栏的位置。可选值包括：

  • left：左侧
  • right：右侧
alignment alignment true 'start' | 'center' | 'end' 'start'

<mdui-navigation-rail-item> 元素的对齐方式。可选值包括：

  • start：顶部对齐
  • center：居中对齐
  • end：底部对齐
contained contained true boolean false

默认情况下，导航栏相对于 body 元素显示。当该参数设置为 true 时，导航栏将相对于其父元素显示。

Note：设置该属性时，必须在父元素上手动设置样式 position: relative;。
divider divider true boolean false

是否在导航栏和页面内容之间添加分割线
order order true number

该组件在 <mdui-layout> 中的布局顺序，按从小到大排序。默认为 0
### 事件
名称 描述
change

值变化时触发
### Slots
名称 描述
默认

<mdui-navigation-rail-item> 组件
top

顶部的元素
bottom

底部的元素
### CSS Parts
名称 描述
top

顶部元素的容器
bottom

底部元素的容器
items

<mdui-navigation-rail-item> 组件的容器
### CSS 自定义属性
名称 描述
--shape-corner

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

组件的 CSS z-index 值
# 单选框组件 Radio 单选框用于让用户在一组选项中选择其中一个，确保每次只能选中一个选项。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/radio-group.js'; import 'mdui/components/radio.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { RadioGroup } from 'mdui/components/radio-group.js'; import type { Radio } from 'mdui/components/radio.js'; ``` 使用示例： ```html Chinese English ``` ## 示例 {#examples} ### 选中状态 {#example-checked} `` 组件的 `value` 属性值即当前选中的 `` 组件的 `value` 属性值。您也可以通过更新 `` 组件的 `value` 属性值，来切换当前选中的单选框。 ```html Chinese English ``` 可以单独使用 `` 组件，此时可以通过 `checked` 属性来读取和修改选中状态。 ```html Radio ``` ### 禁用状态 {#example-disabled} 通过在 `` 组件上添加 `disabled` 属性，可以禁用整个单选框组。 ```html Chinese English ``` 如果需要禁用特定的单选框，可以在 `` 组件上添加 `disabled` 属性。 ```html Chinese English ``` ### 图标 {#example-icon} 可以通过设置 `unchecked-icon` 和 `checked-icon` 属性，分别定义未选中和选中状态下的单选框的 Material Icons 图标。也可以通过 `unchecked-icon` 和 `checked-icon` slot 来设置。 ```html Chinese English ``` ## mdui-radio-group API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
disabled disabled true boolean false

是否禁用此组件
form form true string

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

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

单选框组的名称，将与表单数据一起提交
value value true string ''

单选框组的名称，将于表单数据一起提交
undefined defaultValue false string ''

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

提交表单时，是否必须选中其中一个单选框
undefined validity false ValidityState

表单验证状态对象，具体参见 ValidityState
undefined validationMessage false string

如果表单验证未通过，此属性将包含提示信息。如果验证通过，此属性将为空字符串
### 方法
名称 描述
checkValidity(): boolean

检查表单字段是否通过验证。如果未通过，返回 false 并触发 invalid 事件；如果通过，返回 true
reportValidity(): boolean

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

如果验证未通过，还会在组件上显示验证失败的提示。
setCustomValidity(message: string): void

设置自定义的错误提示文本。只要这个文本不为空，就表示字段未通过验证
### 事件
名称 描述
change

选中值变化时触发
input

选中值变化时触发
invalid

表单字段验证未通过时触发
### Slots
名称 描述
默认

<mdui-radio> 元素
## mdui-radio API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
value value true string ''

当前单选项的值
disabled disabled true boolean false

是否禁用当前单选项
checked checked true boolean false

当前单选项是否已选中
unchecked-icon uncheckedIcon true string

未选中状态的 Material Icons 图标名。也可以通过 slot="unchecked-icon" 设置
checked-icon checkedIcon true string

选中状态的 Material Icons 图标名。也可以通过 slot="checked-icon" 设置
autofocus autofocus true boolean false

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

元素在使用 Tab 键切换焦点时的顺序
### 方法
名称 描述
click(): void

模拟鼠标点击元素
focus(options?: FocusOptions): void

将焦点设置到当前元素。

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

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

移除当前元素的焦点
### 事件
名称 描述
focus

获得焦点时触发
blur

失去焦点时触发
change

选中该单选项时触发
### Slots
名称 描述
默认

文本内容
unchecked-icon

未选中状态的图标
checked-icon

选中状态的图标
### CSS Parts
名称 描述
control

左侧图标容器
unchecked-icon

未选中状态的图标
checked-icon

选中状态的图标
label

文本内容
# 范围滑块组件 RangeSlider 范围滑块组件用于让用户在一系列值中选择一个范围。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/range-slider.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { RangeSlider } from 'mdui/components/range-slider.js'; ``` 使用示例： ```html ``` ## 示例 {#examples} ### 默认值 {#example-value} 通过 `value` 属性，可以读取或设置范围滑块的当前值。该属性值是一个数组，只能通过 JavaScript 属性进行读取和设置。 ```html ``` ### 禁用状态 {#example-disabled} 添加 `disabled` 属性可以禁用范围滑块。 ```html ``` ### 范围 {#example-min-max} 使用 `min` 和 `max` 属性设置范围滑块的最小值和最大值。 ```html ``` ### 步进间隔 {#example-step} 使用 `step` 属性设置范围滑块的步进间隔。 ```html ``` ### 刻度标记 {#example-tickmarks} 添加 `tickmarks` 属性可以在范围滑块上添加刻度标记。 ```html ``` ### 隐藏文本提示 {#example-nolabel} 添加 `nolabel` 属性可以隐藏范围滑块上的文本提示。 ```html ``` ### 修改文本提示 {#example-labelFormatter} 通过 `labelFormatter` JavaScript 属性，可以修改文本提示的显示格式。该属性值是一个函数，函数参数为当前范围滑块的值，返回值为你期望显示的文本。 ```html ``` ## mdui-range-slider API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
undefined defaultValue false number[] []

默认值。在重置表单时，将重置为该默认值。此属性只能通过 JavaScript 属性设置
undefined value false number[]

滑块的值，为数组格式，将于表单数据一起提交。

NOTE：该属性无法通过 HTML 属性设置初始值，如果要修改该值，只能通过修改 JavaScript 属性值实现。
autofocus autofocus true boolean false

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

元素在使用 Tab 键切换焦点时的顺序
min min true number 0

滑块的最小值，默认为 0
max max true number 100

滑块的最大值，默认为 100
step step true number 1

步进间隔，默认为 1
tickmarks tickmarks true boolean false

是否添加刻度标记
nolabel nolabel true boolean false

是否隐藏文本提示
disabled disabled true boolean false

是否被禁用
form form true string

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

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

滑块的名称，该名称将与表单数据一起提交
undefined validity false ValidityState

表单验证状态对象，具体参见 ValidityState
undefined validationMessage false string

如果表单验证未通过，此属性将包含提示信息。如果验证通过，此属性将为空字符串
undefined labelFormatter false (value: number) => string

用于自定义标签的显示格式的函数。函数参数为滑块的当前值，返回值为期望显示的文本。
### 方法
名称 描述
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

失去焦点时触发
change

值发生变更，且失去焦点时，将触发该事件
input

值变更时触发
invalid

表单字段验证未通过时触发
### CSS Parts
名称 描述
track-inactive

未激活状态的轨道
track-active

已激活状态的轨道
handle

操作杆
label

提示文本
tickmark

刻度标记
# 选择框组件 Select 下拉选择组件在一个下拉菜单中提供多种选项，方便用户快速选择所需内容。 本页面主要介绍 `` 组件的使用方法，关于下拉菜单项的用法，请参见 [``](/zh-cn/docs/2/components/menu#menu-item-api)。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/select.js'; import 'mdui/components/menu-item.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { Select } from 'mdui/components/select.js'; import type { MenuItem } from 'mdui/components/menu-item.js'; ``` 使用示例： ```html Item 1 Item 2 ``` ## 示例 {#examples} ### 形状 {#example-variant} 通过 `variant` 属性设置下拉选择的形状。 ```html Item 1 Item 2 Item 1 Item 2 ``` ### 多选支持 {#example-multiple} 下拉选择默认为单选，`` 组件的 `value` 值即为当前选中的 [``](/zh-cn/docs/2/components/menu#menu-item-api) 的 `value` 值。 添加 `multiple` 属性可以使下拉选择支持多选。此时 `` 的 `value` 值为当前选中的 [``](/zh-cn/docs/2/components/menu#menu-item-api) 的 `value` 的值组成的数组。 注意：在支持多选时，`` 的 `value` 值为数组，只能通过 JavaScript 属性来读取和设置该值。 ```html Item 1 Item 2 Item 3 ``` ### 辅助文本 {#example-helper-text} 使用 `label` 属性设置下拉选择上方的标签文本。 ```html Item 1 Item 2 ``` 使用 `placeholder` 属性设置未选中值时的占位文本。 ```html Item 1 Item 2 ``` 使用 `helper` 属性设置下拉选择底部的帮助文本。也可以使用 `helper` slot 来设置帮助文本。 ```html Item 1 Item 2 Item 1 Item 2 Supporting text ``` ### 只读模式 {#example-readonly} 通过添加 `readonly` 属性，可以将下拉选择设置为只读模式。 ```html Item 1 Item 2 ``` ### 禁用模式 {#example-disabled} 通过添加 `disabled` 属性，可以禁用下拉选择。 ```html Item 1 Item 2 ``` ### 可清空 {#example-clearable} 添加 `clearable` 属性后，当下拉选择有值时，右侧会出现一个清空按钮。 ```html Item 1 Item 2 ``` 也可以通过 `clear` slot 自定义清空按钮。 ```html Item 1 Item 2 ``` ### 下拉菜单位置 {#example-placement} 通过 `placement` 属性，你可以设置下拉菜单的位置。 ```html Item 1 Item 2 ``` ### 文本右对齐 {#example-end-aligned} 添加 `end-aligned` 属性，可以使文本右对齐。 ```html Item 1 Item 2 ``` ### 前后文本及图标 {#example-prefix-suffix} 通过设置 `icon` 和 `end-icon` 属性，可以在下拉选择的左侧和右侧添加 Material Icons 图标。你也可以通过 `icon` 和 `end-icon` slot 在下拉选择的左侧和右侧添加元素。 ```html Item 1 Item 2

Item 1 Item 2 ``` 通过设置 `prefix` 和 `suffix` 属性，可以在下拉选择的左侧和右侧添加文本。也可以通过 `prefix` 和 `suffix` slot 在下拉选择的左侧和右侧添加文本元素。这些文本只有在下拉选择聚焦或有值时才会显示。 ```html Item 1 Item 2

Item 1 Item 2 $ /100 ``` ## mdui-select API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
variant variant true 'filled' | 'outlined' 'filled'

选择框的样式。可选值包括：

  • filled：带背景色的选择框，视觉效果较强
  • outlined：带边框的选择框，视觉效果较弱
multiple multiple true boolean false

是否支持多选
name name true string ''

选择框的名称，将与表单数据一起提交
value value false string | string[] ''

选择框的值，将与表单数据一起提交。

如果未指定 multiple 属性，该值为字符串；如果指定了 multiple 属性，该值为字符串数组。HTML 属性只能设置字符串值；如果需要设置数组值，请通过 JavaScript 属性设置。
undefined defaultValue false string | string[] ''

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

标签文本
placeholder placeholder true string

占位符文本
helper helper true string

选择框底部的帮助文本。也可以通过 slot="helper" 设置
clearable clearable true boolean false

是否可以清空选择框
clear-icon clearIcon true string

当选择框可清空时，显示在选择框右侧的清空按钮的 Material Icons 图标名。也可以通过 slot="clear-icon" 设置
placement placement true 'auto' | 'bottom' | 'top' 'auto'

选择框的位置。可选值包括：

  • auto：自动判断位置
  • bottom：位于下方
  • top：位于上方
end-aligned endAligned true boolean false

文本是否右对齐
prefix prefix true string

选择框的前缀文本。仅在聚焦状态，或选择框有值时才会显示。也可以通过 slot="prefix" 设置
suffix suffix true string

选择框的后缀文本。仅在聚焦状态，或选择框有值时才会显示。也可以通过 slot="suffix" 设置
icon icon true string

选择框的前缀图标的 Material Icons 图标名。也可以通过 slot="icon" 设置
end-icon endIcon true string

选择框的后缀图标的 Material Icons 图标名。也可以通过 slot="end-icon" 设置
error-icon errorIcon true string

表单字段验证失败时，显示在选择框右侧的 Material Icons 图标名。也可以通过 slot="error-icon" 设置
form form true string

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

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

是否为只读状态
disabled disabled true boolean false

是否为禁用状态
required required true boolean false

提交表单时，是否必须填写该字段
undefined validity false ValidityState

表单验证状态对象，具体参见 ValidityState
undefined validationMessage false string

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

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

元素在使用 Tab 键切换焦点时的顺序
### 方法
名称 描述
checkValidity(): boolean

检查表单字段是否通过验证。如果未通过，返回 false 并触发 invalid 事件；如果通过，返回 true
reportValidity(): boolean

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

如果验证未通过，还会在组件上显示验证失败的提示。
setCustomValidity(message: string): void

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

模拟鼠标点击元素
focus(options?: FocusOptions): void

将焦点设置到当前元素。

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

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

移除当前元素的焦点
### 事件
名称 描述
focus

获得焦点时触发
blur

失去焦点时触发
change

选中的值变更时触发
invalid

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

在点击由 clearable 属性生成的清空按钮时触发。可以通过调用 event.preventDefault() 阻止清空选择框
### Slots
名称 描述
默认

<mdui-menu-item> 元素
icon

左侧图标
end-icon

右侧图标
error-icon

验证失败状态的右侧图标
prefix

左侧文本
suffix

右侧文本
clear-button

清空按钮
clear-icon

清空按钮中的图标
helper

底部的帮助文本
### CSS Parts
名称 描述
chips

多选时，放置选中值对应的 chip 的容器
chip

多选时，每一个选中的值对应的 chip
chip__button

chip 内部的 <button> 元素
chip__label

chip 内部的文本
chip__delete-icon

chip 内部的删除图标
text-field

文本框，即 <mdui-text-field> 元素
text-field__container

text-field 内部的文本框容器
text-field__icon

text-field 内部的左侧图标
text-field__end-icon

text-field 内部的右侧图标
text-field__error-icon

text-field 内部的验证失败状态的右侧图标
text-field__prefix

text-field 内部的左侧文本
text-field__suffix

text-field 内部的右侧文本
text-field__label

text-field 内部的标签文本
text-field__input

text-field 内部的 <input> 元素
text-field__clear-button

text-field 内部的清空按钮
text-field__clear-icon

text-field 内部的清空按钮中的图标
text-field__supporting

text-field 内部的底部辅助信息容器，包括 helper 和 error
text-field__helper

text-field 内部的底部帮助文本
text-field__error

text-field 内部的底部错误描述文本
menu

下拉菜单，即 <mdui-menu> 元素
# 分段按钮组件 SegmentedButton 分段按钮组件封装了一组按钮，用于提供选项、切换视图或对元素进行排序等。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/segmented-button-group.js'; import 'mdui/components/segmented-button.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { SegmentedButtonGroup } from 'mdui/components/segmented-button-group.js'; import type { SegmentedButton } from 'mdui/components/segmented-button.js'; ``` 使用示例： ```html Day Week Month ``` ## 示例 {#examples} ### 全宽显示 {#example-full-width} 在 `` 元素上添加 `full-width` 属性，可使组件占据全部宽度。 ```html Day Week Month ``` ### 单选模式 {#example-selects-single} 在 `` 元素上指定 `selects` 属性为 `single`，可以实现单选模式。此时 `` 的 `value` 属性值即为当前选中的 `` 的 `value` 属性的值。 ```html Day Week Month Day Week Month ``` ### 多选模式 {#example-selects-multiple} 在 `` 元素上指定 `selects` 属性为 `multiple`，可以实现多选模式。此时 `` 的 `value` 属性值为当前选中的 `` 的 `value` 属性的值组成的数组。 注意：在多选模式下，`` 的 `value` 属性值为数组，只能通过 JavaScript 属性来读取和设置该值。 ```html Day Week Month Day Week Month ``` ### 图标 {#example-icon} 在 `` 元素上，通过设置 `icon` 和 `end-icon` 属性，可以在按钮的左侧和右侧添加 Material Icons 图标。另外，也可以通过 `icon` 和 `end-icon` slot 在按钮的左侧和右侧添加元素。 ```html Day Week Month ``` 在 `` 元素上，通过添加 `selected-icon` 属性，可以设置选中状态的 Material Icons 图标。也可以通过 `selected-icon` slot 进行设置。 ```html Day Week ``` ### 链接 {#example-link} 在 `` 元素上，通过设置 `href` 属性，可以将按钮转换为链接。此时，还可以使用与链接相关的属性，如：`download`、`target`、`rel`。 ```html Link Week Month ``` ### 禁用及加载中状态 {#example-disabled} 在 `` 元素上，通过添加 `disabled` 属性，可以禁用整个分段按钮组。 ```html Day Week Month ``` 在 `` 元素上，通过添加 `disabled` 属性，可以禁用特定按钮；通过添加 `loading` 属性，可以为特定按钮添加加载中状态。 ```html Day Week Month Year ``` ## mdui-segmented-button-group API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
full-width fullWidth true boolean false

是否填满父元素宽度
selects selects true 'single' | 'multiple'

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

  • single：单选
  • multiple：多选
disabled disabled true boolean false

是否为禁用状态
required required true boolean false

提交表单时，是否必须选中
form form true string

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

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

提交表单时的名称，将与表单数据一起提交
value value false string | string[] ''

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

Note：该属性的 HTML 属性始终为字符串，且仅在 selects="single" 时可以通过 HTML 属性设置初始值。该属性的 JavaScript 属性值在 selects="single" 时为字符串，在 selects="multiple" 时为字符串数组。所以，在 selects="multiple" 时，如果要修改该值，只能通过修改 JavaScript 属性值实现。
undefined defaultValue false string | string[] ''

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

表单验证状态对象，具体参见 ValidityState
undefined validationMessage false string

如果表单验证未通过，此属性将包含提示信息。如果验证通过，此属性将为空字符串
### 方法
名称 描述
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 类型 默认值 描述
icon icon true string

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

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

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

链接的目标 URL。

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

下载链接的目标。

Note：仅在设置了 href 属性时，此属性才有效。
target target true '_blank' | '_parent' | '_self' | '_top'

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

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

Note：仅在设置了 href 属性时，此属性才有效。
rel rel true '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 属性时可用。
autofocus autofocus true boolean false

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

元素在使用 Tab 键切换焦点时的顺序
disabled disabled true boolean false

是否禁用
loading loading true boolean false

是否处于加载中状态
name name true string ''

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

Note：仅在未设置 href 属性时，此属性才有效。
value value true string ''

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

Note：仅在未设置 href 属性时，此属性才有效。
type type true 'submit' | 'reset' | 'button' 'button'

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

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

Note：仅在未指定 href 属性时，此属性才有效。
form form true string

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

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

Note：仅在未指定 href 属性时，此属性才有效。
formaction formAction true string

指定提交表单的 URL。

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

Note：仅在未指定 href 属性且 type="submit" 时，此属性才有效。
formenctype formEnctype true '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" 时，此属性才有效。
formmethod formMethod true 'post' | 'get'

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

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

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

Note：仅在未设置 href 属性且 type="submit" 时，此属性才有效。
formnovalidate formNoValidate true boolean false

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

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

Note：仅在未设置 href 属性且 type="submit" 时，此属性才有效。
formtarget formTarget true '_self' | '_blank' | '_parent' | '_top'

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

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

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

Note：仅在未设置 href 属性且 type="submit" 时，此属性才有效。
undefined validity false ValidityState

表单验证状态对象，具体参见 ValidityState
undefined validationMessage false string

如果表单验证未通过，此属性将包含提示信息。如果验证通过，此属性将为空字符串
### 方法
名称 描述
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> 元素
# 滑块组件 Slider 滑块组件允许用户通过滑动滑块从一系列值中进行选择。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/slider.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { Slider } from 'mdui/components/slider.js'; ``` 使用示例： ```html ``` ## 示例 {#examples} ### 默认值 {#example-value} 通过 `value` 属性，可以读取或设置滑块的当前值。 ```html ``` ### 禁用状态 {#example-disabled} 添加 `disabled` 属性可以禁用滑块。 ```html ``` ### 范围 {#example-min-max} 使用 `min` 和 `max` 属性来设置滑块的最小值和最大值。 ```html ``` ### 步进间隔 {#example-step} 通过 `step` 属性，你可以设置滑块的步进间隔。 ```html ``` ### 刻度标记 {#example-tickmarks} 添加 `tickmarks` 属性，可以在滑块上显示刻度标记。 ```html ``` ### 隐藏文本提示 {#example-nolabel} 如果你想隐藏滑块上的文本提示，可以添加 `nolabel` 属性。 ```html ``` ### 修改文本提示 {#example-labelFormatter} 可以通过 `labelFormatter` JavaScript 属性来修改文本提示的显示格式。这个属性的值应该是一个函数，该函数接收当前滑块的值作为参数，返回你希望显示的文本。 ```html ``` ## mdui-slider API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
value value false number 0

滑块的值，将于表单数据一起提交
undefined defaultValue false number 0

默认值。在重置表单时，将重置为该默认值。该属性只能通过 JavaScript 属性设置
autofocus autofocus true boolean false

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

元素在使用 Tab 键切换焦点时的顺序
min min true number 0

滑块的最小值，默认为 0
max max true number 100

滑块的最大值，默认为 100
step step true number 1

步进间隔，默认为 1
tickmarks tickmarks true boolean false

是否添加刻度标记
nolabel nolabel true boolean false

是否隐藏文本提示
disabled disabled true boolean false

是否被禁用
form form true string

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

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

滑块的名称，该名称将与表单数据一起提交
undefined validity false ValidityState

表单验证状态对象，具体参见 ValidityState
undefined validationMessage false string

如果表单验证未通过，此属性将包含提示信息。如果验证通过，此属性将为空字符串
undefined labelFormatter false (value: number) => string

用于自定义标签的显示格式的函数。函数参数为滑块的当前值，返回值为期望显示的文本。
### 方法
名称 描述
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

失去焦点时触发
change

在值发生变更，且失去焦点时，将触发该事件
input

值变更时触发
invalid

表单字段验证未通过时触发
### CSS Parts
名称 描述
track-inactive

未激活状态的轨道
track-active

已激活状态的轨道
handle

操作杆
label

提示文本
tickmark

刻度标记
# 消息条组件 Snackbar 消息条组件用于在页面中展示简短的应用程序进程信息。 除了直接使用该组件外，mdui 还提供了一个 [`mdui.snackbar`](/zh-cn/docs/2/functions/snackbar) 函数，以简化 Snackbar 组件的使用。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/snackbar.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { Snackbar } from 'mdui/components/snackbar.js'; ``` 使用示例： ```html Photo archived 打开 Snackbar ``` ## 示例 {#examples} ### 位置 {#example-placement} 通过 `placement` 属性，你可以设置 Snackbar 的显示位置。 ```html
Photo archived top-start Photo archived top Photo archived top-end
Photo archived bottom-start Photo archived bottom Photo archived bottom-end
``` ### 操作按钮 {#example-action} 可以使用 `action` 属性在 Snackbar 的右侧添加一个操作按钮，并通过该属性指定按钮的文本。点击操作按钮会触发 `action-click` 事件。如果你想让操作按钮显示为加载中状态，可以添加 `action-loading` 属性。 ```html Photo archived 打开 Snackbar ``` 也可以通过 `action` slot 在 Snackbar 的右侧添加自定义元素。 ```html Photo archived Undo 打开 Snackbar ``` ### 可关闭 {#example-closeable} 添加 `closeable` 属性后，Snackbar 的右侧会出现一个关闭按钮。点击该按钮会关闭 Snackbar，并触发 `close` 事件。 ```html Photo archived 打开 Snackbar ``` 可以通过 `close-button` slot 来自定义关闭按钮的元素。 ```html Photo archived 打开 Snackbar ``` 通过设置 `close-icon` 属性，你可以修改默认关闭按钮中的 Material Icons 图标。也可以通过 `close-icon` slot 来自定义关闭按钮中的图标元素。 ```html Photo archived 打开 Snackbar ``` ### 文本行数 {#example-message-line} 默认情况下，消息文本没有行数限制。你可以通过 `message-line` 属性来限制文本行数，最多可以设置为 2 行。 ```html The item already has the label "travel". You can add a new label. You can add a new label. 打开 Snackbar ``` ### 自动关闭延时 {#example-auto-close-delay} 可以使用 `auto-close-delay` 属性来设置自动关闭的延时，单位为毫秒。默认值为 5000 毫秒。 ```html Photo archived 打开 Snackbar ``` ### 点击外部区域关闭 {#example-close-on-outside-click} 通过添加 `close-on-outside-click` 属性，你可以设置在点击 Snackbar 外部区域时关闭 Snackbar。 ```html Photo archived 打开 Snackbar ``` ## mdui-snackbar API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
open open true boolean false

是否显示 Snackbar
placement placement true 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' 'bottom'

Snackbar 的显示位置。默认为 bottom。可选值包括：

  • top：顶部居中
  • top-start：顶部左对齐
  • top-end：顶部右对齐
  • bottom：底部居中
  • bottom-start：底部左对齐
  • bottom-end：底部右对齐
action action true string

操作按钮的文本。也可以通过 slot="action" 设置操作按钮
action-loading actionLoading true boolean false

操作按钮是否处于加载中状态
closeable closeable true boolean false

是否在右侧显示关闭按钮
close-icon closeIcon true string

关闭按钮的 Material Icons 图标名。也可以通过 slot="close-icon" 设置
message-line messageLine true 1 | 2

消息文本的最大显示行数。默认不限制。可选值包括：

  • 1：最多显示一行
  • 2：最多显示两行
auto-close-delay autoCloseDelay true number 5000

自动关闭的延迟时间（单位：毫秒）。设置为 0 则不自动关闭。默认为 5000 毫秒
close-on-outside-click closeOnOutsideClick true boolean false

点击或触摸 Snackbar 以外的区域时，是否关闭 Snackbar
### 事件
名称 描述
open

Snackbar 开始显示时，事件被触发。可以通过调用 event.preventDefault() 阻止 Snackbar 显示
opened

Snackbar 显示动画完成时，事件被触发
close

Snackbar 开始隐藏时，事件被触发。可以通过调用 event.preventDefault() 阻止 Snackbar 关闭
closed

Snackbar 隐藏动画完成时，事件被触发
action-click

点击操作按钮时触发
### Slots
名称 描述
默认

Snackbar 的消息文本内容
action

右侧的操作按钮
close-button

右侧的关闭按钮。必须设置 closeable 属性为 true 才会显示
close-icon

关闭按钮中的图标
### CSS Parts
名称 描述
message

消息文本
action

操作按钮
close-button

关闭按钮
close-icon

关闭按钮中的图标
### CSS 自定义属性
名称 描述
--shape-corner

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

组件的 CSS z-index 值
# 开关切换组件 Switch 开关组件用于切换单个选项的开启或关闭状态，通过直观的交互设计，让用户能轻松调整设置。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/switch.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { Switch } from 'mdui/components/switch.js'; ``` 使用示例： ```html ``` ## 示例 {#examples} ### 选中状态 {#example-checked} 当开关被选中时，`checked` 属性的值为 `true`。你也可以通过添加 `checked` 属性，使开关默认处于选中状态。 ```html ``` ### 禁用状态 {#example-disabled} 通过添加 `disabled` 属性，可以禁用开关组件。 ```html ``` ### 图标 {#example-icon} 可以通过 `unchecked-icon` 属性来设置未选中状态的 Material Icons 图标，通过 `checked-icon` 属性来设置选中状态的 Material Icons 图标。也可以通过 `unchecked-icon` 和 `checked-icon` slot 来自定义未选中和选中状态的图标元素。 ```html ``` ## mdui-switch API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
disabled disabled true boolean false

是否为禁用状态
checked checked true boolean false

是否为选中状态
undefined defaultChecked false boolean false

默认选中状态。在重置表单时，将重置为此状态。此属性只能通过 JavaScript 属性设置
unchecked-icon uncheckedIcon true string

未选中状态的 Material Icons 图标名。也可以通过 slot="unchecked-icon" 设置
checked-icon checkedIcon true string

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

默认为 check 图标，可传入空字符串移除默认图标
required required true boolean false

提交表单时，是否必须选中此开关
form form true string

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

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

开关的名称，将与表单数据一起提交
value value true string 'on'

开关的值，将于表单数据一起提交
undefined validity false ValidityState

表单验证状态对象，具体参见 ValidityState
undefined validationMessage false string

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

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

元素在使用 Tab 键切换焦点时的顺序
### 方法
名称 描述
checkValidity(): boolean

检查表单字段是否通过验证。如果未通过，返回 false 并触发 invalid 事件；如果通过，返回 true
reportValidity(): boolean

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

如果验证未通过，还会在组件上显示验证失败的提示。
setCustomValidity(message: string): void

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

模拟鼠标点击元素
focus(options?: FocusOptions): void

将焦点设置到当前元素。

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

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

移除当前元素的焦点
### 事件
名称 描述
focus

获得焦点时触发
blur

失去焦点时触发
change

选中状态变更时触发
input

选中状态变更时触发
invalid

表单字段验证不通过时触发
### Slots
名称 描述
unchecked-icon

未选中状态的元素
checked-icon

选中状态的元素
### CSS Parts
名称 描述
track

轨道
thumb

图标容器
unchecked-icon

未选中状态的图标
checked-icon

选中状态的图标
### CSS 自定义属性
名称 描述
--shape-corner

组件轨道的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
--shape-corner-thumb

组件图标容器的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
# 选项卡组件 Tabs 选项卡组件用于将内容或数据集分组并展示，方便用户在不同类别之间快速切换。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/tabs.js'; import 'mdui/components/tab.js'; import 'mdui/components/tab-panel.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { Tabs } from 'mdui/components/tabs.js'; import type { Tab } from 'mdui/components/tab.js'; import type { TabPanel } from 'mdui/components/tab-panel.js'; ``` 使用示例： ```html Tab 1 Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 ``` ## 示例 {#examples} ### 选项卡样式 {#example-variant} 通过在 `` 组件上使用 `variant` 属性，可以设置选项卡的样式。 ```html Tab 1 Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 Tab 1 Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 ``` ### 选项卡位置 {#example-placement} 在 `` 组件上使用 `placement` 属性，可以设置选项卡的位置。 ```html top-start top top-end bottom-start bottom bottom-end left-start left left-end right-start right right-end Tab 1 Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 ``` ### 全宽显示 {#example-full-width} 在 `` 组件上添加 `full-width` 属性，可以使选项卡占据全部宽度，各个选项卡将平均分配宽度。 ```html Tab 1 Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 ``` ### 图标 {#example-icon} 在 `` 组件上设置 `icon` 属性，可以在选项卡上添加 Material Icons 图标。也可以通过 `icon` slot 添加图标元素。 添加 `inline` 属性可以将图标和文本水平排列。 ```html Tab 1 Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 ``` ### 徽标 {#example-badge} 在 `` 组件中，可以通过 `badge` slot 添加徽标。 ```html Tab 1 99+ Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 ``` ### 自定义内容 {#example-custom} 在 `` 组件中使用 `custom` slot，可以完全自定义选项卡的内容。 ```html Tab 1 Icon Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 ``` ## mdui-tab-panel API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
value value true string

选项卡面板项的值
### Slots
名称 描述
默认

选项卡面板项内容
## mdui-tab API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
value value true string

选项卡导航项的值
icon icon true string

Material Icons 图标名。也可以通过 slot="icon" 设置
inline inline true boolean false

是否把图标和文本水平排列
autofocus autofocus true boolean false

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

元素在使用 Tab 键切换焦点时的顺序
### 方法
名称 描述
click(): void

模拟鼠标点击元素
focus(options?: FocusOptions): void

将焦点设置到当前元素。

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

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

移除当前元素的焦点
### 事件
名称 描述
focus

获得焦点时触发
blur

失去焦点时触发
### Slots
名称 描述
默认

选项卡导航项的文本内容
icon

选项卡导航项中的图标
badge

徽标
custom

自定义整个选项卡导航项中的内容
### CSS Parts
名称 描述
container

选项卡导航项容器
icon

选项卡导航项中的图标
label

选项卡导航项的文本
## mdui-tabs API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
variant variant true 'primary' | 'secondary' 'primary'

选项卡形状。可选值包括：

  • primary：适用于位于 <mdui-top-app-bar> 下方，用于切换应用的主页面的场景
  • secondary：适用于位于页面中，用于切换一组相关内容的场景
value value true string

当前激活的 <mdui-tab> 的值
placement placement true 'top-start' | 'top' | 'top-end' | 'bottom-start' | 'bottom' | 'bottom-end' | 'left-start' | 'left' | 'left-end' | 'right-start' | 'right' | 'right-end' 'top-start'

选项卡位置。默认为 top-start。可选值包括：

  • top-start：位于上方，左对齐
  • top：位于上方，居中对齐
  • top-end：位于上方，右对齐
  • bottom-start：位于下方，左对齐
  • bottom：位于下方，居中对齐
  • bottom-end：位于下方，右对齐
  • left-start：位于左侧，顶部对齐
  • left：位于左侧，居中对齐
  • left-end：位于左侧，底部对齐
  • right-start：位于右侧，顶部对齐
  • right：位于右侧，居中对齐
  • right-end：位于右侧，底部对齐
full-width fullWidth true boolean false

是否填满父元素宽度
### 事件
名称 描述
change

选中的值变化时触发
### Slots
名称 描述
默认

<mdui-tab> 元素
panel

<mdui-tab-panel> 元素
### CSS Parts
名称 描述
container

<mdui-tab> 元素的容器
indicator

激活状态指示器
# 文本框组件 TextField 文本框组件允许用户在页面中输入文本，通常用于表单和对话框。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/text-field.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { TextField } from 'mdui/components/text-field.js'; ``` 使用示例： ```html ``` ## 示例 {#examples} ### 形状 {#example-variant} 通过 `variant` 属性设置文本框的形状。 ```html

``` ### 辅助文本 {#example-helper-text} 通过 `label` 属性设置文本框上方的标签文本。 ```html ``` 通过 `placeholder` 属性设置无值时的占位文本。 ```html ``` 通过 `helper` 属性设置文本框底部的帮助文本。也可以使用 `helper` slot 来设置帮助文本。添加 `helper-on-focus` 属性则仅在输入框聚焦时显示帮助文本。 ```html Supporting text ``` ### 可清空 {#example-clearable} 添加 `clearable` 属性后，当文本框有值时，会在右侧添加清空按钮。 ```html ``` ### 文本右对齐 {#example-end-aligned} 添加 `end-aligned` 属性可以使文本右对齐。 ```html ``` ### 前后文本及图标 {#example-prefix-suffix} 通过设置 `icon` 和 `end-icon` 属性，可以在文本框的左侧和右侧添加 Material Icons 图标。也可以通过 `icon` 和 `end-icon` slot 在文本框的左侧和右侧添加元素。 ```html

``` 通过设置 `prefix` 和 `suffix` 属性，可以在文本框的左侧和右侧添加文本。也可以通过 `prefix` 和 `suffix` slot 在文本框的左侧和右侧添加文本元素。这些文本只有在文本框聚焦或有值时才会显示。 ```html

$ /100 ``` ### 只读模式 {#example-readonly} 通过添加 `readonly` 属性，可以将文本框设置为只读模式。 ```html ``` ### 禁用状态 {#example-disabled} 通过添加 `disabled` 属性，可以禁用文本框。 ```html ``` ### 多行文本框 {#example-rows} 通过 `rows` 属性，可以设置多行文本框的行数。 ```html ``` 也可以添加 `autosize` 属性，使文本框能根据输入内容的长度自动调整高度。通过 `min-rows` 和 `max-rows` 属性，可以指定自动调整高度时的最小行数和最大行数。 ```html

``` ### 字数统计 {#example-counter} 当通过 `maxlength` 属性设置了最大字数时，可以添加 `counter` 属性在文本框下方显示字数统计。 ```html ``` ### 密码框 {#example-password} 当 `type="password"` 时，添加 `toggle-password` 属性可以在文本框右侧添加切换密码可见性的按钮。 ```html ``` ## mdui-text-field API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
variant variant true 'filled' | 'outlined' 'filled'

文本框的形状。默认为 filled。可选值包括：

  • filled：带背景色的文本框，视觉效果较强
  • outlined：带边框的文本框，视觉效果较弱
type type true 'text' | 'number' | 'password' | 'url' | 'email' | 'search' | 'tel' | 'hidden' | 'date' | 'datetime-local' | 'month' | 'time' | 'week' 'text'

文本框输入类型。默认为 text。可选值包括：

  • text：默认值。文本字段
  • number：只能输入数字。拥有动态键盘的设备上会显示数字键盘
  • password：用于输入密码，其值会被遮盖
  • url：用于输入 URL，会验证 URL 格式。在支持动态键盘的设备上有相应的键盘
  • email：用于输入邮箱地址，会验证邮箱格式。在支持动态键盘的设备上有相应的键盘
  • search：用于搜索框。拥有动态键盘的设备上的回车图标会变成搜索图标
  • tel：用于输入电话号码。拥有动态键盘的设备上会显示电话数字键盘
  • hidden：隐藏该控件，但其值仍会提交到服务器
  • date：输入日期的控件（年、月、日，不包括时间）。在支持的浏览器激活时打开日期选择器或年月日的数字滚轮
  • datetime-local：输入日期和时间的控件，不包括时区。在支持的浏览器激活时打开日期选择器或年月日的数字滚轮
  • month：输入年和月的控件，没有时区
  • time：用于输入时间的控件，不包括时区
  • week：用于输入以年和周数组成的日期，不带时区
name name true string ''

文本框名称，将与表单数据一起提交
value value false string ''

文本框的值，将与表单数据一起提交
undefined defaultValue false string ''

默认值。在重置表单时，将重置为该默认值。该属性只能通过 JavaScript 属性设置
label label true string

标签文本
placeholder placeholder true string

占位符文本
helper helper true string

文本框底部的帮助文本。也可以通过 slot="helper" 设置
helper-on-focus helperOnFocus true boolean false

是否仅在获得焦点时，显示底部的帮助文本
clearable clearable true boolean false

是否可清空文本框内容
clear-icon clearIcon true string

可清空文本框时，显示在文本框右侧的清空按钮的 Material Icons 图标名。也可以通过 slot="clear-icon" 设置
end-aligned endAligned true boolean false

是否将文本右对齐
prefix prefix true string

文本框的前缀文本。只在文本框聚焦或有值时显示。也可以通过 slot="prefix" 设置
suffix suffix true string

文本框的后缀文本。只在文本框聚焦或有值时显示。也可以通过 slot="suffix" 设置
icon icon true string

文本框的前缀图标的 Material Icons 图标名。也可以通过 slot="icon" 设置
end-icon endIcon true string

文本框的后缀图标的 Material Icons 图标名。也可以通过 slot="end-icon" 设置
error-icon errorIcon true string

表单字段验证失败时，显示在文本框右侧的 Material Icons 图标名。也可以通过 slot="error-icon" 设置
form form true string

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

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

是否为只读模式
disabled disabled true boolean false

是否禁用输入框
required required true boolean false

提交表单时，是否必须填写该字段
rows rows true number

文本框的固定显示行数
autosize autosize true boolean false

是否根据输入内容自动调整文本框高度
min-rows minRows true number

autosize 为 true 时，文本框的最小行数
max-rows maxRows true number

autosize 为 true 时，文本框的最大行数
minlength minlength true number

允许输入的最小字符数
maxlength maxlength true number

允许输入的最大字符数
counter counter true boolean false

是否显示字数统计，只在 maxlength 被指定时有效
min min true number

当 type 为 number 时，允许输入的最小数值
max max true number

当 type 为 number 时，允许输入的最大数值
step step true number

type 为 number 时，数值增减的步长
pattern pattern true string

用于表单验证的正则表达式
toggle-password togglePassword true boolean false

type 为 password 时，设置此属性会添加一个切换按钮，用于在明文和密文之间切换
show-password-icon showPasswordIcon true string

密码切换按钮的 Material Icons 图标，当密码为明文时显示。也可以通过 slot="show-password-icon" 设置
hide-password-icon hidePasswordIcon true string

密码切换按钮的 Material Icons 图标，当密码为密文时显示。也可以通过 slot="hide-password-icon" 设置
autocapitalize autocapitalize true 'none' | 'sentences' | 'words' | 'characters'

iOS 的非标准属性，用于控制文本首字母是否自动大写。在 iOS5 及以后的版本上有效。可选值包括：

  • none：禁用首字母大写
  • sentences：句子首字母大写
  • words：单词首字母大写
  • characters：所有字母大写
autocorrect autocorrect true string

input 元素的 autocorrect 属性
autocomplete autocomplete true string

input 元素的 autocomplete 属性
enterkeyhint enterkeyhint true 'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send'

input 元素的 enterkeyhint 属性，用于定制虚拟键盘上的 Enter 键的显示文本或图标。具体显示效果取决于用户使用的设备和语言。可选值包括：

  • enter：插入新行
  • done：完成输入，关闭虚拟键盘
  • go：导航到输入文本的目标
  • next：移动到下一个输入项
  • previous：移动到上一个输入项
  • search：导航到搜索结果
  • send：发送文本信息
spellcheck spellcheck true boolean false

是否启用拼写检查
inputmode inputmode true 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url'

input 元素的 inputmode 属性，用于定制虚拟键盘的类型。可选值包括：

  • none：无虚拟键盘。在需要实现自己的键盘输入控件时很有用
  • text：标准文本输入键盘
  • decimal：小数输入键盘，除了数字之外可能会有小数点 . 或者千分符逗号 ,
  • numeric：显示 0-9 的数字键盘
  • tel：手机数字键盘，包含 0-9 数字、星号 * 或者井号 # 键
  • search：为搜索输入优化的虚拟键盘，提交按钮通常会显示 search 或者 “搜索”
  • email：为邮件地址输入优化的虚拟键盘，通常会有 @ . 等键
  • url：为 URL 输入优化的虚拟键盘，通常会有 . / # 等键
undefined validity false ValidityState

表单验证状态对象，具体参见 ValidityState
undefined validationMessage false string

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

获取当前值，并转换为 number 类型；或设置一个 number 类型的值。 如果值无法被转换为 number 类型，则会返回 NaN。
autofocus autofocus true boolean false

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

元素在使用 Tab 键切换焦点时的顺序
### 方法
名称 描述
select(): void

选中文本框中的文本
setSelectionRange(start: number, end: number, direction: 'forward' | 'backward' | 'none'): void

选中文本框中特定范围的内容
setRangeText(replacement: string, start: number, end: number, selectMode: 'select' | 'start' | 'end' | 'preserve'): void

将文本框中特定范围的文本替换为新的文本
checkValidity(): boolean

检查表单字段是否通过验证。如果未通过，返回 false 并触发 invalid 事件；如果通过，返回 true
reportValidity(): boolean

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

如果验证未通过，还会在组件上显示验证失败的提示。
setCustomValidity(message: string): void

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

模拟鼠标点击元素
focus(options?: FocusOptions): void

将焦点设置到当前元素。

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

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

移除当前元素的焦点
### 事件
名称 描述
focus

获得焦点时触发
blur

失去焦点时触发
change

在文本框的值变更，且失去焦点时触发
input

在文本框的值变更时触发
invalid

表单字段验证不通过时触发
clear

在点击由 clearable 属性生成的清空按钮时触发。可以通过调用 event.preventDefault() 阻止清空文本框
### Slots
名称 描述
icon

左侧图标
end-icon

右侧图标
error-icon

验证失败状态的右侧图标
prefix

左侧文本
suffix

右侧文本
clear-button

清空按钮
clear-icon

清空按钮中的图标
toggle-password-button

密码显示状态切换按钮
show-password-icon

显示密码状态下，密码显示状态切换按钮中的图标
hide-password-icon

隐藏密码状态下，密码显示状态切换按钮中的图标
helper

底部的帮助文本
### CSS Parts
名称 描述
container

文本框容器
icon

左侧图标
end-icon

右侧图标
error-icon

验证失败状态的右侧图标
prefix

左侧文本
suffix

右侧文本
label

上方的标签文本
input

内部的 <input> 或 <textarea> 元素
clear-button

清空按钮
clear-icon

清空按钮中的图标
toggle-password-button

密码显示状态切换按钮
show-password-icon

显示密码状态下，密码显示状态切换按钮中的图标
hide-password-icon

隐藏密码状态下，密码显示状态切换按钮中的图标
supporting

底部辅助信息容器，包括 helper、error、counter
helper

底部的帮助文本
error

底部的错误描述文本
counter

底部右侧的字数统计
# 工具提示组件 Tooltip 工具提示用于对特定元素提供补充文本提示或上下文信息，以便用户更好地理解该元素的功能或用途。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/tooltip.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { Tooltip } from 'mdui/components/tooltip.js'; ``` 使用示例： ```html button ``` ## 示例 {#examples} ### 纯文本 tooltip {#example-plain} 默认为纯文本 tooltip。可以通过 `content` 属性设置 tooltip 的内容。 ```html button ``` 也可以通过 `content` slot 设置 tooltip 的内容。 ```html button
title
content
 ``` ### 富文本 tooltip {#example-rich} 设置 `variant` 属性为 `rich` 可以创建富文本 tooltip。可以通过 `headline` 属性设置 tooltip 的标题，`content` 属性设置 tooltip 的内容。 ```html button ``` 也可以通过 `headline`、`content` slot 设置 tooltip 的标题和内容。通过 `action` slot 设置 tooltip 的操作按钮。 ```html button
Rich tooltip
Rich tooltips bring attention to a particular element of feature that warrants the user's focus. It supports multiple lines of informational text.
Action ``` ### 位置 {#example-placement} 通过 `placement` 属性可以设置 tooltip 的位置。 ```html
``` ### 触发方式 {#example-trigger} 通过 `trigger` 属性，可以设置 tooltip 的触发方式。 ```html button ``` ### 打开/关闭延时 {#example-delay} 当触发方式为 `hover` 时，可以通过 `open-delay` 和 `close-delay` 属性分别设置打开和关闭 tooltip 的延时，单位为毫秒。 ```html button ``` ### 禁用状态 {#example-disabled} 通过添加 `disabled` 属性，可以禁用 tooltip。 ```html button ``` ## mdui-tooltip API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
variant variant true 'plain' | 'rich' 'plain'

tooltip 的形状。默认为 plain。可选值包括：

  • plain：纯文本，适用于简单的单行文本
  • rich：富文本，可以包含标题、正文和操作按钮
placement placement true 'auto' | 'top-left' | 'top-start' | 'top' | 'top-end' | 'top-right' | 'bottom-left' | 'bottom-start' | 'bottom' | 'bottom-end' | 'bottom-right' | 'left-start' | 'left' | 'left-end' | 'right-start' | 'right' | 'right-end' 'auto'

tooltip 的位置。默认为 auto。可选值包括：

  • auto：自动判断位置。variant="plain" 时，优先使用 top；variant="rich" 时，优先使用 bottom-right
  • top-left：位于左上方
  • top-start：位于上方，左对齐
  • top：位于上方，居中对齐
  • top-end：位于上方，右对齐
  • top-right：位于右上方
  • bottom-left：位于左下方
  • bottom-start：位于下方，左对齐
  • bottom：位于下方，居中对齐
  • bottom-end：位于下方，右对齐
  • bottom-right：位于右下方
  • left-start：位于左侧，顶部对齐
  • left：位于左侧，居中对齐
  • left-end：位于左侧，底部对齐
  • right-start：位于右侧，顶部对齐
  • right：位于右侧，居中对齐
  • right-end：位于右侧，底部对齐
open-delay openDelay true number 150

鼠标悬浮触发显示的延时，单位为毫秒
close-delay closeDelay true number 150

鼠标悬浮触发隐藏的延时，单位为毫秒
headline headline true string

tooltip 的标题。仅 variant="rich" 时可使用。也可以通过 slot="headline" 设置
content content true string

tooltip 的内容。也可以通过 slot="content" 设置
trigger trigger true 'click' | 'hover' | 'focus' | 'manual' | string 'hover focus'

触发方式，支持多个值，用空格分隔。可选值包括：

  • click：点击时触发
  • hover：鼠标悬浮时触发
  • focus：聚焦时触发
  • manual：只能通过编程方式打开和关闭 tooltip，不能再指定其他触发方式
disabled disabled true boolean false

是否禁用 tooltip
open open true boolean false

是否显示 tooltip
### 事件
名称 描述
open

tooltip 开始显示时，事件被触发。可以通过调用 event.preventDefault() 阻止 tooltip 打开
opened

tooltip 显示动画完成时，事件被触发
close

tooltip 开始隐藏时，事件被触发。可以通过调用 event.preventDefault() 阻止 tooltip 关闭
closed

tooltip 隐藏动画完成时，事件被触发
### Slots
名称 描述
默认

tooltip 触发的目标元素，只有 default slot 中的第一个元素会作为目标元素
headline

tooltip 的标题，只有当 variant="rich" 时，此 slot 才有效
content

tooltip 的内容，可以包含 HTML。若只包含纯文本，可以使用 content 属性代替
action

tooltip 底部的按钮，只有当 variant="rich" 时，此 slot 才有效
### CSS Parts
名称 描述
popup

tooltip 的容器
headline

标题
content

正文
action

操作按钮
### CSS 自定义属性
名称 描述
--shape-corner-plain

当 variant="plain" 时，组件的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
--shape-corner-rich

当 variant="rich" 时，组件的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
--z-index

组件的 CSS z-index 值
# 顶部应用栏组件 TopAppBar 顶部应用栏用于在页面顶部展示关键信息和相关操作，为用户提供清晰的导航和方便的功能访问。 ## 使用方法 {#usage} 按需导入组件： ```js import 'mdui/components/top-app-bar.js'; import 'mdui/components/top-app-bar-title.js'; ``` 按需导入组件的 TypeScript 类型： ```ts import type { TopAppBar } from 'mdui/components/top-app-bar.js'; import type { TopAppBarTitle } from 'mdui/components/top-app-bar-title.js'; ``` 使用示例：（示例中的 `style="position: relative"` 仅用于演示，实际使用时请移除该样式。） ```html Title
``` **注意事项：** 该组件默认使用 `position: fixed` 定位，并会自动在 `body` 上添加 `padding-top` 样式，以防止页面内容被该组件遮挡。 但在以下两种情况下，会默认使用 `position: absolute` 定位： 1. 当指定了 `scroll-target` 属性时。此时会在 `scroll-target` 的元素上添加 `padding-top` 样式。 2. 当位于 [``](/zh-cn/docs/2/components/layout) 组件中时。此时不会添加 `padding-top` 样式。 ## 示例 {#examples} ### 位于指定容器内 {#example-scroll-target} 默认情况下，顶部应用栏会相对于当前窗口，在页面顶部显示。 如果你希望将顶部应用栏放在指定的容器内，可以在 `` 组件上指定 `scroll-target` 属性，其值为可滚动内容的容器的 CSS 选择器或 DOM 元素。此时，顶部应用栏会相对于父元素显示（你需要自行在父元素上添加样式 `position: relative; overflow: hidden`）。 ```html
Title
``` ### 形状 {#example-variant} 可以通过在 `` 组件上使用 `variant` 属性来设置顶部应用栏的形状。 ```html
Title
center-aligned small medium large
``` ### 页面滚动时的行为 {#example-scroll-behavior} 通过在 `` 组件上设置 `scroll-behavior` 属性，可以定义页面滚动时顶部应用栏的行为。可以同时设置多个行为，用空格分隔即可。 滚动行为包括： * `hide`：页面向下滚动时隐藏顶部应用栏，向上滚动时显示顶部应用栏。 * `shrink`：仅在 `variant` 属性为 `medium` 或 `large` 时有效。页面向下滚动时展开顶部应用栏，向上滚动时收缩顶部应用栏。 * `elevate`：页面向下滚动时，在顶部应用栏上添加阴影；页面滚回到顶部时，取消阴影。 使用 `scroll-threshold` 属性，可以设置滚动多少像素后开始触发顶部应用栏的滚动行为。（注意，为了响应及时，在使用了 `elevate` 滚动行为时，请不要再设置 `scroll-threshold` 属性。） **示例：滚动时隐藏** ```html
Title
``` **示例：滚动时添加阴影** ```html
Title
``` **示例：滚动时收缩** ```html
Title
``` **示例：滚动时收缩及添加阴影** ```html
Title
``` ### 展开状态的文本 {#label-large} 对于 `variant` 属性为 `medium` 或 `large`，且 `scroll-behavior` 属性为 `shrink` 的顶部应用栏，你可以在 `` 组件中添加 `label-large` slot，以设置展开状态下的文本。 ```html
这是收起状态的标题 这是展开状态的标题
``` ## mdui-top-app-bar-title API ### Slots
名称 描述
默认

顶部应用栏的标题文本
label-large

展开状态下的标题文本
### CSS Parts
名称 描述
label

标题文本
label-large

展开状态下的标题文本
## mdui-top-app-bar API ### 属性
HTML 属性 JavaScript 属性 Reflect 类型 默认值 描述
variant variant true 'center-aligned' | 'small' | 'medium' | 'large' 'small'

顶部应用栏的形状。默认为 small。可选值包括：

  • center-aligned：小型应用栏，标题居中
  • small：小型应用栏
  • medium：中型应用栏
  • large：大型应用栏
hide hide true boolean false

是否隐藏
shrink shrink true boolean false

是否缩小为 variant="small" 的样式，仅在 variant="medium" 或 variant="large" 时生效
scroll-behavior scrollBehavior true 'hide' | 'shrink' | 'elevate'

滚动行为。可同时使用多个值，用空格分隔。可选值包括：

  • hide：滚动时隐藏
  • shrink：在中型、大型应用栏中可使用，滚动时缩小成小型应用栏的样式
  • elevate：滚动时添加阴影
scroll-target scrollTarget false string | HTMLElement | JQ<HTMLElement>

需要监听其滚动事件的元素。值可以是 CSS 选择器、DOM 元素、或 JQ 对象。默认监听 window 的滚动事件
scroll-threshold scrollThreshold true number

在滚动多少距离之后触发滚动行为，单位为 px
order order true number

该组件在 <mdui-layout> 中的布局顺序，按从小到大排序。默认为 0
### 事件
名称 描述
show

开始显示时，事件被触发。可以通过调用 event.preventDefault() 阻止显示
shown

显示动画完成时，事件被触发
hide

开始隐藏时，事件被触发。可以通过调用 event.preventDefault() 阻止隐藏
hidden

隐藏动画完成时，事件被触发
### Slots
名称 描述
默认

顶部应用栏内部的元素
### CSS 自定义属性
名称 描述
--shape-corner

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

组件的 CSS z-index 值
# jq 工具库 mdui 内置了一个轻量级的 JavaScript 工具库，它提供了类似于 jQuery 的 API 和链式调用方式，但其体积只有 jQuery 的六分之一。 你可以按需导入该工具函数： ```js import { $ } from 'mdui/jq.js'; ``` ## 核心 {#api-core} ### `$()` {#dollar} 该函数有多种用法： 传入 CSS 选择器作为参数，返回包含匹配元素的 JQ 对象。 ```js $('.box'); ``` 传入 DOM 元素、任意数组、NodeList 或 JQ 对象，返回包含指定元素的 JQ 对象。 ```js $(document); ``` 传入 HTML 字符串，返回包含根据 HTML 创建的 DOM 的 JQ 对象。 ```js $(`
`); ``` 传入一个函数，当 DOM 加载完毕后会调用该函数。 ```js $(function () { console.log('DOM Loaded') }); ``` ## 扩展 {#api-extend} ### `$.extend()` {#d-extend} 如果只传入一个对象，该对象中的属性将合并到 `$` 对象中，相当于在 `$` 的命名空间下添加新的功能。 ```js $.extend({ customFunc: function () {} }); // 然后就可以这样调用自定义方法了 $.customFunc(); ``` 如果传入了两个或更多个对象，所有对象的属性都添加到第一个对象，并返回合并后的对象。不过值为 `undefined` 的属性不会合并。 ```js const object = $.extend( { key1: val1 }, { key2: val2 }, { key3: val3 } ); // 此时第一个对象和返回值都是 { key1: val1, key2: val2, key3: val3 } ``` ### `$.fn.extend()` {#fn-extend} 在 `$` 的原型链上扩展方法。 ```js $.fn.extend({ customFunc: function () {} }); // 然后就可以这样使用扩展的方法了 $(document).customFunc(); ``` ## URL {#api-url} ### `$.param()` {#d-param} 将数组或对象序列化为 URL 查询字符串。 ```js $.param({ width: 1680, height: 1050 }); // width=1680&height=1050 $.param({ foo: { one: 1, two: 2 } }); // foo[one]=1&foo[two]=2 $.param({ ids: [1, 2, 3] }); // ids[]=1&ids[]=2&ids[]=3 ``` 如果传入的参数是数组，那么该数组的格式必须与 [`.serializeArray()`](#serializeArray) 返回的格式一致。 ```js $.param([ { "name": "name", "value": "mdui" }, { "name": "password", "value": "123456" } ]); // name=mdui&password=123456 ``` ## 数组和对象操作 {#api-array} ### `$.each()` {#d-each} 遍历数组或对象。它返回的是第一个参数，即被遍历的数组或对象。 回调函数的第一个参数是数组的索引或对象的键，第二个参数是数组或对象对应位置的值。 在回调函数中，`this` 指向数组或对象对应位置的值。如果回调函数返回 `false`，则停止遍历。 ```js // 遍历数组 $.each(['a', 'b', 'c'], function (index, value) { console.log(index + ':' + value); }); // 结果： // 0:a // 1:b // 2:c ``` ```js // 遍历对象 $.each({'name': 'mdui', 'lang': 'zh'}, function (key, value) { console.log(key + ':' + value); }); // 结果 // name:mdui // lang:zh ``` ### `$.merge()` {#d-merge} 将第二个数组的元素追加到第一个数组中，并返回合并后的数组。 ```js const first = ['a', 'b', 'c']; const second = ['c', 'd', 'e']; const result = $.merge(first, second); console.log(first); // ['a', 'b', 'c', 'c', 'd', 'e'] console.log(result); // ['a', 'b', 'c', 'c', 'd', 'e'] ``` ### `$.unique()` {#d-unique} 移除数组中的重复元素。 ```js const result = $.unique([1, 2, 12, 3, 2, 1, 2, 1, 1, 1, 1]); console.log(result); // [1, 2, 12, 3] ``` ### `$.map()` {#d-map} 遍历数组或对象，返回一个由回调函数的返回值组成的新数组。 回调函数的第一个参数是数组或对象对应位置的值，第二个参数是数组的索引或对象的键。 回调函数可以返回任何值。如果返回的是数组，那么这个数组会被展开。如果返回的是 `null` 或 `undefined`，那么这个值会被忽略。在回调函数内部，`this` 指向 `window` 对象。 ```js // 遍历数组 const result = $.map(['a', 'b', 'c'], function (value, index) { return index + value; }); console.log(result); // ['0a', '1b', '2c'] ``` ```js // 当回调函数返回数组时，数组会被展开 const result = $.map([1, 2, 3], function (value, index) { return [value, value + 1]; }); console.log(result); // [1, 2, 2, 3, 3, 4] ``` ```js // 遍历对象 const result = $.map({ name: 'mdui', password: '123456' }, function (value, key) { return key + ':' + value; }); console.log(result); // ['name:mdui', 'password:123456'] ``` ### `$.contains()` {#d-contains} 判断一个节点是否包含另一个节点。如果父节点包含子节点，返回 `true`；否则，返回 `false`。 ```js $.contains(document, document.body); // true $.contains(document.body, document); // false ``` ## 数据类型判断 {#api-type} ### `.is()` {#is} 判断集合中是否至少有一个元素与参数匹配。如果匹配，返回 `true`；否则，返回 `false`。 参数可以是 CSS 选择器、DOM 元素、DOM 元素数组、JQ 对象，或者回调函数。 如果参数是回调函数，那么函数的第一个参数是索引，第二个参数是当前元素。在函数内部，`this` 指向当前元素。如果函数返回 `true`，表示当前元素与参数匹配；如果返回 `false`，表示当前元素与参数不匹配。 ```js $('.box').is('.box'); // true $('.box').is('.boxss'); // false $('.box').is($('.box')[0]); // true ``` ```js // 通过回调函数的返回值做判断 $(document).is(function (index, element) { return element === document; }); // true ``` ## 对象访问 {#api-object} ### `.length` {#length} 返回当前集合中元素的数量。 ```js $('body').length; // 1 ``` ### `.each()` {#each} 遍历当前集合，为集合中的每个元素执行一个函数。如果函数返回 `false`，则停止遍历。 函数的第一个参数是元素的索引位置，第二个参数是当前元素。在函数内部，`this` 指向当前元素。 ```js $('img').each(function(index, element) { this.src = 'test' + index + '.jpg'; }); ``` ### `.map()` {#map} 遍历当前集合，为集合中的每个元素执行一个函数，返回由函数返回值组成的新集合。 函数可以返回单个数据或数据数组。如果返回数组，那么会将数组中的元素依次添加到新集合中。如果函数返回 `null` 或 `undefined`，那么这个值不会被添加到新集合中。 函数的第一个参数是元素的索引位置，第二个参数是当前元素。在函数内部，`this` 指向当前元素。 ```js const result = $('input.checked').map(function (i, element) { return element.value; }); // result 是一个由匹配元素的值组成的 JQ 对象 ``` ### `.eq()` {#eq} 返回一个新集合，该集合只包含指定索引位置的元素。 ```js $('div').eq(0); // 返回仅包含第一个元素的集合 $('div').eq(-1); // 返回仅包含最后一个元素的集合 $('div').eq(-2); // 返回仅包含倒数第二个元素的集合 ``` ### `.first()` {#first} 返回一个新集合，该集合只包含当前集合中的第一个元素。 ```js $('div').first(); // 返回仅包含第一个 div 的集合 ``` ### `.last()` {#last} 返回一个新集合，该集合只包含当前集合中的最后一个元素。 ```js $('div').last(); // 返回仅包含最后一个 div 的集合 ``` ### `.get()` {#get} 返回指定索引位置的元素。如果没有传入参数，它将返回由集合中所有元素组成的数组。 ```js $('div').get(); // 返回所有 div 元素组成的数组 $('div').get(0); // 返回第一个 div 元素 $('div').get(-1); // 返回最后一个 div 元素 ``` ### `.index()` {#index} 如果没有传入参数，它将返回当前集合中第一个元素相对于其同辈元素的索引值。 如果传入一个 CSS 选择器，它将返回当前集合中第一个元素相对于 CSS 选择器匹配元素的索引值。 如果传入一个 DOM 元素，它将返回该元素在当前集合中的索引值。 如果传入一个 JQ 对象，它将返回对象中第一个元素在当前集合中的索引值。 ```html
``` ```js $('#child3').index(); // 2 $('#child3').index('#child div'); // 2 $('#child div').index($('#child3').get(0)); // 2 ``` ### `.slice()` {#slice} 返回当前集合的子集。 你可以通过传入两个参数来指定子集的起始和结束位置（不包含结束位置的元素）。如果没有传入第二个参数，它将返回从起始位置到集合末尾的所有元素。 ```js // 返回集合中第三个（包含第三个）之后的所有元素 $('div').slice(3); // 返回集合中第三个到第五个（包含第三个，不包含第五个）之间的元素 $('div').slice(3, 5); ``` ### `.filter()` {#filter} 从当前集合中筛选出与指定表达式匹配的元素。参数可以是 CSS 选择器、DOM 元素、DOM 元素数组或回调函数。 如果参数是回调函数，该函数的第一个参数是元素的索引位置，第二个参数是当前元素。在函数内部，`this` 指向当前元素。如果函数返回 `true`，当前元素会被保留；如果返回 `false`，当前元素会被移除。 ```js // 筛选出所有含 .box 的 div 元素 $('div').filter('.box'); // 筛选出所有已选中选项 $('#select option').filter(function (index, element) { return element.selected; }); ``` ### `.not()` {#not} 从当前集合中筛选出与指定表达式不匹配的元素。 参数可以是 CSS 选择器、DOM 元素、DOM 元素数组、JQ 对象，或返回 `boolean` 值的回调函数。 如果参数是回调函数，该函数的第一个参数是元素的索引位置，第二个参数是当前元素。在函数内部，`this` 指向当前元素。如果函数返回 `true`，当前元素会被移除；如果返回 `false`，当前元素会被保留。 ```js // 筛选出所有不含 .box 类的 div 元素 $('div').not('.box'); // 筛选出所有未选中选项 $('#select option').not(function (index, element) { return element.selected; }); ``` ## CSS 类 {#api-css} ### `.hasClass()` {#hasClass} 判断集合中的第一个元素是否含有指定的 CSS 类。 ```js // 判断第一个 div 元素是否含有 .item $('div').hasClass('item'); ``` ### `.addClass()` {#addClass} 为集合中的每个元素添加 CSS 类，多个类名之间可以用空格分隔。 参数可以是字符串，也可以是一个返回 CSS 类名的回调函数。如果参数是回调函数，该函数的第一个参数是元素的索引位置，第二个参数是该元素上原有的 CSS 类名。在函数内部，`this` 指向当前元素。 ```js // 为所有 div 元素添加 .item $('div').addClass('item'); // 为所有 div 元素添加 .item1 和 .item2 $('div').addClass('item1 item2'); // 为所有 div 元素添加由回调函数返回的 CSS 类 $('div').addClass(function (index, currentClassName) { return currentClassName + '-' + index; }); ``` ### `.removeClass()` {#removeClass} 移除集合中每个元素上的指定 CSS 类，多个类名之间可以用空格分隔。 参数可以是字符串，也可以是一个返回 CSS 类名的回调函数。如果参数是回调函数，该函数的第一个参数是元素的索引位置，第二个参数是该元素上原有的 CSS 类名。在函数内部，`this` 指向当前元素。 如果没有传入参数，该方法将直接移除元素上的 `class` 属性。 ```js // 移除所有 div 元素上的 .item $('div').removeClass('item'); // 移除所有 div 元素上的 .item1 和 .item2 $('div').removeClass('item1 item2'); // 移除所有 div 元素上的由回调函数返回的 CSS 类 $('div').removeClass(function (index, currentClassName) { return 'item'; }); ``` ### `.toggleClass()` {#toggleClass} 如果元素上有指定的 CSS 类，则删除它；如果没有，则添加它。多个类名之间可以用空格分隔。 参数可以是字符串，也可以是一个返回 CSS 类名的回调函数。如果参数是回调函数，该函数的第一个参数是元素的索引位置，第二个参数是该元素上原有的 CSS 类名。在函数内部，`this` 指向当前元素。 ```js // 切换所有 div 元素上的 .item 类 $('div').toggleClass('item'); // 切换所有 div 元素上的 .item1 和 .item2 类 $('div').toggleClass('item1 item2'); // 切换所有 div 元素上的由回调函数返回的 CSS 类 $('div').toggleClass(function (index, currentClassName) { return 'item'; }); ``` ## 节点属性 {#api-attr} ### `.prop()` {#prop} 获取集合中第一个元素的 JavaScript 属性值。 ```js // 获取第一个元素 checked 属性值 $('input').prop('checked'); ``` 如果传入了两个参数，该方法将设置集合中所有元素的指定 JavaScript 属性值。 属性值可以是任意类型的值，或回调函数的返回值。回调函数的第一个参数为元素的索引位置，第二个参数为该元素上原有的属性值，函数内的 `this` 指向当前元素。 属性值可以是任意类型的值，也可以是一个返回属性值的回调函数。如果参数是回调函数，该函数的第一个参数是元素的索引位置，第二个参数是该元素上原有的属性值。在函数内部，`this` 指向当前元素。 如果属性值或回调函数的返回值为 `undefined`，该方法将不会修改元素的原有属性。 ```js // 设置所有选中元素的 checked 属性值为 true $('input').prop('checked', true); // 通过回调函数的返回值设置属性值 $('input').prop('checked', function (index, oldPropValue) { return true; }); ``` 也可以通过传入一个对象来同时设置多个属性。 ```js // 同时设置元素的多个属性值 $('input').prop({ checked: false, disabled: function (index, oldPropValue) { return true; } }); ``` ### `.removeProp()` {#removeProp} 删除集合中所有元素上指定的 JavaScript 属性值。 ```js $('input').removeProp('disabled'); ``` ### `.attr()` {#attr} 获取集合中第一个元素的 HTML 属性值。 ```js // 获取第一个元素的属性值 $('div').attr('username'); ``` 如果传入两个参数，该方法将设置集合中所有元素的指定 HTML 属性值。 属性值可以是字符串或数值，也可以是一个返回属性值的回调函数。如果参数是回调函数，该函数的第一个参数是元素的索引位置，第二个参数是该元素上原有的属性值。在函数内部，`this` 指向当前元素。 如果属性值或回调函数的返回值为 `null`，该方法将删除指定属性；如果为 `undefined`，则不会修改元素的原有属性。 ```js // 设置所有选中元素的属性值 $('div').attr('username', 'mdui'); // 通过回调函数的返回值设置属性值 $('div').attr('username', function (index, oldAttrValue) { return 'mdui'; }); ``` 也可以通过传入一个对象来同时设置多个属性。 ```js // 同时设置元素的多个属性值 $('div').attr({ username: 'mdui', lastname: function (index, oldAttrValue) { return 'test'; } }); ``` ### `.removeAttr()` {#removeAttr} 删除集合中所有元素上指定的 HTML 属性，多个属性名之间可以用空格分隔。 ```js // 删除集合中所有元素上的一个属性 $('div').removeAttr('username'); // 删除集合中所有元素上的多个属性 $('div').removeAttr('username lastname'); ``` ### `.val()` {#val} 返回集合中第一个元素的值。 如果元素是 ``、``、`