mdui 2.0.3 → 2.0.4

package/components/avatar/index.d.ts

@@ -8,35 +8,35 @@ import type { CSSResultGroup, TemplateResult } from 'lit';
  * <mdui-avatar src="https://avatars.githubusercontent.com/u/3030330?s=40&v=4"></mdui-avatar>
  * ```
  *
- * @slot - 自定义头像中的内容，可以为字母、汉字、`<img>` 元素、图标等
+ * @slot - 自定义头像内容，可以为字母、汉字、`<img>` 元素、图标等
  *
- * @csspart image - 使用图片头像时，组件内部的 `<img>` 元素
- * @csspart icon - 使用图标头像时，组件内部的 `<mdui-icon>` 元素
+ * @csspart image - 使用图片作为头像时，组件内部的 `<img>` 元素
+ * @csspart icon - 使用图标作为头像时，组件内部的 `<mdui-icon>` 元素
  *
- * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐[引用设计令牌](/docs/2/styles/design-tokens#shape-corner)
+ * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐引用[设计令牌](/docs/2/styles/design-tokens#shape-corner)
  */
 export declare class Avatar extends MduiElement<AvatarEventMap> {
     static styles: CSSResultGroup;
     /**
-     * 头像的图片地址
+     * 头像图片的 URL 地址
      */
     src?: string;
     /**
-     * 图片如何适应容器框，同原生的 <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit" target="_blank">`object-fit`</a>。可选值为：
+     * 图片如何适应容器框，与原生的 [`object-fit`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) 属性相同。可选值包括：
      *
-     * * `contain`：保持原有尺寸比例。内容被缩放
-     * * `cover`：保持原有尺寸比例。但部分内容可能被剪切
-     * * `fill`：默认，不保证保持原有的比例，内容拉伸填充整个内容容器
-     * * `none`：保留原有元素内容的长度和宽度，也就是说内容不会被重置
-     * * `scale-down`：保持原有尺寸比例。内容的尺寸与 `none` 或 `contain` 中的一个相同，取决于它们两个之间谁得到的对象尺寸会更小一些
+     * * `contain`：保持图片原有尺寸比例，内容会被等比例缩放
+     * * `cover`：保持图片原有尺寸比例，但部分内容可能被剪切
+     * * `fill`：默认值，不保持图片原有尺寸比例，内容会被拉伸以填充整个容器
+     * * `none`：保留图片原有尺寸，内容不会被缩放或拉伸
+     * * `scale-down`：保持图片原有尺寸比例，内容尺寸与 `none` 或 `contain` 中较小的一个相同
      */
-    fit?: /*保持原有尺寸比例。内容被缩放*/ 'contain' | /*保持原有尺寸比例。但部分内容可能被剪切*/ 'cover' | /*默认，不保证保持原有的比例，内容拉伸填充整个内容容器*/ 'fill' | /*保留原有元素内容的长度和宽度，也就是说内容不会被重置*/ 'none' | /*保持原有尺寸比例。内容的尺寸与 `none` 或 `contain` 中的一个相同，取决于它们两个之间谁得到的对象尺寸会更小一些*/ 'scale-down';
+    fit?: /*保持图片原有尺寸比例，内容会被等比例缩放*/ 'contain' | /*保持图片原有尺寸比例，但部分内容可能被剪切*/ 'cover' | /*默认值，不保持图片原有尺寸比例，内容会被拉伸以填充整个容器*/ 'fill' | /*保留图片原有尺寸，内容不会被缩放或拉伸*/ 'none' | /*保持图片原有尺寸比例，内容尺寸与 `none` 或 `contain` 中较小的一个相同*/ 'scale-down';
     /**
      * 头像的 Material Icons 图标名
      */
     icon?: string;
     /**
-     * 描述头像的替换文本
+     * 头像的替代文本描述
      */
     label?: string;
     private readonly hasSlotController;

package/components/avatar/index.js

@@ -16,12 +16,12 @@ import { style } from './style.js';
  * <mdui-avatar src="https://avatars.githubusercontent.com/u/3030330?s=40&v=4"></mdui-avatar>
  * ```
  *
- * @slot - 自定义头像中的内容，可以为字母、汉字、`<img>` 元素、图标等
+ * @slot - 自定义头像内容，可以为字母、汉字、`<img>` 元素、图标等
  *
