m8-mcp-server 1.0.0

package/dist/data/m8mpdoc-develop/009-UI/347/273/204/344/273/266/045-toast/350/275/273/346/217/220/347/244/272.md

@@ -0,0 +1,429 @@
+# 组件使用
+
+## toast 轻提示
+
+### 介绍
+
+-   在页面中间弹出黑色半透明提示，用于消息通知、加载提示、操作结果提示等场景。
+
+::: ifdef M83
+
+-   `v8.3.11`开始支持 weex 端使用
+
+::: endif
+
+### 引入
+
+手动引入时的引入路径：
+
+```js
+import Toast from '@components/em-toast/index.js';
+```
+
+Toast 作为全局函数，跨端框架为其提供了全局注入的功能，使用 Toast 函数时，框架会自动引入上述路径，所以在跨端框架中使用时，不必再手动引入。
+
+### 代码演示
+
+#### 文字提示
+
+通过函数调用 toast 组件时，需要手动在页面上放一个 toast 节点，且提供一个 ref 方便函数进行查找。
+
+::: ifdef M83
+该 ref 值默认为 emToast
+::: endif
+
+::: ifdef M84
+该 ref 值默认为 emToastRef
+::: endif
+
+::: ifdef M83
+
+```html
+<em-toast ref="emToast"></em-toast>
+```
+
+```js
+Toast('提示内容');
+```
+
+::: endif
+
+::: ifdef M84
+
+```html
+<em-toast ref="emToastRef"></em-toast>
+```
+
+```js
+import { ref } from 'vue';
+
+const emToastRef = ref(null);
+Toast('提示内容');
+defineExpose({
+    emToastRef
+});
+```
+
+::: endif
+
+#### 加载提示
+
+使用 `Toast.loading` 方法展示加载提示，通过 `forbidClick` 属性可以禁用背景点击。
+
+::: ifdef M83
+
+```html
+<em-toast ref="emToast"></em-toast>
+```
+
+```js
+Toast.loading({
+    message: '加载中...',
+    forbidClick: true
+});
+```
+
+::: endif
+
+::: ifdef M84
+
+```html
+<em-toast ref="emToastRef"></em-toast>
+```
+
+```js
+import { ref } from 'vue';
+
+const emToastRef = ref(null);
+Toast.loading({
+    message: '加载中...',
+    forbidClick: true
+});
+defineExpose({
+    emToastRef
+});
+```
+
+::: endif
+
+#### 成功/失败提示
+
+使用 `Toast.success` 方法展示成功提示，使用 `Toast.fail` 方法展示失败提示。
+
+::: ifdef M83
+
+```html
+<em-toast ref="emToast"></em-toast>
+```
+
+```js
+Toast.success('成功文案');
+Toast.fail('失败文案');
+```
+
+::: endif
+
+::: ifdef M84
+
+```html
+<em-toast ref="emToastRef"></em-toast>
+```
+
+```js
+import { ref } from 'vue';
+
+const emToastRef = ref(null);
+Toast.success('成功文案');
+Toast.fail('失败文案');
+defineExpose({
+    emToastRef
+});
+```
+
+::: endif
+
+#### 自定义图标
+
+通过 `icon` 选项可以自定义图标，支持传入图标名称或图片链接，通过`loadingType` 属性可以自定义加载图标类型。
+
+::: ifdef M83
+
+```html
+<em-toast ref="emToast"></em-toast>
+```
+
+```js
+Toast({
+    message: '自定义图标',
+    icon: 'like-o'
+});
+
+Toast({
+    message: '自定义图片',
+    icon: 'https://img.yzcdn.cn/vant/logo.png'
+});
+
+// 自定义加载图标
+Toast.loading({
+    message: '加载中...',
+    loadingType: 'spinner'
+});
+```
+
+::: endif
+
+::: ifdef M84
+
+```html
+<em-toast ref="emToastRef"></em-toast>
+```
+
+```js
+import { ref } from 'vue';
+
+const emToastRef = ref(null);
+Toast({
+    message: '自定义图标',
+    icon: 'like-o'
+});
+
+Toast({
+    message: '自定义图片',
+    icon: 'https://img.yzcdn.cn/vant/logo.png'
+});
+
+// 自定义加载图标
+Toast.loading({
+    message: '加载中...',
+    loadingType: 'spinner'
+});
+defineExpose({
+    emToastRef
+});
+```
+
+::: endif
+
+#### 动态更新提示
+
+执行 `Toast` 方法时会返回对应的 `Toast` 实例，通过修改实例上的 `message` 属性可以实现动态更新提示的效果。
+
+::: ifdef M83
+
+```html
+<em-toast ref="emToast"></em-toast>
+```
+
+```js
+const toast = Toast.loading({
+    duration: 0, // 持续展示 toast
+    forbidClick: true,
+    message: '倒计时 3 秒'
+});
+
+let second = 3;
+let times = () => {
+    setTimeout(() => {
+        second--;
+        if (second > 0) {
+            toast.message = `倒计时 ${second} 秒`;
+            times();
+        } else {
+            // 关闭 toast
+            Toast.clear();
+        }
+    }, 1000);
+};
+
+times();
+```
+
+::: endif
+
+::: ifdef M84
+
+```html
+<em-toast ref="emToastRef"></em-toast>
+```
+
+```js
+import { ref } from 'vue';
+
+const emToastRef = ref(null);
+const toast = Toast.loading({
+    duration: 0, // 持续展示 toast
+    forbidClick: true,
+    message: '倒计时 3 秒'
+});
+
+let second = 3;
+let times = () => {
+    setTimeout(() => {
+        second--;
+        if (second > 0) {
+            toast.message = `倒计时 ${second} 秒`;
+            times();
+        } else {
+            // 关闭 toast
+            Toast.clear();
+        }
+    }, 1000);
+};
+
+times();
+defineExpose({
+    emToastRef
+});
+```
+
+::: endif
+
+#### 展示多个提示
+
+若需要展示多个 toast，可以在页面上放置多个 toast 节点，通过 selector 传入不同节点的 ref。
+
+::: ifdef M83
+
+```html
+<em-toast ref="emToast"></em-toast>
+<em-toast ref="other"></em-toast>
+```
+
+```js
+// 使用了默认的emToast节点
+Toast('一个提示');
+// 使用了手动添加的 other 节点
+Toast({
+    selector: 'other',
+    message: '另一个提示',
+    position: 'bottom'
+});
+```
+
+::: endif
+
+::: ifdef M84
+
+```html
+<em-toast ref="emToastRef"></em-toast>
+<em-toast ref="other"></em-toast>
+```
+
+```js
+import { ref } from 'vue';
+
+const emToastRef = ref(null);
+const other = ref(null);
+
+// 使用了默认的emToast节点
+Toast('一个提示');
+// 使用了手动添加的 other 节点
+Toast({
+    selector: 'other',
+    message: '另一个提示',
+    position: 'bottom'
+});
+
+defineExpose({
+    emToastRef,
+    other
+});
+```
+
+::: endif
+
+#### 修改默认配置
+
+通过`Toast.setDefaultOptions`函数可以全局修改 `Toast` 的默认配置。
+
+```js
+// 将所有 Toast 的展示时长设置为 2000 毫秒
+Toast.setDefaultOptions({ duration: 2000 });
+
+// 将所有 loading Toast 设置为背景不可点击
+Toast.setDefaultOptions('loading', { forbidClick: true });
+
+// 重置所有 Toast 的默认配置
+Toast.resetDefaultOptions();
+
+// 重置 loading Toast 的默认配置
+Toast.resetDefaultOptions('loading');
+```
+
+### API
+
+#### 方法
+
+| 方法名                    |                                   说明                                    | 参数              | 返回值       |
+| :------------------------ | :-----------------------------------------------------------------------: | :---------------- | :----------- |
+| Toast                     |                                 展示提示                                  | options / message | `toast` 实例 |
+| Toast.loading             |                               展示加载提示                                | options / message | `toast` 实例 |
+| Toast.success             |                               展示成功提示                                | options / message | `toast` 实例 |
+| Toast.fail                |                               展示失败提示                                | options / message | `toast` 实例 |
+| Toast.clear               |                            关闭页面上所有提示                             |                   | `void`       |
+| Toast.setDefaultOptions   |  修改默认配置，对所有 `Toast` 生效。传入 type 可以修改指定类型的默认配置  | type / options    | `void`       |
+| Toast.resetDefaultOptions | 重置默认配置，对所有 `Toast` 生效。传入 `type` 可以重置指定类型的默认配置 | type              | `void`       |
+
+#### Options
+
+| 参数                |                             说明                             | 类型     | 默认值     | ::: ifdef M83 weex 端支持 ::: endif                                                                       |
+| :------------------ | :----------------------------------------------------------: | :------- | :--------- | :-------------------------------------------------------------------------------------------------------- |
+| context             |   toast 节点上下文，传入后只在该$vm 节点下查找 toast 节点    | vue 实例 | 当前页面   | 是 ::: ifdef M83（weex 端必填项，`v8.3.11`开始可以通过`setDefaultOptions`统一设置当前`context`）::: endif |
+| selector            |          toast 节点的 ref，函数根据该 ref 进行查找           | string   | `emToast`  | 是                                                                                                        |
+| type                |        提示类型，可选值为 `loading` `success` `fail`         | string   | `text`     | 是                                                                                                        |
+| position            |                位置，可选值为 `top` `bottom`                 | string   | `middle`   | 是                                                                                                        |
+| message             |                  文本内容，支持通过`\n`换行                  | string   | `''`       | 是                                                                                                        |
+| icon                |            自定义图标，支持传入图标名称或图片链接            | string   | -          | 是                                                                                                        |
+| iconPrefix          |      图标类名前缀，同 `Icon` 组件的 `class-prefix` 属性      | string   | `van-icon` | 否                                                                                                        |
+| overlay             |                      是否显示背景遮罩层                      | boolean  | `false`    | 是                                                                                                        |
+| forbidClick         |                       是否禁止背景点击                       | boolean  | `false`    | 是                                                                                                        |
+| closeOnClick        |                       是否在点击后关闭                       | boolean  | `false`    | 是                                                                                                        |
+| closeOnClickOverlay |                    是否在点击遮罩层后关闭                    | boolean  | `false`    | 是                                                                                                        |
+| loadingType         | 加载图标类型, 可选值为 `spinner` `ball` `operation` `square` | string   | `circular` | 是                                                                                                        |
+| duration            |         展示时长(`ms`)，值为 `0` 时，`toast`不会消失         | number   | `2000`     | 是                                                                                                        |
+| onOpened            |                     完全展示后的回调函数                     | Function | -          | 是                                                                                                        |
+| onClose             |                       关闭时的回调函数                       | Function | -          | 是                                                                                                        |
+| transition          |          动画类名，等价于 `transtion` 的`name`属性           | string   | `em-fade`  | 是                                                                                                        |
+| zIndex              |                           样式层级                           | number   | `9999`     | 否                                                                                                        |
+
+注意，其中`transition`属性组件库支持的可选值有：`em-fade` `em-fade-up` `em-fade-down` `em-fade-left` `em-fade-right` `em-slide-up` `em-slide-down` `em-slide-left` `em-slide-right`
+
+#### Props
+
+这是可以放在 toast 节点上的属性，对该节点有效
+
+| 参数         |    说明    | 类型   | 默认值 | ::: ifdef M83 weex 端支持 ::: endif    |
+| :----------- | :--------: | :----- | :----- | :------------------------------------- |
+| custom-class | 自定义类名 | string | -      | 否                                     |
+| custom-style | 自定义样式 | string | -      | 是（有可能不生效，因为优先级规则不同） |
+
+::: ifdef M83
+<iframe
+ src="//app.epoint.com.cn/m8mpdoc/showcase/index.html#/modules/m8showcase/examples/em-toast"
+ frameborder=0
+ allowfullscreen class="ui-showcase-iframe">
+  </iframe>
+::: endif
+::: ifdef M84
+<iframe
+ src="//app.epoint.com.cn/m8mpdoc/showcase/m8.4/index.html#/modules/m8showcase/examples/em-toast"
+ frameborder=0
+ allowfullscreen class="ui-showcase-iframe">
+  </iframe>
+::: endif
+
+ <style>
+ .ui-showcase-iframe {
+    position: fixed;
+    right: 3.5vw;
+    top: 17%;
+    width: 375px;
+    height: 75vh;
+    box-shadow: 0 0 12px 6px #eee;
+    border-radius: 15px;
+ }
+ .main .markdown-body {
+    padding: 45px;
+    width: calc(97vw - 661px);
+}
+ </style>