mdui 2.0.2 → 2.0.4

package/components/slider/slider-base.d.ts

@@ -1,15 +1,15 @@
-import { LitElement } from 'lit';
+import { MduiElement } from '@mdui/shared/base/mdui-element.js';
 import type { CSSResultGroup, TemplateResult } from 'lit';
 import type { Ref } from 'lit/directives/ref.js';
-declare const SliderBase_base: import("@open-wc/dedupe-mixin").Constructor<import("../ripple/ripple-mixin.js").RippleMixinInterface> & import("@open-wc/dedupe-mixin").Constructor<import("@mdui/shared/mixins/focusable.js").FocusableMixinInterface> & typeof LitElement;
-export declare class SliderBase extends SliderBase_base {
+declare const SliderBase_base: import("@open-wc/dedupe-mixin").Constructor<import("../ripple/ripple-mixin.js").RippleMixinInterface> & import("@open-wc/dedupe-mixin").Constructor<import("@mdui/shared/mixins/focusable.js").FocusableMixinInterface> & typeof MduiElement;
+export declare class SliderBase<E> extends SliderBase_base<E> {
     static styles: CSSResultGroup;
     /**
-     * 最小允许值，默认为 `0`
+     * 滑块的最小值，默认为 `0`
      */
     min: number;
     /**
-     * 最大允许值，默认为 `100`
+     * 滑块的最大值，默认为 `100`
      */
     max: number;
     /**
@@ -21,21 +21,21 @@ export declare class SliderBase extends SliderBase_base {
      */
     tickmarks: boolean;
     /**
-     * 是否不显示文本提示
+     * 是否隐藏文本提示
      */
     nolabel: boolean;
     /**
-     * 是否禁用
+     * 是否被禁用
      */
     disabled: boolean;
     /**
-     * 关联的 `form` 元素。此属性值必须为同一页面中的一个 `<form>` 元素的 `id` 属性。
+     * 关联的 `<form>` 元素。此属性值应为同一页面中的一个 `<form>` 元素的 `id`。
      *
-     * 如果此属性未指定，则元素必须是 `form` 元素的后代。利用此属性，你可以将元素放置在页面中的任何位置，而不仅仅是作为 `form` 元素的后代。
+     * 如果未指定此属性，则该元素必须是 `<form>` 元素的子元素。通过此属性，你可以将元素放置在页面的任何位置，而不仅仅是 `<form>` 元素的子元素。
      */
     form?: string;
     /**
-     * 滑块名称，将与表单数据一起提交
+     * 滑块的名称，该名称将与表单数据一起提交
      */
     name: string;
     /**
@@ -48,37 +48,41 @@ export declare class SliderBase extends SliderBase_base {
     protected readonly inputRef: Ref<HTMLInputElement>;
     protected readonly trackActiveRef: Ref<HTMLElement>;
     /**
-     * 表单验证状态对象
+     * 表单验证状态对象，具体参见 [`ValidityState`](https://developer.mozilla.org/zh-CN/docs/Web/API/ValidityState)
      */
     get validity(): ValidityState;
     /**
-     * 表单验证的错误提示信息
+     * 如果表单验证未通过，此属性将包含提示信息。如果验证通过，此属性将为空字符串
      */
     get validationMessage(): string;
     protected get rippleDisabled(): boolean;
     protected get focusElement(): HTMLElement;
     protected get focusDisabled(): boolean;
     /**
-     * 用于自定义标签的显示格式
+     * 用于自定义标签的显示格式的函数。函数参数为滑块的当前值，返回值为期望显示的文本。
      */
     labelFormatter: (value: number) => string;
     private onDisabledChange;
     /**
-     * 检查表单字段是否验证通过。若未通过则返回 `false`，并触发 `invalid` 事件；若验证通过，则返回 `true`
+     * 检查表单字段是否通过验证。如果未通过，返回 `false` 并触发 `invalid` 事件；如果通过，返回 `true`
      */
     checkValidity(): boolean;
     /**
-     * 检查表单字段是否验证通过。若未通过则返回 `false`，并触发 `invalid` 事件；若验证通过，则返回 `true`。
+     * 检查表单字段是否通过验证。如果未通过，返回 `false` 并触发 `invalid` 事件；如果通过，返回 `true`。
      *
-     * 验证未通过时，还将在组件上显示未通过的提示。
+     * 如果验证未通过，还会在组件上显示验证失败的提示。
      */
     reportValidity(): boolean;
     /**
-     * 设置自定义的错误提示文本。只要文本不为空，则表示字段验证未通过
+     * 设置自定义的错误提示文本。只要这个文本不为空，就表示字段未通过验证
      *
-     * @param message 自定义的提示文本
+     * @param message 自定义的错误提示文本
      */
     setCustomValidity(message: string): void;
+    /**
+     * value 不在 min、max 或 step 的限制范围内时，修正 value 的值
+     */
+    protected fixValue(value: number): number;
     /**
      * 获取候选值组成的数组
      */

package/components/slider/slider-base.js

@@ -1,25 +1,25 @@
 import { __decorate } from "tslib";
-import { html, LitElement } from 'lit';
+import { html } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { classMap } from 'lit/directives/class-map.js';
 import { createRef } from 'lit/directives/ref.js';
 import { when } from 'lit/directives/when.js';
+import { MduiElement } from '@mdui/shared/base/mdui-element.js';
 import { watch } from '@mdui/shared/decorators/watch.js';
 import { booleanConverter } from '@mdui/shared/helpers/decorator.js';
-import { emit } from '@mdui/shared/helpers/event.js';
 import { componentStyle } from '@mdui/shared/lit-styles/component-style.js';
 import { FocusableMixin } from '@mdui/shared/mixins/focusable.js';
 import { RippleMixin } from '../ripple/ripple-mixin.js';
 import { sliderBaseStyle } from './slider-base-style.js';
-export class SliderBase extends RippleMixin(FocusableMixin(LitElement)) {
+export class SliderBase extends RippleMixin(FocusableMixin(MduiElement)) {
     constructor() {
         super(...arguments);
         /**
-         * 最小允许值，默认为 `0`
+         * 滑块的最小值，默认为 `0`
          */
         this.min = 0;
         /**
-         * 最大允许值，默认为 `100`
+         * 滑块的最大值，默认为 `100`
          */
         this.max = 100;
         /**
@@ -31,15 +31,15 @@ export class SliderBase extends RippleMixin(FocusableMixin(LitElement)) {
          */
         this.tickmarks = false;
         /**
-         * 是否不显示文本提示
+         * 是否隐藏文本提示
          */
         this.nolabel = false;
         /**
-         * 是否禁用
+         * 是否被禁用
          */
         this.disabled = false;
         /**
-         * 滑块名称，将与表单数据一起提交
+         * 滑块的名称，该名称将与表单数据一起提交
          */
         this.name = '';
         /**
@@ -53,18 +53,18 @@ export class SliderBase extends RippleMixin(FocusableMixin(LitElement)) {
         this.inputRef = createRef();
         this.trackActiveRef = createRef();
         /**
-         * 用于自定义标签的显示格式
+         * 用于自定义标签的显示格式的函数。函数参数为滑块的当前值，返回值为期望显示的文本。
          */
         this.labelFormatter = (value) => value.toString();
     }
     /**
-     * 表单验证状态对象
+     * 表单验证状态对象，具体参见 [`ValidityState`](https://developer.mozilla.org/zh-CN/docs/Web/API/ValidityState)
      */
     get validity() {
         return this.inputRef.value.validity;
     }
     /**
-     * 表单验证的错误提示信息
+     * 如果表单验证未通过，此属性将包含提示信息。如果验证通过，此属性将为空字符串
      */
     get validationMessage() {
         return this.inputRef.value.validationMessage;
@@ -82,12 +82,13 @@ export class SliderBase extends RippleMixin(FocusableMixin(LitElement)) {
         this.invalid = !this.inputRef.value.checkValidity();
     }
     /**
-     * 检查表单字段是否验证通过。若未通过则返回 `false`，并触发 `invalid` 事件；若验证通过，则返回 `true`
+     * 检查表单字段是否通过验证。如果未通过，返回 `false` 并触发 `invalid` 事件；如果通过，返回 `true`
      */
     checkValidity() {
         const valid = this.inputRef.value.checkValidity();
         if (!valid) {
-            emit(this, 'invalid', {
+            // @ts-ignore
+            this.emit('invalid', {
                 bubbles: false,
                 cancelable: true,
                 composed: false,
@@ -96,20 +97,21 @@ export class SliderBase extends RippleMixin(FocusableMixin(LitElement)) {
         return valid;
     }
     /**
-     * 检查表单字段是否验证通过。若未通过则返回 `false`，并触发 `invalid` 事件；若验证通过，则返回 `true`。
+     * 检查表单字段是否通过验证。如果未通过，返回 `false` 并触发 `invalid` 事件；如果通过，返回 `true`。
      *
-     * 验证未通过时，还将在组件上显示未通过的提示。
+     * 如果验证未通过，还会在组件上显示验证失败的提示。
      */
     reportValidity() {
         this.invalid = !this.inputRef.value.reportValidity();
         if (this.invalid) {
-            const requestInvalid = emit(this, 'invalid', {
+            // @ts-ignore
+            const eventProceeded = this.emit('invalid', {
                 bubbles: false,
                 cancelable: true,
                 composed: false,
             });
-            // 调用了 preventDefault() 时，隐藏默认的表单错误提示
-            if (requestInvalid.defaultPrevented) {
+            if (!eventProceeded) {
+                // 调用了 preventDefault() 时，隐藏默认的表单错误提示
                 this.blur();
                 this.focus();
             }
@@ -117,14 +119,30 @@ export class SliderBase extends RippleMixin(FocusableMixin(LitElement)) {
         return !this.invalid;
     }
     /**
-     * 设置自定义的错误提示文本。只要文本不为空，则表示字段验证未通过
+     * 设置自定义的错误提示文本。只要这个文本不为空，就表示字段未通过验证
      *
-     * @param message 自定义的提示文本
+     * @param message 自定义的错误提示文本
      */
     setCustomValidity(message) {
         this.inputRef.value.setCustomValidity(message);
         this.invalid = !this.inputRef.value.checkValidity();
     }
+    /**
+     * value 不在 min、max 或 step 的限制范围内时，修正 value 的值
+     */
+    fixValue(value) {
+        const { min, max, step } = this;
+        // 确保 value 在 min 和 max 范围内
+        value = Math.min(Math.max(value, min), max);
+        // 计算最接近 value 的 step 值
+        const steps = Math.round((value - min) / step);
+        let fixedValue = min + steps * step;
+        // 如果修正后的值超出最大值，则减去一个 step
+        if (fixedValue > max) {
+            fixedValue -= step;
+        }
+        return fixedValue;
+    }
     /**
      * 获取候选值组成的数组
      */
@@ -138,7 +156,8 @@ export class SliderBase extends RippleMixin(FocusableMixin(LitElement)) {
         return when(!this.nolabel, () => html `<div part="label" class="label ${classMap({ 'label-visible': this.labelVisible })}">${this.labelFormatter(value)}</div>`);
     }
     onChange() {
-        emit(this, 'change');
+        // @ts-ignore
+        this.emit('change');
     }
 }
 SliderBase.styles = [

package/components/snackbar/index.d.ts

@@ -1,4 +1,4 @@
-import { LitElement } from 'lit';
+import { MduiElement } from '@mdui/shared/base/mdui-element.js';
 import '@mdui/shared/icons/clear.js';
 import '../button-icon.js';
 import '../button.js';
@@ -17,42 +17,42 @@ import type { CSSResultGroup, TemplateResult } from 'lit';
  * @event closed - Snackbar 隐藏动画完成时，事件被触发
  * @event action-click - 点击操作按钮时触发
  *
- * @slot - Snackbar 中的消息文本内容
+ * @slot - Snackbar 的消息文本内容
  * @slot action - 右侧的操作按钮
- * @slot close-button - 右侧的关闭按钮。必须设置 `closeable` 属性为 `true` 才会显示该按钮
- * @slot close-icon - 右侧的关闭按钮中的图标
+ * @slot close-button - 右侧的关闭按钮。必须设置 `closeable` 属性为 `true` 才会显示
+ * @slot close-icon - 关闭按钮中的图标
  *
  * @csspart message - 消息文本
  * @csspart action - 操作按钮
  * @csspart close-button - 关闭按钮
  * @csspart close-icon - 关闭按钮中的图标
  *
- * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐[引用设计令牌](/docs/2/styles/design-tokens#shape-corner)
- * @cssprop --z-index - 组件的 CSS 的 `z-index` 值
+ * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐引用[设计令牌](/docs/2/styles/design-tokens#shape-corner)
+ * @cssprop --z-index - 组件的 CSS `z-index` 值
  */
-export declare class Snackbar extends LitElement {
+export declare class Snackbar extends MduiElement<SnackbarEventMap> {
     static styles: CSSResultGroup;
     /**
      * 是否显示 Snackbar
      */
     open: boolean;
     /**
-     * Snackbar 出现的位置。默认为 `bottom`。可选值为：
+     * Snackbar 的显示位置。默认为 `bottom`。可选值包括：
      *
-     * * `top`：位于顶部，居中对齐
-     * * `top-start`：位于顶部，左对齐
-     * * `top-end`：位于顶部，右对齐
-     * * `bottom`：位于底部，居中对齐
-     * * `bottom-start`：位于底部，左对齐
-     * * `bottom-end`：位于底部，右对齐
+     * * `top`：顶部居中
+     * * `top-start`：顶部左对齐
+     * * `top-end`：顶部右对齐
+     * * `bottom`：底部居中
+     * * `bottom-start`：底部左对齐
+     * * `bottom-end`：底部右对齐
      */
-    placement: /*位于顶部，居中对齐*/ 'top' | /*位于顶部，左对齐*/ 'top-start' | /*位于顶部，右对齐*/ 'top-end' | /*位于底部，居中对齐*/ 'bottom' | /*位于底部，左对齐*/ 'bottom-start' | /*位于底部，右对齐*/ 'bottom-end';
+    placement: /*顶部居中*/ 'top' | /*顶部左对齐*/ 'top-start' | /*顶部右对齐*/ 'top-end' | /*底部居中*/ 'bottom' | /*底部左对齐*/ 'bottom-start' | /*底部右对齐*/ 'bottom-end';
     /**
      * 操作按钮的文本。也可以通过 `slot="action"` 设置操作按钮
      */
     action?: string;
     /**
-     * 操作按钮是否为 loading 状态
+     * 操作按钮是否处于加载中状态
      */
     actionLoading: boolean;
     /**
@@ -60,22 +60,22 @@ export declare class Snackbar extends LitElement {
      */
     closeable: boolean;
     /**
-     * 关闭按钮中的 Material Icons 图标名。也可以通过 `slot="close-icon"` 设置
+     * 关闭按钮的 Material Icons 图标名。也可以通过 `slot="close-icon"` 设置
      */
     closeIcon?: string;
     /**
-     * 消息文本最多显示几行。默认不限制行数。可选值为：
+     * 消息文本的最大显示行数。默认不限制。可选值包括：
      *
-     * * `1`：消息文本最多显示一行
-     * * `2`：消息文本最多显示两行
+     * * `1`：最多显示一行
+     * * `2`：最多显示两行
      */
-    messageLine?: /*消息文本最多显示一行*/ 1 | /*消息文本最多显示两行*/ 2;
+    messageLine?: /*最多显示一行*/ 1 | /*最多显示两行*/ 2;
     /**
-     * 在多长时间后自动关闭（单位为毫秒）。设置为 `0` 时，不自动关闭。默认为 5 秒后自动关闭。
+     * 自动关闭的延迟时间（单位：毫秒）。设置为 `0` 则不自动关闭。默认为 5000 毫秒
      */
     autoCloseDelay: number;
     /**
-     * 点击或触摸 Snackbar 以外的区域时是否关闭 Snackbar
+     * 点击或触摸 Snackbar 以外的区域时，是否关闭 Snackbar
      */
     closeOnOutsideClick: boolean;
     private closeTimeout;
@@ -91,6 +91,13 @@ export declare class Snackbar extends LitElement {
     private onActionClick;
     private onCloseClick;
 }
+export interface SnackbarEventMap {
+    open: CustomEvent<void>;
+    opened: CustomEvent<void>;
+    close: CustomEvent<void>;
+    closed: CustomEvent<void>;
+    'action-click': CustomEvent<void>;
+}
 declare global {
     interface HTMLElementTagNameMap {
         'mdui-snackbar': Snackbar;

package/components/snackbar/index.js

@@ -1,12 +1,12 @@
 import { __decorate } from "tslib";
-import { html, LitElement } from 'lit';
+import { html } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { when } from 'lit/directives/when.js';
+import { MduiElement } from '@mdui/shared/base/mdui-element.js';
 import { watch } from '@mdui/shared/decorators/watch.js';
 import { animateTo, stopAnimations } from '@mdui/shared/helpers/animate.js';
 import { breakpoint } from '@mdui/shared/helpers/breakpoint.js';
 import { booleanConverter } from '@mdui/shared/helpers/decorator.js';
-import { emit } from '@mdui/shared/helpers/event.js';
 import { getDuration, getEasing } from '@mdui/shared/helpers/motion.js';
 import { nothingTemplate } from '@mdui/shared/helpers/template.js';
 import '@mdui/shared/icons/clear.js';
@@ -28,20 +28,20 @@ import { style } from './style.js';
  * @event closed - Snackbar 隐藏动画完成时，事件被触发
  * @event action-click - 点击操作按钮时触发
  *
- * @slot - Snackbar 中的消息文本内容
+ * @slot - Snackbar 的消息文本内容
  * @slot action - 右侧的操作按钮
- * @slot close-button - 右侧的关闭按钮。必须设置 `closeable` 属性为 `true` 才会显示该按钮
- * @slot close-icon - 右侧的关闭按钮中的图标
+ * @slot close-button - 右侧的关闭按钮。必须设置 `closeable` 属性为 `true` 才会显示
+ * @slot close-icon - 关闭按钮中的图标
  *
  * @csspart message - 消息文本
  * @csspart action - 操作按钮
  * @csspart close-button - 关闭按钮
  * @csspart close-icon - 关闭按钮中的图标
  *
- * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐[引用设计令牌](/docs/2/styles/design-tokens#shape-corner)
- * @cssprop --z-index - 组件的 CSS 的 `z-index` 值
+ * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐引用[设计令牌](/docs/2/styles/design-tokens#shape-corner)
+ * @cssprop --z-index - 组件的 CSS `z-index` 值
  */
-let Snackbar = class Snackbar extends LitElement {
+let Snackbar = class Snackbar extends MduiElement {
     constructor() {
         super();
         /**
@@ -49,18 +49,18 @@ let Snackbar = class Snackbar extends LitElement {
          */
         this.open = false;
         /**
-         * Snackbar 出现的位置。默认为 `bottom`。可选值为：
+         * Snackbar 的显示位置。默认为 `bottom`。可选值包括：
          *
-         * * `top`：位于顶部，居中对齐
-         * * `top-start`：位于顶部，左对齐
-         * * `top-end`：位于顶部，右对齐
-         * * `bottom`：位于底部，居中对齐
-         * * `bottom-start`：位于底部，左对齐
-         * * `bottom-end`：位于底部，右对齐
+         * * `top`：顶部居中
+         * * `top-start`：顶部左对齐
+         * * `top-end`：顶部右对齐
+         * * `bottom`：底部居中
+         * * `bottom-start`：底部左对齐
+         * * `bottom-end`：底部右对齐
          */
         this.placement = 'bottom';
         /**
-         * 操作按钮是否为 loading 状态
+         * 操作按钮是否处于加载中状态
          */
         this.actionLoading = false;
         /**
@@ -68,11 +68,11 @@ let Snackbar = class Snackbar extends LitElement {
          */
         this.closeable = false;
         /**
-         * 在多长时间后自动关闭（单位为毫秒）。设置为 `0` 时，不自动关闭。默认为 5 秒后自动关闭。
+         * 自动关闭的延迟时间（单位：毫秒）。设置为 `0` 则不自动关闭。默认为 5000 毫秒
          */
         this.autoCloseDelay = 5000;
         /**
-         * 点击或触摸 Snackbar 以外的区域时是否关闭 Snackbar
+         * 点击或触摸 Snackbar 以外的区域时，是否关闭 Snackbar
          */
         this.closeOnOutsideClick = false;
         this.onDocumentClick = this.onDocumentClick.bind(this);
@@ -97,8 +97,8 @@ let Snackbar = class Snackbar extends LitElement {
                 await this.updateComplete;
             }
             if (hasUpdated) {
-                const requestOpen = emit(this, 'open', { cancelable: true });
-                if (requestOpen.defaultPrevented) {
+                const eventProceeded = this.emit('open', { cancelable: true });
+                if (!eventProceeded) {
                     return;
                 }
             }
@@ -155,14 +155,14 @@ let Snackbar = class Snackbar extends LitElement {
                 })),
             ]);
             if (hasUpdated) {
-                emit(this, 'opened');
+                this.emit('opened');
             }
             return;
         }
         // 关闭
         if (!this.open && this.hasUpdated) {
-            const requestClose = emit(this, 'close', { cancelable: true });
-            if (requestClose.defaultPrevented) {
+            const eventProceeded = this.emit('close', { cancelable: true });
+            if (!eventProceeded) {
                 return;
             }
             window.clearTimeout(this.closeTimeout);
@@ -191,7 +191,7 @@ let Snackbar = class Snackbar extends LitElement {
                 ...children.map((child) => animateTo(child, [{ opacity: 1 }, { opacity: 0, offset: 0.75 }, { opacity: 0 }], { duration, easing: easingLinear })),
             ]);
             this.style.display = 'none';
-            emit(this, 'closed');
+            this.emit('closed');
             return;
         }
     }
@@ -224,7 +224,7 @@ let Snackbar = class Snackbar extends LitElement {
     }
     onActionClick(event) {
         event.stopPropagation();
-        emit(this, 'action-click');
+        this.emit('action-click');
     }
     onCloseClick() {
         this.open = false;

package/components/switch/index.d.ts

@@ -1,10 +1,10 @@
-import { LitElement } from 'lit';
+import { MduiElement } from '@mdui/shared/base/mdui-element.js';
 import '@mdui/shared/icons/check.js';
 import '../icon.js';
 import type { Ripple } from '../ripple/index.js';
 import type { FormControl } from '@mdui/jq/shared/form.js';
 import type { CSSResultGroup, TemplateResult } from 'lit';
-declare const Switch_base: import("@open-wc/dedupe-mixin").Constructor<import("../ripple/ripple-mixin.js").RippleMixinInterface> & import("@open-wc/dedupe-mixin").Constructor<import("@mdui/shared/mixins/focusable.js").FocusableMixinInterface> & typeof LitElement;
+declare const Switch_base: import("@open-wc/dedupe-mixin").Constructor<import("../ripple/ripple-mixin.js").RippleMixinInterface> & import("@open-wc/dedupe-mixin").Constructor<import("@mdui/shared/mixins/focusable.js").FocusableMixinInterface> & typeof MduiElement;
 /**
  * @summary 开关切换组件
  *
@@ -26,10 +26,10 @@ declare const Switch_base: import("@open-wc/dedupe-mixin").Constructor<import(".
  * @csspart unchecked-icon - 未选中状态的图标
  * @csspart checked-icon 选中状态的图标
  *
- * @cssprop --shape-corner - 组件的轨道的圆角大小。可以指定一个具体的像素值；但更推荐[引用设计令牌](/docs/2/styles/design-tokens#shape-corner)
- * @cssprop --shape-corner-thumb - 组件的图标容器的圆角大小。可以指定一个具体的像素值；但更推荐[引用设计令牌](/docs/2/styles/design-tokens#shape-corner)
+ * @cssprop --shape-corner - 组件轨道的圆角大小。可以指定一个具体的像素值；但更推荐引用[设计令牌](/docs/2/styles/design-tokens#shape-corner)
+ * @cssprop --shape-corner-thumb - 组件图标容器的圆角大小。可以指定一个具体的像素值；但更推荐引用[设计令牌](/docs/2/styles/design-tokens#shape-corner)
  */
-export declare class Switch extends Switch_base implements FormControl {
+export declare class Switch extends Switch_base<SwitchEventMap> implements FormControl {
     static styles: CSSResultGroup;
     /**
      * 是否为禁用状态
@@ -40,7 +40,7 @@ export declare class Switch extends Switch_base implements FormControl {
      */
     checked: boolean;
     /**
-     * 默认选中状态。在重置表单时，将重置为该默认状态。该属性只能通过 JavaScript 属性设置
+     * 默认选中状态。在重置表单时，将重置为此状态。此属性只能通过 JavaScript 属性设置
      */
     defaultChecked: boolean;
     /**
@@ -50,17 +50,17 @@ export declare class Switch extends Switch_base implements FormControl {
     /**
      * 选中状态的 Material Icons 图标名。也可以通过 `slot="checked-icon"` 设置
      *
-     * 默认为 check 图标，可传入空字符串移除默认图标
+     * 默认为 `check` 图标，可传入空字符串移除默认图标
      */
     checkedIcon?: string;
     /**
-     * 提交表单时，是否必须选中该开关
+     * 提交表单时，是否必须选中此开关
      */
     required: boolean;
     /**
-     * 关联的 `form` 元素。此属性值必须为同一页面中的一个 `<form>` 元素的 `id` 属性。
+     * 关联的 `<form>` 元素。此属性值应为同一页面中的一个 `<form>` 元素的 `id`。
      *
-     * 如果此属性未指定，则元素必须是 `form` 元素的后代。利用此属性，你可以将元素放置在页面中的任何位置，而不仅仅是作为 `form` 元素的后代。
+     * 如果未指定此属性，则该元素必须是 `<form>` 元素的子元素。通过此属性，你可以将元素放置在页面的任何位置，而不仅仅是 `<form>` 元素的子元素。
      */
     form?: string;
     /**
@@ -80,11 +80,11 @@ export declare class Switch extends Switch_base implements FormControl {
     private readonly formController;
     private readonly hasSlotController;
     /**
-     * 表单验证状态对象
+     * 表单验证状态对象，具体参见 [`ValidityState`](https://developer.mozilla.org/zh-CN/docs/Web/API/ValidityState)
      */
     get validity(): ValidityState;
     /**
-     * 表单验证的错误提示信息
+     * 如果表单验证未通过，此属性将包含提示信息。如果验证通过，此属性将为空字符串
      */
     get validationMessage(): string;
     protected get rippleElement(): Ripple;
@@ -94,19 +94,19 @@ export declare class Switch extends Switch_base implements FormControl {
     private onDisabledChange;
     private onCheckedChange;
     /**
-     * 检查表单字段是否验证通过。若未通过则返回 `false`，并触发 `invalid` 事件；若验证通过，则返回 `true`
+     * 检查表单字段是否通过验证。如果未通过，返回 `false` 并触发 `invalid` 事件；如果通过，返回 `true`
      */
     checkValidity(): boolean;
     /**
-     * 检查表单字段是否验证通过。若未通过则返回 `false`，并触发 `invalid` 事件；若验证通过，则返回 `true`。
+     * 检查表单字段是否通过验证。如果未通过，返回 `false` 并触发 `invalid` 事件；如果通过，返回 `true`。
      *
-     * 验证未通过时，还将在组件上显示未通过的提示。
+     * 如果验证未通过，还会在组件上显示验证失败的提示。
      */
     reportValidity(): boolean;
     /**
-     * 设置自定义的错误提示文本。只要文本不为空，则表示字段验证未通过
+     * 设置自定义的错误提示文本。只要这个文本不为空，就表示字段未通过验证
      *
-     * @param message 自定义的提示文本
+     * @param message 自定义的错误提示文本
      */
     setCustomValidity(message: string): void;
     protected render(): TemplateResult;
@@ -115,6 +115,13 @@ export declare class Switch extends Switch_base implements FormControl {
      */
     private onChange;
 }
+export interface SwitchEventMap {
+    focus: FocusEvent;
+    blur: FocusEvent;
+    change: CustomEvent<void>;
+    input: Event;
+    invalid: CustomEvent<void>;
+}
 declare global {
     interface HTMLElementTagNameMap {
         'mdui-switch': Switch;