- * @csspart image - 使用图片头像时，组件内部的 `<img>` 元素
- * @csspart icon - 使用图标头像时，组件内部的 `<mdui-icon>` 元素
+ * @csspart image - 使用图片作为头像时，组件内部的 `<img>` 元素
+ * @csspart icon - 使用图标作为头像时，组件内部的 `<mdui-icon>` 元素
  *
- * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐[引用设计令牌](/docs/2/styles/design-tokens#shape-corner)
+ * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐引用[设计令牌](/docs/2/styles/design-tokens#shape-corner)
  */
 let Avatar = class Avatar extends MduiElement {
     constructor() {

package/components/badge/index.d.ts

@@ -7,18 +7,19 @@ import type { CSSResultGroup, TemplateResult } from 'lit';
  * <mdui-badge>12</mdui-badge>
  * ```
  *
- * @slot - 显示的文本
+ * @slot - 徽标中显示的文本
  *
- * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐[引用设计令牌](/docs/2/styles/design-tokens#shape-corner)
+ * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐引用[设计令牌](/docs/2/styles/design-tokens#shape-corner)
  */
 export declare class Badge extends MduiElement<BadgeEventMap> {
     static styles: CSSResultGroup;
     /**
-     * 徽标形状。可选值为：
-     * * `small`：小型徽标，不显示文字
-     * * `large`：大型徽标，会显示文字
+     * 徽标的形状。可选值包括：
+     *
+     * * `small`：小型徽标，不显示文本
+     * * `large`：大型徽标，会显示文本
      */
-    variant: /*小型徽标，不显示文字*/ 'small' | /*大型徽标，会显示文字*/ 'large';
+    variant: /*小型徽标，不显示文本*/ 'small' | /*大型徽标，会显示文本*/ 'large';
     protected render(): TemplateResult;
 }
 export interface BadgeEventMap {

package/components/badge/index.js

@@ -12,17 +12,18 @@ import { style } from './style.js';
  * <mdui-badge>12</mdui-badge>
  * ```
  *
- * @slot - 显示的文本
+ * @slot - 徽标中显示的文本
  *
- * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐[引用设计令牌](/docs/2/styles/design-tokens#shape-corner)
+ * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐引用[设计令牌](/docs/2/styles/design-tokens#shape-corner)
  */
 let Badge = class Badge extends MduiElement {
     constructor() {
         super(...arguments);
         /**
-         * 徽标形状。可选值为：
-         * * `small`：小型徽标，不显示文字
-         * * `large`：大型徽标，会显示文字
+         * 徽标的形状。可选值包括：
+         *
+         * * `small`：小型徽标，不显示文本
+         * * `large`：大型徽标，会显示文本
          */
         this.variant = 'large';
     }

package/components/bottom-app-bar/index.d.ts

@@ -24,8 +24,8 @@ declare const BottomAppBar_base: import("@open-wc/dedupe-mixin").Constructor<imp
  *
  * @slot - 底部应用栏内部的元素
  *
- * @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 BottomAppBar extends BottomAppBar_base<BottomAppBarEventMap> {
     static styles: CSSResultGroup;
@@ -34,11 +34,12 @@ export declare class BottomAppBar extends BottomAppBar_base<BottomAppBarEventMap
      */
     hide: boolean;
     /**
-     * 是否使底部应用栏中的 [`<mdui-fab>`](/docs/2/components/fab) 组件脱离应用栏。若为 `true`，则在应用栏隐藏后，[`<mdui-fab>`](/docs/2/components/fab) 仍将停留在页面上
+     * 是否让底部应用栏中的 [`<mdui-fab>`](/docs/2/components/fab) 组件脱离应用栏。如果为 `true`，则当应用栏隐藏后，[`<mdui-fab>`](/docs/2/components/fab) 仍会停留在页面上
      */
     fabDetach: boolean;
     /**
      * 滚动行为。可选值为：
+     *
      * * `hide`：滚动时隐藏
      */
     scrollBehavior?: 'hide';

package/components/bottom-app-bar/index.js

@@ -27,8 +27,8 @@ import { style } from './style.js';
  *
  * @slot - 底部应用栏内部的元素
  *
- * @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 BottomAppBar = class BottomAppBar extends ScrollBehaviorMixin(LayoutItemBase) {
     constructor() {
@@ -38,7 +38,7 @@ let BottomAppBar = class BottomAppBar extends ScrollBehaviorMixin(LayoutItemBase
          */
         this.hide = false;
         /**
-         * 是否使底部应用栏中的 [`<mdui-fab>`](/docs/2/components/fab) 组件脱离应用栏。若为 `true`，则在应用栏隐藏后，[`<mdui-fab>`](/docs/2/components/fab) 仍将停留在页面上
+         * 是否让底部应用栏中的 [`<mdui-fab>`](/docs/2/components/fab) 组件脱离应用栏。如果为 `true`，则当应用栏隐藏后，[`<mdui-fab>`](/docs/2/components/fab) 仍会停留在页面上
          */
         this.fabDetach = false;
     }

package/components/button/button-base-style.js

@@ -1,2 +1,2 @@
 import { css } from 'lit';
-export const buttonBaseStyle = css `.button{position:relative;display:inline-flex;align-items:center;justify-content:center;height:100%;padding:0;overflow:hidden;color:inherit;font-size:inherit;font-family:inherit;letter-spacing:inherit;white-space:nowrap;text-align:center;text-decoration:none;vertical-align:middle;background:0 0;border:none;outline:0;cursor:inherit;-webkit-user-select:none;user-select:none;touch-action:manipulation;zoom:1;-webkit-user-drag:none}`;
+export const buttonBaseStyle = css `.button{position:relative;display:inline-flex;align-items:center;justify-content:center;height:100%;padding:0;overflow:hidden;color:inherit;font-size:inherit;font-family:inherit;font-weight:inherit;letter-spacing:inherit;white-space:nowrap;text-align:center;text-decoration:none;vertical-align:middle;background:0 0;border:none;outline:0;cursor:inherit;-webkit-user-select:none;user-select:none;touch-action:manipulation;zoom:1;-webkit-user-drag:none}`;

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

@@ -16,118 +16,117 @@ export declare class ButtonBase<E> extends ButtonBase_base<E> {
      */
     disabled: boolean;
     /**
-     * 是否为加载中状态
+     * 是否处于加载中状态
      */
     loading: boolean;
     /**
-     * 按钮的名称，将与表单数据一起提交
+     * 按钮的名称，将与表单数据一起提交。
      *
-     * **Note**：仅在未指定 `href` 属性时可用
+     * **Note**：仅在未设置 `href` 属性时，此属性才有效。
      */
     name: string;
     /**
-     * 按钮的初始值，将与表单数据一起提交
+     * 按钮的初始值，将与表单数据一起提交。
      *
-     * **Note**：仅在未指定 `href` 属性时可用
+     * **Note**：仅在未设置 `href` 属性时，此属性才有效。
      */
     value: string;
     /**
-     * 按钮的类型。默认值为 `button`。可选值为：
+     * 按钮的类型。默认类型为 `button`。可选类型包括：
      *
-     * * `submit`：点击按钮将表单数据提交给服务器
-     * * `reset`：点击按钮将表单中所有组件重置为初始值
-     * * `button`：按钮没有默认行为
+     * * `submit`：点击按钮会提交表单数据到服务器
+     * * `reset`：点击按钮会将表单中的所有字段重置为初始值
+     * * `button`：此类型的按钮没有默认行为
      *
-     * **Note**：仅在未指定 `href` 属性时可用
+     * **Note**：仅在未指定 `href` 属性时，此属性才有效。
      */
     type: /*此按钮将表单数据提交给服务器*/ 'submit' | /*此按钮重置所有组件为初始值*/ 'reset' | /*此按钮没有默认行为*/ 'button';
     /**
-     * 关联的 `form` 元素。此属性值必须为同一页面中的一个 `<form>` 元素的 `id` 属性。
+     * 关联的 `<form>` 元素。此属性值应为同一页面中的一个 `<form>` 元素的 `id`。
      *
-     * 如果此属性未指定，则元素必须是 `form` 元素的后代。利用此属性，你可以将元素放置在页面中的任何位置，而不仅仅是作为 `form` 元素的后代。
+     * 如果未指定此属性，则该元素必须是 `<form>` 元素的子元素。通过此属性，你可以将元素放置在页面的任何位置，而不仅仅是 `<form>` 元素的子元素。
      *
-     * **Note**：仅在未指定 `href` 属性时可用
+     * **Note**：仅在未指定 `href` 属性时，此属性才有效。
      */
     form?: string;
     /**
-     *
      * 指定提交表单的 URL。
      *
-     * 指定了该属性时，将覆盖 `form` 元素的 `action` 属性。
+     * 如果指定了此属性，将覆盖 `<form>` 元素的 `action` 属性。
      *
-     * **Note**：仅在未指定 `href` 属性、且 `type="submit"` 时可用。
+     * **Note**：仅在未指定 `href` 属性且 `type="submit"` 时，此属性才有效。
      */
     formAction?: string;
     /**
-     * 指定提交表单到服务器的内容类型。可选值为：
+     * 指定提交表单到服务器的内容类型。可选值包括：
      *
-     * * `application/x-www-form-urlencoded`：未指定属性时的默认值
-     * * `multipart/form-data`：当表单包含 `<input type="file">` 元素时使用此值
-     * * `text/plain`：出现于 HTML5，用于调试
+     * * `application/x-www-form-urlencoded`：未指定该属性时的默认值
+     * * `multipart/form-data`：当表单包含 `<input type="file">` 元素时使用
+     * * `text/plain`：HTML5 新增，用于调试
      *
-     * 指定了该属性时，将覆盖 `form` 元素的 `enctype` 属性。
+     * 如果指定了此属性，将覆盖 `<form>` 元素的 `enctype` 属性。
      *
-     * **Note**：仅在未指定 `href` 属性、且 `type="submit"` 时可用
+     * **Note**：仅在未指定 `href` 属性且 `type="submit"` 时，此属性才有效。
      */
-    formEnctype?: /*未指定属性时的默认值*/ 'application/x-www-form-urlencoded' | /*当表单包含 `<input type="file">` 元素时使用此值*/ 'multipart/form-data' | /*出现于 HTML5，用于调试*/ 'text/plain';
+    formEnctype?: /*未指定该属性时的默认值*/ 'application/x-www-form-urlencoded' | /*当表单包含 `<input type="file">` 元素时使用*/ 'multipart/form-data' | /*HTML5 新增，用于调试*/ 'text/plain';
     /**
-     * 指定提交表单使用的 HTTP 方法。可选值为：
+     * 指定提交表单时使用的 HTTP 方法。可选值包括：
      *
-     * * `post`：来自表单的数据被包含在表单内容中，被发送到服务器
-     * * `get`：来自表单的数据以 `?` 作为分隔符被附加到 form 的 URI 属性中，得到的 URI 被发送到服务器。当表单没有副作用，且仅包含 ASCII 字符时使用这种方法
+     * * `post`：表单数据包含在表单内容中，发送到服务器
+     * * `get`：表单数据以 `?` 作为分隔符附加到表单的 URI 属性中，生成的 URI 发送到服务器。当表单没有副作用，并且仅包含 ASCII 字符时，使用此方法
      *
-     * 指定了该属性时，将覆盖 `form` 元素的 `method` 属性。
+     * 如果设置了此属性，将覆盖 `<form>` 元素的 `method` 属性。
      *
-     * **Note**：仅在未指定 `href` 属性、且 `type="submit"` 时可用。
+     * **Note**：仅在未设置 `href` 属性且 `type="submit"` 时，此属性才有效。
      */
-    formMethod?: /*来自表单的数据被包含在表单内容中，被发送到服务器*/ 'post' | /*来自表单的数据以 `?` 作为分隔符被附加到 form 的 URI 属性中，得到的 URI 被发送到服务器。当表单没有副作用，且仅包含 ASCII 字符时使用这种方法*/ 'get';
+    formMethod?: /*表单数据包含在表单内容中，发送到服务器*/ 'post' | /*表单数据以 `?` 作为分隔符附加到表单的 URI 属性中，生成的 URI 发送到服务器。当表单没有副作用，并且仅包含 ASCII 字符时，使用此方法*/ 'get';
     /**
-     * 指定了该属性时，表示当表单被提交时不需要验证。
+     * 如果设置了此属性，表单提交时将不执行表单验证。
      *
-     * 指定了该属性时，将覆盖 `form` 元素的 `novalidate` 属性。
+     * 如果设置了此属性，将覆盖 `<form>` 元素的 `novalidate` 属性。
      *
-     * **Note**：仅在未指定 `href` 属性、且 `type="submit"` 时可用。
+     * **Note**：仅在未设置 `href` 属性且 `type="submit"` 时，此属性才有效。
      */
     formNoValidate: boolean;
     /**
-     * 在何处显示提交表单后接收到的响应。可选值为：
+     * 提交表单后接收到的响应应显示在何处。可选值包括：
      *
-     * * `_self`：默认。在同一框架中打开
+     * * `_self`：默认选项，在当前框架中打开
      * * `_blank`：在新窗口中打开
      * * `_parent`：在父框架中打开
      * * `_top`：在整个窗口中打开
      *
-     * 指定了该属性时，将覆盖 `form` 元素的 `target` 属性。
+     * 如果设置了此属性，将覆盖 `<form>` 元素的 `target` 属性。
      *
-     * **Note**：仅在未指定 `href` 属性、且 `type="submit"` 时可用
+     * **Note**：仅在未设置 `href` 属性且 `type="submit"` 时，此属性才有效。
      */
-    formTarget?: /*默认。在同一框架中打开*/ '_self' | /*在新窗口中打开*/ '_blank' | /*在父框架中打开*/ '_parent' | /*在整个窗口中打开*/ '_top';
+    formTarget?: /*默认选项，在当前框架中打开*/ '_self' | /*在新窗口中打开*/ '_blank' | /*在父框架中打开*/ '_parent' | /*在整个窗口中打开*/ '_top';
     private readonly formController;
     /**
-     * 表单验证状态对象
+     * 表单验证状态对象，具体参见 [`ValidityState`](https://developer.mozilla.org/zh-CN/docs/Web/API/ValidityState)
      */
     get validity(): ValidityState | undefined;
     /**
-     * 表单验证的错误提示信息
+     * 如果表单验证未通过，此属性将包含提示信息。如果验证通过，此属性将为空字符串
      */
     get validationMessage(): string | undefined;
     protected get rippleDisabled(): boolean;
     protected get focusElement(): HTMLElement | null;
     protected get focusDisabled(): boolean;
     /**
-     * 检查表单字段是否验证通过。若未通过则返回 `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 firstUpdated(_changedProperties: PropertyValues): void;

package/components/button/button-base.js

@@ -21,43 +21,43 @@ export class ButtonBase extends AnchorMixin(RippleMixin(FocusableMixin(MduiEleme
          */
         this.disabled = false;
         /**
-         * 是否为加载中状态
+         * 是否处于加载中状态
          */
         this.loading = false;
         /**
-         * 按钮的名称，将与表单数据一起提交
+         * 按钮的名称，将与表单数据一起提交。
          *
-         * **Note**：仅在未指定 `href` 属性时可用
+         * **Note**：仅在未设置 `href` 属性时，此属性才有效。
          */
         this.name = '';
         /**
-         * 按钮的初始值，将与表单数据一起提交
+         * 按钮的初始值，将与表单数据一起提交。
          *
-         * **Note**：仅在未指定 `href` 属性时可用
+         * **Note**：仅在未设置 `href` 属性时，此属性才有效。
          */
         this.value = '';
         /**
-         * 按钮的类型。默认值为 `button`。可选值为：
+         * 按钮的类型。默认类型为 `button`。可选类型包括：
          *
-         * * `submit`：点击按钮将表单数据提交给服务器
-         * * `reset`：点击按钮将表单中所有组件重置为初始值
-         * * `button`：按钮没有默认行为
+         * * `submit`：点击按钮会提交表单数据到服务器
+         * * `reset`：点击按钮会将表单中的所有字段重置为初始值
+         * * `button`：此类型的按钮没有默认行为
          *
-         * **Note**：仅在未指定 `href` 属性时可用
+         * **Note**：仅在未指定 `href` 属性时，此属性才有效。
          */
         this.type = 'button';
         /**
-         * 指定了该属性时，表示当表单被提交时不需要验证。
+         * 如果设置了此属性，表单提交时将不执行表单验证。
          *
-         * 指定了该属性时，将覆盖 `form` 元素的 `novalidate` 属性。
+         * 如果设置了此属性，将覆盖 `<form>` 元素的 `novalidate` 属性。
          *
-         * **Note**：仅在未指定 `href` 属性、且 `type="submit"` 时可用。
+         * **Note**：仅在未设置 `href` 属性且 `type="submit"` 时，此属性才有效。
          */
         this.formNoValidate = false;
         this.formController = new FormController(this);
     }
     /**
-     * 表单验证状态对象
+     * 表单验证状态对象，具体参见 [`ValidityState`](https://developer.mozilla.org/zh-CN/docs/Web/API/ValidityState)
      */
     get validity() {
         if (this.isButton()) {
@@ -65,7 +65,7 @@ export class ButtonBase extends AnchorMixin(RippleMixin(FocusableMixin(MduiEleme
         }
     }
     /**
-     * 表单验证的错误提示信息
+     * 如果表单验证未通过，此属性将包含提示信息。如果验证通过，此属性将为空字符串
      */
     get validationMessage() {
         if (this.isButton()) {
@@ -86,7 +86,7 @@ export class ButtonBase extends AnchorMixin(RippleMixin(FocusableMixin(MduiEleme
         return this.disabled || this.loading;
     }
     /**
-     * 检查表单字段是否验证通过。若未通过则返回 `false`，并触发 `invalid` 事件；若验证通过，则返回 `true`
+     * 检查表单字段是否通过验证。如果未通过，返回 `false` 并触发 `invalid` 事件；如果通过，返回 `true`
      */
     checkValidity() {
         if (this.isButton()) {
@@ -104,9 +104,9 @@ export class ButtonBase extends AnchorMixin(RippleMixin(FocusableMixin(MduiEleme
         return true;
     }
     /**
-     * 检查表单字段是否验证通过。若未通过则返回 `false`，并触发 `invalid` 事件；若验证通过，则返回 `true`。
+     * 检查表单字段是否通过验证。如果未通过，返回 `false` 并触发 `invalid` 事件；如果通过，返回 `true`。
      *
-     * 验证未通过时，还将在组件上显示未通过的提示。
+     * 如果验证未通过，还会在组件上显示验证失败的提示。
      */
     reportValidity() {
         if (this.isButton()) {
@@ -125,9 +125,9 @@ export class ButtonBase extends AnchorMixin(RippleMixin(FocusableMixin(MduiEleme
         return true;
     }
     /**
-     * 设置自定义的错误提示文本。只要文本不为空，则表示字段验证未通过
+     * 设置自定义的错误提示文本。只要这个文本不为空，就表示字段未通过验证
      *
-     * @param message 自定义的提示文本
+     * @param message 自定义的错误提示文本
      */
     setCustomValidity(message) {
         if (this.isButton()) {

package/components/button/index.d.ts

@@ -14,29 +14,29 @@ import type { TemplateResult, CSSResultGroup } from 'lit';
  * @event invalid - 表单字段验证未通过时触发
  *
  * @slot - 按钮的文本
- * @slot icon - 按钮左侧元素
- * @slot end-icon - 按钮右侧元素
+ * @slot icon - 按钮左侧的元素
+ * @slot end-icon - 按钮右侧的元素
  *
  * @csspart button - 内部的 `<button>` 或 `<a>` 元素
- * @csspart label - 按钮文本
- * @csspart icon - 按钮左侧图标
- * @csspart end-icon - 按钮右侧图标
+ * @csspart label - 按钮的文本
+ * @csspart icon - 按钮左侧的图标
+ * @csspart end-icon - 按钮右侧的图标
  * @csspart loading - 加载中状态的 `<mdui-circular-progress>` 元素
  *
- * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐[引用设计令牌](/docs/2/styles/design-tokens#shape-corner)
+ * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐引用[设计令牌](/docs/2/styles/design-tokens#shape-corner)
  */
 export declare class Button extends ButtonBase<ButtonEventMap> {
     static styles: CSSResultGroup;
     /**
-     * 按钮形状。可选值为：
+     * 按钮的形状。可选值包括：
      *
-     * * `elevated`：带阴影的按钮，在需要把按钮和背景进行视觉分离时使用
-     * * `filled`：视觉效果仅次于 FAB，用于重要流程的最终操作，如“保存”、“确认”等
-     * * `tonal`：视觉效果介于 `filled` 和 `outlined` 之间，用于中高优先级的操作，如流程中的“下一步”
-     * * `outlined`：带边框的按钮，用于中等优先级，且次要的操作，如“返回”
-     * * `text`：文本按钮，用于最低优先级的操作
+     * * `elevated`：带阴影的按钮，适用于需要将按钮与背景视觉分离的场景
+     * * `filled`：视觉效果强烈，适用于重要流程的最终操作，如“保存”、“确认”等
+     * * `tonal`：视觉效果介于 `filled` 和 `outlined` 之间，适用于中高优先级的操作，如流程中的“下一步”
+     * * `outlined`：带边框的按钮，适用于中等优先级，且次要的操作，如“返回”
+     * * `text`：文本按钮，适用于最低优先级的操作
      */
-    variant: /*带阴影的按钮，在需要把按钮和背景进行视觉分离时使用*/ 'elevated' | /*视觉效果仅次于 FAB，用于重要流程的最终操作，如“保存”、“确认”等*/ 'filled' | /*视觉效果介于 `filled` 和 `outlined` 之间，用于中等偏高优先级的场景，如流程中的“下一步”*/ 'tonal' | /*带边框的按钮，用于中等优先级，且次要操作的场景，如“返回”*/ 'outlined' | /*文本按钮，用于最低优先级的操作*/ 'text';
+    variant: /*带阴影的按钮，适用于需要将按钮与背景视觉分离的场景*/ 'elevated' | /*视觉效果强烈，适用于重要流程的最终操作，如“保存”、“确认”等*/ 'filled' | /*视觉效果介于 `filled` 和 `outlined` 之间，适用于中高优先级的操作，如流程中的“下一步”*/ 'tonal' | /*带边框的按钮，适用于中等优先级，且次要的操作，如“返回”*/ 'outlined' | /*文本按钮，适用于最低优先级的操作*/ 'text';
     /**
      * 是否填满父元素宽度
      */

package/components/button/index.js

@@ -19,28 +19,28 @@ import { style } from './style.js';
  * @event invalid - 表单字段验证未通过时触发
  *
  * @slot - 按钮的文本
- * @slot icon - 按钮左侧元素
- * @slot end-icon - 按钮右侧元素
+ * @slot icon - 按钮左侧的元素
+ * @slot end-icon - 按钮右侧的元素
  *
  * @csspart button - 内部的 `<button>` 或 `<a>` 元素
- * @csspart label - 按钮文本
- * @csspart icon - 按钮左侧图标
- * @csspart end-icon - 按钮右侧图标
+ * @csspart label - 按钮的文本
+ * @csspart icon - 按钮左侧的图标
+ * @csspart end-icon - 按钮右侧的图标
  * @csspart loading - 加载中状态的 `<mdui-circular-progress>` 元素
  *
- * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐[引用设计令牌](/docs/2/styles/design-tokens#shape-corner)
+ * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐引用[设计令牌](/docs/2/styles/design-tokens#shape-corner)
  */
 let Button = class Button extends ButtonBase {
     constructor() {
         super(...arguments);
         /**
-         * 按钮形状。可选值为：
+         * 按钮的形状。可选值包括：
          *
-         * * `elevated`：带阴影的按钮，在需要把按钮和背景进行视觉分离时使用
-         * * `filled`：视觉效果仅次于 FAB，用于重要流程的最终操作，如“保存”、“确认”等
-         * * `tonal`：视觉效果介于 `filled` 和 `outlined` 之间，用于中高优先级的操作，如流程中的“下一步”
-         * * `outlined`：带边框的按钮，用于中等优先级，且次要的操作，如“返回”
-         * * `text`：文本按钮，用于最低优先级的操作
+         * * `elevated`：带阴影的按钮，适用于需要将按钮与背景视觉分离的场景
+         * * `filled`：视觉效果强烈，适用于重要流程的最终操作，如“保存”、“确认”等
+         * * `tonal`：视觉效果介于 `filled` 和 `outlined` 之间，适用于中高优先级的操作，如流程中的“下一步”
+         * * `outlined`：带边框的按钮，适用于中等优先级，且次要的操作，如“返回”
+         * * `text`：文本按钮，适用于最低优先级的操作
          */
         this.variant = 'filled';
         /**

package/components/button-icon/index.d.ts

@@ -22,19 +22,19 @@ import type { CSSResultGroup, PropertyValues, TemplateResult } from 'lit';
  * @csspart selected-icon 选中状态的图标
  * @csspart loading - 加载中状态的 `<mdui-circular-progress>` 元素
  *
- * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐[引用设计令牌](/docs/2/styles/design-tokens#shape-corner)
+ * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐引用[设计令牌](/docs/2/styles/design-tokens#shape-corner)
  */
 export declare class ButtonIcon extends ButtonBase<ButtonIconEventMap> {
     static styles: CSSResultGroup;
     /**
-     * 图标按钮的形状。可选值为：
+     * 图标按钮的形状。可选值包括：
      *
-     * * `standard`：用于最低优先级的操作
-     * * `filled`：具有最强视觉效果，用于高优先级的操作
-     * * `tonal`：视觉效果介于 `filled` 和 `outlined` 之间，用于中高优先级的操作
-     * * `outlined`：用于中等优先级的操作
+     * * `standard`：适用于最低优先级的操作
+     * * `filled`：视觉效果强烈，适用于高优先级的操作
+     * * `tonal`：视觉效果介于 `filled` 和 `outlined` 之间，适用于中高优先级的操作
+     * * `outlined`：适用于中等优先级的操作
      */
-    variant: /*用于最低优先级的操作*/ 'standard' | /*具有最强视觉效果，用于高优先级的操作*/ 'filled' | /*视觉效果介于 `filled` 和 `outlined` 之间，用于中高优先级的操作*/ 'tonal' | /*用于中等优先级的操作*/ 'outlined';
+    variant: /*适用于最低优先级的操作*/ 'standard' | /*视觉效果强烈，适用于高优先级的操作*/ 'filled' | /*视觉效果介于 `filled` 和 `outlined` 之间，适用于中高优先级的操作*/ 'tonal' | /*适用于中等优先级的操作*/ 'outlined';
     /**
      * Material Icons 图标名。也可以通过 default slot 设置
      */
@@ -48,7 +48,7 @@ export declare class ButtonIcon extends ButtonBase<ButtonIconEventMap> {
      */
     selectable: boolean;
     /**
-     * 是否已选中
+     * 是否已被选中
      */
     selected: boolean;
     private readonly rippleRef;

package/components/button-icon/index.js

@@ -29,18 +29,18 @@ import { style } from './style.js';
  * @csspart selected-icon 选中状态的图标
  * @csspart loading - 加载中状态的 `<mdui-circular-progress>` 元素
  *
- * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐[引用设计令牌](/docs/2/styles/design-tokens#shape-corner)
+ * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐引用[设计令牌](/docs/2/styles/design-tokens#shape-corner)
  */
 let ButtonIcon = class ButtonIcon extends ButtonBase {
     constructor() {
         super(...arguments);
         /**
-         * 图标按钮的形状。可选值为：
+         * 图标按钮的形状。可选值包括：
          *
-         * * `standard`：用于最低优先级的操作
-         * * `filled`：具有最强视觉效果，用于高优先级的操作
-         * * `tonal`：视觉效果介于 `filled` 和 `outlined` 之间，用于中高优先级的操作
-         * * `outlined`：用于中等优先级的操作
+         * * `standard`：适用于最低优先级的操作
+         * * `filled`：视觉效果强烈，适用于高优先级的操作
+         * * `tonal`：视觉效果介于 `filled` 和 `outlined` 之间，适用于中高优先级的操作
+         * * `outlined`：适用于中等优先级的操作
          */
         this.variant = 'standard';
         /**
@@ -48,7 +48,7 @@ let ButtonIcon = class ButtonIcon extends ButtonBase {
          */
         this.selectable = false;
         /**
-         * 是否已选中
+         * 是否已被选中
          */
         this.selected = false;
         this.rippleRef = createRef();