mdui 2.0.3 → 2.0.4

package/components/card/index.d.ts

@@ -12,22 +12,22 @@ declare const Card_base: import("@open-wc/dedupe-mixin").Constructor<import("@md
  * @event focus - 获得焦点时触发
  * @event blur - 失去焦点时触发
  *
- * @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 Card extends Card_base<CardEventMap> {
     static styles: CSSResultGroup;
     /**
-     * 卡片形状。可选值为：
+     * 卡片的形状。可选值包括：
      *
-     * * `elevated`：具有阴影，与背景的分离度比 `filled` 更高，但小于 `outlined`
-     * * `filled`：与背景的分离度最小
-     * * `outlined`：具有边框，与背景的分离度最大
+     * * `elevated`：带阴影的卡片，与背景的视觉分离度较高
+     * * `filled`：带填充色的卡片，与背景的视觉分离度较低
+     * * `outlined`：带边框的卡片，与背景的视觉分离度最高
      */
-    variant: /*具有阴影，与背景的分离度比 `filled` 更高，但小于 `outlined`*/ 'elevated' | /*与背景的分离度最小*/ 'filled' | /*具有边框，与背景的分离度最大*/ 'outlined';
+    variant: /*带阴影的卡片，与背景的视觉分离度较高*/ 'elevated' | /*带填充色的卡片，与背景的视觉分离度较低*/ 'filled' | /*带边框的卡片，与背景的视觉分离度最高*/ 'outlined';
     /**
-     * 是否可点击。为 `true` 时，会添加鼠标悬浮效果、及点击涟漪效果
+     * 是否可点击。为 `true` 时，卡片将具有鼠标悬浮效果和点击涟漪效果
      */
     clickable: boolean;
     /**

package/components/card/index.js

@@ -19,23 +19,23 @@ import { style } from './style.js';
  * @event focus - 获得焦点时触发
  * @event blur - 失去焦点时触发
  *
- * @slot - 卡片内容
+ * @slot - 卡片的内容
  *
- * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐[引用设计令牌](/docs/2/styles/design-tokens#shape-corner)
+ * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐引用[设计令牌](/docs/2/styles/design-tokens#shape-corner)
  */
 let Card = class Card extends AnchorMixin(RippleMixin(FocusableMixin(MduiElement))) {
     constructor() {
         super(...arguments);
         /**
-         * 卡片形状。可选值为：
+         * 卡片的形状。可选值包括：
          *
-         * * `elevated`：具有阴影，与背景的分离度比 `filled` 更高，但小于 `outlined`
-         * * `filled`：与背景的分离度最小
-         * * `outlined`：具有边框，与背景的分离度最大
+         * * `elevated`：带阴影的卡片，与背景的视觉分离度较高
+         * * `filled`：带填充色的卡片，与背景的视觉分离度较低
+         * * `outlined`：带边框的卡片，与背景的视觉分离度最高
          */
         this.variant = 'elevated';
         /**
-         * 是否可点击。为 `true` 时，会添加鼠标悬浮效果、及点击涟漪效果
+         * 是否可点击。为 `true` 时，卡片将具有鼠标悬浮效果和点击涟漪效果
          */
         this.clickable = false;
         /**

package/components/checkbox/index.d.ts

@@ -20,16 +20,16 @@ declare const Checkbox_base: import("@open-wc/dedupe-mixin").Constructor<import(
  * @event input - 选中状态变更时触发
  * @event invalid - 表单字段验证未通过时触发
  *
- * @slot - 文本
- * @slot unchecked-icon - 未选中状态图标
- * @slot checked-icon - 选中状态图标
- * @slot indeterminate-icon - 不确定状态图标
+ * @slot - 复选框文本
+ * @slot unchecked-icon - 未选中状态的图标
+ * @slot checked-icon - 选中状态的图标
+ * @slot indeterminate-icon - 不确定状态的图标
  *
  * @csspart control - 左侧图标容器
- * @csspart unchecked-icon - 未选中状态图标
- * @csspart checked-icon - 选中状态图标
- * @csspart indeterminate-icon - 不确定状态图标
- * @csspart label - 文本
+ * @csspart unchecked-icon - 未选中状态的图标
+ * @csspart checked-icon - 选中状态的图标
+ * @csspart indeterminate-icon - 不确定状态的图标
+ * @csspart label - 复选框文本
  */
 export declare class Checkbox extends Checkbox_base<CheckboxEventMap> implements FormControl {
     static styles: CSSResultGroup;
@@ -42,21 +42,21 @@ export declare class Checkbox extends Checkbox_base<CheckboxEventMap> implements
      */
     checked: boolean;
     /**
-     * 默认选中状态。在重置表单时，将重置为该默认状态。该属性只能通过 JavaScript 属性设置
+     * 默认选中状态。在重置表单时，将恢复为此状态。此属性只能通过 JavaScript 属性设置
      */
     defaultChecked: boolean;
     /**
-     * 是否为不确定状态
+     * 是否处于不确定状态
      */
     indeterminate: boolean;
     /**
-     * 提交表单时，是否必须选中该复选框
+     * 提交表单时，是否必须选中此复选框
      */
     required: boolean;
     /**
-     * 关联的 `form` 元素。此属性值必须为同一页面中的一个 `<form>` 元素的 `id` 属性。
+     * 关联的 `<form>` 元素。此属性值应为同一页面中的一个 `<form>` 元素的 `id`。
      *
-     * 如果此属性未指定，则元素必须是 `form` 元素的后代。利用此属性，你可以将元素放置在页面中的任何位置，而不仅仅是作为 `form` 元素的后代。
+     * 如果未指定此属性，则该元素必须是 `<form>` 元素的子元素。通过此属性，你可以将元素放置在页面的任何位置，而不仅仅是 `<form>` 元素的子元素。
      */
     form?: string;
     /**
@@ -87,11 +87,11 @@ export declare class Checkbox extends Checkbox_base<CheckboxEventMap> implements
     private readonly rippleRef;
     private readonly formController;
     /**
-     * 表单验证状态对象
+     * 表单验证状态对象，具体参见 [`ValidityState`](https://developer.mozilla.org/zh-CN/docs/Web/API/ValidityState)
      */
     get validity(): ValidityState;
     /**
-     * 表单验证的错误提示信息
+     * 如果表单验证未通过，此属性将包含提示信息。如果验证通过，此属性将为空字符串
      */
     get validationMessage(): string;
     protected get rippleElement(): Ripple;
@@ -101,19 +101,19 @@ export declare class Checkbox extends Checkbox_base<CheckboxEventMap> implements
     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;

package/components/checkbox/index.js

@@ -31,16 +31,16 @@ import { style } from './style.js';
  * @event input - 选中状态变更时触发
  * @event invalid - 表单字段验证未通过时触发
  *
- * @slot - 文本
- * @slot unchecked-icon - 未选中状态图标
- * @slot checked-icon - 选中状态图标
- * @slot indeterminate-icon - 不确定状态图标
+ * @slot - 复选框文本
+ * @slot unchecked-icon - 未选中状态的图标
+ * @slot checked-icon - 选中状态的图标
+ * @slot indeterminate-icon - 不确定状态的图标
  *
  * @csspart control - 左侧图标容器
- * @csspart unchecked-icon - 未选中状态图标
- * @csspart checked-icon - 选中状态图标
- * @csspart indeterminate-icon - 不确定状态图标
- * @csspart label - 文本
+ * @csspart unchecked-icon - 未选中状态的图标
+ * @csspart checked-icon - 选中状态的图标
+ * @csspart indeterminate-icon - 不确定状态的图标
+ * @csspart label - 复选框文本
  */
 let Checkbox = class Checkbox extends RippleMixin(FocusableMixin(MduiElement)) {
     constructor() {
@@ -54,15 +54,15 @@ let Checkbox = class Checkbox extends RippleMixin(FocusableMixin(MduiElement)) {
          */
         this.checked = false;
         /**
-         * 默认选中状态。在重置表单时，将重置为该默认状态。该属性只能通过 JavaScript 属性设置
+         * 默认选中状态。在重置表单时，将恢复为此状态。此属性只能通过 JavaScript 属性设置
          */
         this.defaultChecked = false;
         /**
-         * 是否为不确定状态
+         * 是否处于不确定状态
          */
         this.indeterminate = false;
         /**
-         * 提交表单时，是否必须选中该复选框
+         * 提交表单时，是否必须选中此复选框
          */
         this.required = false;
         /**
@@ -86,13 +86,13 @@ let Checkbox = class Checkbox extends RippleMixin(FocusableMixin(MduiElement)) {
         });
     }
     /**
-     * 表单验证状态对象
+     * 表单验证状态对象，具体参见 [`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;
@@ -126,7 +126,7 @@ let Checkbox = class Checkbox extends RippleMixin(FocusableMixin(MduiElement)) {
         }
     }
     /**
-     * 检查表单字段是否验证通过。若未通过则返回 `false`，并触发 `invalid` 事件；若验证通过，则返回 `true`
+     * 检查表单字段是否通过验证。如果未通过，返回 `false` 并触发 `invalid` 事件；如果通过，返回 `true`
      */
     checkValidity() {
         const valid = this.inputRef.value.checkValidity();
@@ -140,9 +140,9 @@ let Checkbox = class Checkbox extends RippleMixin(FocusableMixin(MduiElement)) {
         return valid;
     }
     /**
-     * 检查表单字段是否验证通过。若未通过则返回 `false`，并触发 `invalid` 事件；若验证通过，则返回 `true`。
+     * 检查表单字段是否通过验证。如果未通过，返回 `false` 并触发 `invalid` 事件；如果通过，返回 `true`。
      *
-     * 验证未通过时，还将在组件上显示未通过的提示。
+     * 如果验证未通过，还会在组件上显示验证失败的提示。
      */
     reportValidity() {
         this.invalid = !this.inputRef.value.reportValidity();
@@ -161,9 +161,9 @@ let Checkbox = class Checkbox extends RippleMixin(FocusableMixin(MduiElement)) {
         return !this.invalid;
     }
     /**
-     * 设置自定义的错误提示文本。只要文本不为空，则表示字段验证未通过
+     * 设置自定义的错误提示文本。只要这个文本不为空，就表示字段未通过验证
      *
-     * @param message 自定义的提示文本
+     * @param message 自定义的错误提示文本
      */
     setCustomValidity(message) {
         this.inputRef.value.setCustomValidity(message);

package/components/chip/index.d.ts

@@ -17,35 +17,35 @@ import type { CSSResultGroup, PropertyValues, TemplateResult } from 'lit';
  * @event change - 选中状态变更时触发
  * @event delete - 点击删除图标时触发
  *
- * @slot - 文本
+ * @slot - 纸片文本
  * @slot icon - 左侧元素
  * @slot end-icon - 右侧元素
- * @slot selected-icon - 选中状态的左侧元素
- * @slot delete-icon - 可删除时，右侧的删除元素
+ * @slot selected-icon - 选中状态下的左侧元素
+ * @slot delete-icon - 可删除时的右侧删除元素
  *
- * @csspart button - 内部的 `button` 或 `a` 元素
- * @csspart label - 文本
+ * @csspart button - 内部的 `<button>` 或 `<a>` 元素
+ * @csspart label - 纸片文本
  * @csspart icon - 左侧图标
  * @csspart end-icon - 右侧图标
- * @csspart selected-icon - 选中状态的左侧图标
- * @csspart delete-icon - 可删除时，右侧的删除图标
+ * @csspart selected-icon - 选中状态下的左侧图标
+ * @csspart delete-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 Chip extends ButtonBase<ChipEventMap> {
     static styles: CSSResultGroup;
     /**
-     * 纸片形状。可选值为：
+     * 纸片的形状。可选值包括：
      *
-     * * `assist`：用于显示和当前上下文相关的辅助操作。例如在点餐页面，提供分享，收藏等功能
-     * * `filter`：用于对内容进行筛选。例如在搜索结果页，对搜索结果进行过滤
-     * * `input`：用于表示用户输入的信息片段。例如 Gmail 中“收件人”字段中的联系人
-     * * `suggestion`：用于提供动态生成的推荐信息，以简化用户操作。例如在聊天应用中猜测用户可能想发送的信息，供用户选择
+     * * `assist`：用于显示与当前上下文相关的辅助操作，如在点餐页面提供分享、收藏等功能
+     * * `filter`：用于对内容进行筛选，如在搜索结果页过滤搜索结果
+     * * `input`：用于表示用户输入的信息片段，如在 Gmail 的“收件人”字段中的联系人
+     * * `suggestion`：用于提供动态生成的推荐信息，以简化用户操作，如在聊天应用中预测用户可能想发送的信息
      */
-    variant: /*用于显示和当前上下文相关的辅助操作。例如在点餐页面，提供分享，收藏等功能*/ 'assist' | /*用于对内容进行筛选。例如在搜索结果页，对搜索结果进行过滤*/ 'filter' | /*用于表示用户输入的信息片段。例如 Gmail 中“收件人”字段中的联系人*/ 'input' | /*用于提供动态生成的推荐信息，以简化用户操作。例如在聊天应用中猜测用户可能想发送的信息，供用户选择*/ 'suggestion';
+    variant: /*用于显示与当前上下文相关的辅助操作，如在点餐页面提供分享、收藏等功能*/ 'assist' | /*用于对内容进行筛选，如在搜索结果页过滤搜索结果*/ 'filter' | /*用于表示用户输入的信息片段，如在 Gmail 的“收件人”字段中的联系人*/ 'input' | /*用于提供动态生成的推荐信息，以简化用户操作，如在聊天应用中预测用户可能想发送的信息*/ 'suggestion';
     /**
-     * 是否包含阴影
+     * 是否显示阴影
      */
     elevated: boolean;
     /**
@@ -53,11 +53,11 @@ export declare class Chip extends ButtonBase<ChipEventMap> {
      */
     selectable: boolean;
     /**
-     * 是否为选中状态
+     * 是否已选中
      */
     selected: boolean;
     /**
-     * 是否可删除。为 `true` 时，在右侧会显示删除图标图标
+     * 是否可删除。为 `true` 时，纸片右侧会显示删除图标
      */
     deletable: boolean;
     /**
@@ -65,7 +65,7 @@ export declare class Chip extends ButtonBase<ChipEventMap> {
      */
     icon?: string;
     /**
-     * 选中状态，左侧的 Material Icons 图标名。也可以通过 `slot="selected-icon"` 设置
+     * 选中状态下左侧的 Material Icons 图标名。也可以通过 `slot="selected-icon"` 设置
      */
     selectedIcon?: string;
     /**
@@ -73,7 +73,7 @@ export declare class Chip extends ButtonBase<ChipEventMap> {
      */
     endIcon?: string;
     /**
-     * 右侧的 Material Icons 图标名。也可以通过 `slot="delete-icon"` 设置
+     * 可删除时，右侧删除图标的 Material Icons 图标名。也可以通过 `slot="delete-icon"` 设置
      */
     deleteIcon?: string;
     private readonly rippleRef;

package/components/chip/index.js

@@ -25,36 +25,36 @@ import { style } from './style.js';
  * @event change - 选中状态变更时触发
  * @event delete - 点击删除图标时触发
  *
- * @slot - 文本
+ * @slot - 纸片文本
  * @slot icon - 左侧元素
  * @slot end-icon - 右侧元素
- * @slot selected-icon - 选中状态的左侧元素
- * @slot delete-icon - 可删除时，右侧的删除元素
+ * @slot selected-icon - 选中状态下的左侧元素
+ * @slot delete-icon - 可删除时的右侧删除元素
  *
- * @csspart button - 内部的 `button` 或 `a` 元素
- * @csspart label - 文本
+ * @csspart button - 内部的 `<button>` 或 `<a>` 元素
+ * @csspart label - 纸片文本
  * @csspart icon - 左侧图标
  * @csspart end-icon - 右侧图标
- * @csspart selected-icon - 选中状态的左侧图标
- * @csspart delete-icon - 可删除时，右侧的删除图标
+ * @csspart selected-icon - 选中状态下的左侧图标
+ * @csspart delete-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 Chip = class Chip extends ButtonBase {
     constructor() {
         super();
         /**
-         * 纸片形状。可选值为：
+         * 纸片的形状。可选值包括：
          *
-         * * `assist`：用于显示和当前上下文相关的辅助操作。例如在点餐页面，提供分享，收藏等功能
-         * * `filter`：用于对内容进行筛选。例如在搜索结果页，对搜索结果进行过滤
-         * * `input`：用于表示用户输入的信息片段。例如 Gmail 中“收件人”字段中的联系人
-         * * `suggestion`：用于提供动态生成的推荐信息，以简化用户操作。例如在聊天应用中猜测用户可能想发送的信息，供用户选择
+         * * `assist`：用于显示与当前上下文相关的辅助操作，如在点餐页面提供分享、收藏等功能
+         * * `filter`：用于对内容进行筛选，如在搜索结果页过滤搜索结果
+         * * `input`：用于表示用户输入的信息片段，如在 Gmail 的“收件人”字段中的联系人
+         * * `suggestion`：用于提供动态生成的推荐信息，以简化用户操作，如在聊天应用中预测用户可能想发送的信息
          */
         this.variant = 'assist';
         /**
-         * 是否包含阴影
+         * 是否显示阴影
          */
         this.elevated = false;
         /**
@@ -62,11 +62,11 @@ let Chip = class Chip extends ButtonBase {
          */
         this.selectable = false;
         /**
-         * 是否为选中状态
+         * 是否已选中
          */
         this.selected = false;
         /**
-         * 是否可删除。为 `true` 时，在右侧会显示删除图标图标
+         * 是否可删除。为 `true` 时，纸片右侧会显示删除图标
          */
         this.deletable = false;
         this.rippleRef = createRef();

package/components/circular-progress/index.d.ts

@@ -10,11 +10,11 @@ import type { CSSResultGroup, TemplateResult } from 'lit';
 export declare class CircularProgress extends MduiElement<CircularProgressEventMap> {
     static styles: CSSResultGroup;
     /**
-     * 进度指示器的最大值，默认为 1
+     * 进度指示器的最大值。默认为 `1`
      */
     max: number;
     /**
-     * 进度指示器的当前值。若未指定该值，则为不确定状态
+     * 进度指示器的当前值。如果未指定该值，则显示为不确定状态
      */
     value?: number;
     protected render(): TemplateResult;

package/components/circular-progress/index.js

@@ -17,7 +17,7 @@ let CircularProgress = class CircularProgress extends MduiElement {
     constructor() {
         super(...arguments);
         /**
-         * 进度指示器的最大值，默认为 1
+         * 进度指示器的最大值。默认为 `1`
          */
         this.max = 1;
     }

package/components/collapse/collapse-item.d.ts

@@ -3,7 +3,7 @@ import { MduiElement } from '@mdui/shared/base/mdui-element.js';
 import type { JQ } from '@mdui/jq/shared/core.js';
 import type { CSSResultGroup, TemplateResult, PropertyValues } from 'lit';
 /**
- * @summary 折叠面板项组件。需与 `<mdui-collapse>` 组件配合使用
+ * @summary 折叠面板项组件，需配合 `<mdui-collapse>` 组件使用
  *
  * ```html
  * <mdui-collapse>
@@ -26,15 +26,15 @@ import type { CSSResultGroup, TemplateResult, PropertyValues } from 'lit';
 export declare class CollapseItem extends MduiElement<CollapseItemEventMap> {
     static styles: CSSResultGroup;
     /**
-     * 该折叠面板项的值
+     * 此折叠面板项的值
      */
     value?: string;
     /**
-     * 该折叠面板项的头部文本
+     * 此折叠面板项的头部文本
      */
     header?: string;
     /**
-     * 是否禁用该折叠面板项
+     * 是否禁用此折叠面板项
      */
     disabled: boolean;
     /**

package/components/collapse/collapse-item.js

@@ -12,7 +12,7 @@ import { uniqueId } from '@mdui/shared/helpers/uniqueId.js';
 import { componentStyle } from '@mdui/shared/lit-styles/component-style.js';
 import { collapseItemStyle } from './collapse-item-style.js';
 /**
- * @summary 折叠面板项组件。需与 `<mdui-collapse>` 组件配合使用
+ * @summary 折叠面板项组件，需配合 `<mdui-collapse>` 组件使用
  *
  * ```html
  * <mdui-collapse>
@@ -36,7 +36,7 @@ let CollapseItem = class CollapseItem extends MduiElement {
     constructor() {
         super(...arguments);
         /**
-         * 是否禁用该折叠面板项
+         * 是否禁用此折叠面板项
          */
         this.disabled = false;
         /**

package/components/collapse/collapse.d.ts

@@ -2,7 +2,7 @@ import '@mdui/jq/methods/is.js';
 import { MduiElement } from '@mdui/shared/base/mdui-element.js';
 import type { CSSResultGroup, TemplateResult } from 'lit';
 /**
- * @summary 折叠面板组件。需与 `<mdui-collapse-item>` 组件配合使用
+ * @summary 折叠面板组件，需配合 `<mdui-collapse-item>` 组件使用
  *
  * ```html
  * <mdui-collapse>
@@ -11,27 +11,24 @@ import type { CSSResultGroup, TemplateResult } from 'lit';
  * </mdui-collapse>
  * ```
  *
- * @event change - 当前打开的折叠面板项改变时触发
+ * @event change - 当前展开的折叠面板项变化时触发
  *
  * @slot - `<mdui-collapse-item>` 组件
  */
 export declare class Collapse extends MduiElement<CollapseEventMap> {
     static styles: CSSResultGroup;
     /**
-     * 是否为手风琴模式
+     * 是否启用手风琴模式
      */
     accordion: boolean;
     /**
-     * 当前打开的 `<mdui-collapse-item>` 的值
+     * 当前展开的 `<mdui-collapse-item>` 的值
      *
-     * Note:
-     * 该属性的 HTML 属性始终为字符串，且仅在 `accordion` 为 `true` 时可以设置初始值；
-     * 该属性的 JavaScript 属性值在 `accordion` 为 `true` 时为字符串、在 `accordion` 为 `false` 时为字符串数组。
-     * 所以，在 `accordion` 为 `false` 时，如果要修改该值，只能通过修改 JavaScript 属性值实现。
+     * **Note**：该属性的 HTML 属性始终为字符串，只有在 `accordion` 为 `true` 时，才能设置初始值；该属性的 JavaScript 属性值在 `accordion` 为 `true` 时为字符串，在 `accordion` 为 `false` 时为字符串数组。因此，当 `accordion` 为 `false` 时，只能通过修改 JavaScript 属性值来改变此值。
      */
     value?: string | string[];
     /**
-     * 是否禁用该折叠面板
+     * 是否禁用此折叠面板
      */
     disabled: boolean;
     private activeKeys;

package/components/collapse/collapse.js

@@ -12,7 +12,7 @@ import { booleanConverter } from '@mdui/shared/helpers/decorator.js';
 import { componentStyle } from '@mdui/shared/lit-styles/component-style.js';
 import { collapseStyle } from './collapse-style.js';
 /**
- * @summary 折叠面板组件。需与 `<mdui-collapse-item>` 组件配合使用
+ * @summary 折叠面板组件，需配合 `<mdui-collapse-item>` 组件使用
  *
  * ```html
  * <mdui-collapse>
@@ -21,7 +21,7 @@ import { collapseStyle } from './collapse-style.js';
  * </mdui-collapse>
  * ```
  *
- * @event change - 当前打开的折叠面板项改变时触发
+ * @event change - 当前展开的折叠面板项变化时触发
  *
  * @slot - `<mdui-collapse-item>` 组件
  */
@@ -29,11 +29,11 @@ let Collapse = class Collapse extends MduiElement {
     constructor() {
         super(...arguments);
         /**
-         * 是否为手风琴模式
+         * 是否启用手风琴模式
          */
         this.accordion = false;
         /**
-         * 是否禁用该折叠面板
+         * 是否禁用此折叠面板
          */
         this.disabled = false;
         // 因为 collapse-item 的 value 可能会重复，所以在每个 collapse-item 元素上都添加了一个唯一的 key，通过 activeKey 来记录激活状态的 key

package/components/dialog/index.d.ts

@@ -8,10 +8,10 @@ import type { CSSResultGroup, PropertyValues, TemplateResult } from 'lit';
  * <mdui-dialog>content</mdui-dialog>
  * ```
  *
- * @event open - 在对话框打开之前触发。可以通过调用 `event.preventDefault()` 阻止对话框打开
- * @event opened - 在对话框打开之后触发
- * @event close - 在对话框关闭之前触发。可以通过调用 `event.preventDefault()` 阻止对话框关闭
- * @event closed - 在对话框关闭之后触发
+ * @event open - 对话框开始打开时触发。可以通过调用 `event.preventDefault()` 阻止对话框打开
+ * @event opened - 对话框打开动画完成后触发
+ * @event close - 对话框开始关闭时触发。可以通过调用 `event.preventDefault()` 阻止对话框关闭
+ * @event closed - 对话框关闭动画完成后触发
  * @event overlay-click - 点击遮罩层时触发
  *
  * @slot header - 顶部元素，默认包含 `icon` slot 和 `headline` slot
@@ -23,15 +23,15 @@ import type { CSSResultGroup, PropertyValues, TemplateResult } from 'lit';
  *
  * @csspart overlay - 遮罩层
  * @csspart panel - 对话框容器
- * @csspart header - 对话框 header 部分，其中包含了 icon 和 headline
- * @csspart icon - 顶部的图标，位于 header 中
- * @csspart headline - 顶部的标题，位于 header 中
- * @csspart body - 对话框的 body 部分
+ * @csspart header - 对话框 header 部分，包含 icon 和 headline
+ * @csspart icon - 顶部图标，位于 header 中
+ * @csspart headline - 顶部标题，位于 header 中
+ * @csspart body - 对话框 body 部分
  * @csspart description - 副文本部分，位于 body 中
  * @csspart action - 底部操作按钮
  *
- * @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 Dialog extends MduiElement<DialogEventMap> {
     static styles: CSSResultGroup;
@@ -52,15 +52,15 @@ export declare class Dialog extends MduiElement<DialogEventMap> {
      */
     open: boolean;
     /**
-     * 是否为全屏对话框
+     * 是否全屏显示对话框
      */
     fullscreen: boolean;
     /**
-     * 是否在按下 ESC 键时，关闭对话框
+     * 是否允许按下 ESC 键关闭对话框
      */
     closeOnEsc: boolean;
     /**
-     * 是否在点击遮罩时，关闭对话框
+     * 是否允许点击遮罩层关闭对话框
      */
     closeOnOverlayClick: boolean;
     /**