# ModalProgress

命令式组件，扩展 [antd Modal](https://antdv.com/components/modal-cn#modal-method)，弹框进度条展示进程

# 何时使用

用户接口请求返回时间较长的场景

# Usage

## ”假“进度条

```ts
import { ModalProgress } from '@kt/unity-components';
import { Status } from '@kt/unity-components/src/ModalProgress';

const state = reactive({
  status: 'normal' as Status
});
// 或者
// const status = ref<Status>('normal');

const foo = async () => {
  state.status = 'loading';
  ModalProgress({
    // 默认可不传递，表示一个虚拟的进度条
    fake: true,
    // 当使用 ref 声明时，() => status.value,
    status: () => state.status,
    // 状态成功之后回调，这里的回调会在 modal 关闭之后执行
    onSuccess() {
      console.log('onSuccess :>> ', 'onSuccess');
      router.push({ path: '/' });
    },
    onError() {
      console.log('onError :>> ', 'onError');
    }
  });
  const { code } = await request.get('foo/bar');
  if (code === 2000) {
    state.status = 'success';
  } else {
    state.status = 'error';
  }
};
```

> tip:假进度条下，内部会随机递增进度条，且保持 <=98。当状态为 success 时候，会赋值为 100

## 真实进度条

一般是在上传文件时

```ts
import { ModalProgress } from '@kt/unity-components';
import { Status } from '@kt/unity-components/src/ModalProgress';

const state = reactive({
  percent: 0,
  status: 'normal' as Status
});

const foo = async () => {
  state.percent = 0;
  state.status = 'loading';
  ModalProgress({
    // fake = false，表示 percent 由外部控制
    fake: false,
    tips: {
      loading: '文件上传中，请稍后...',
      success: '文件上传成功',
      error: '文件上传失败，请重试'
    },
    status: () => state.status,
    percent: () => state.percent,
    onSuccess() {
      console.log('onSuccess :>> ', 'onSuccess');
    },
    onError() {
      console.log('onError :>> ', 'onError');
    }
  });

  const data = new FormData();
  data.append('file', file);
  const { code } = await request.get('foo/bar', data, {
    onUploadProgress(e) {
      // 真实进度控制
      state.percent = parseInt((e.loaded / e.total) * 100 + '');
    }
  });

  if (code === 2000) {
    state.status = 'success';
  } else {
    state.status = 'error';
  }
};
```

# API

ModalProgress()

ModalProgress 为一个函数，参数为 object，具体属性如下（扩展属性）：

> tip：扩展了 antd Modal，所以 Modal 的属性都可以使用，[参考](https://antdv.com/components/modal-cn#Modal-method)

| 参数             | 说明                                                                                         | 类型                                                                                                                         | 默认值 |
| ---------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------ |
| fake             | 是否虚拟进度条                                                                               | boolean                                                                                                                      | true   |
| percent          | 进度百分比 0-100，<br>传入一个 getter 函数，保持响应性，当 fake 为 true 时，percent 无效     | ()=>number                                                                                                                   | ()=>0  |
| status           | 状态，<br>传入一个 getter 函数，保持响应性                                                   | ()=>'normal' \| 'loading' \| 'success' \| 'error'                                                                            | -      |
| tips             | 提示                                                                                         | [tips](https://ktcode.keytop.cn/front-framework/kt/unity/-/blob/master/packages/components/src/ModalProgress/README.md#tips) | -      |
| successAutoClose | status 为 success 是否自动关闭，<br>为 false 时，closable 不能为 false，否则用户没有关闭渠道 | boolean                                                                                                                      | true   |
| errorAutoClose   | status 为 error 是否自动关闭，<br>为 false 时，closable 不能为 false，否则用户没有关闭渠道   | boolean                                                                                                                      | true   |
| onSuccess        | 成功时回调(1.在成功状态 && 弹框被关闭之后触发，2.当弹框被提前关闭了，状态改变成功时依然触发) | ()=>void                                                                                                                     | -      |
| onError          | 失败时回调(1.在失败状态 && 弹框被关闭之后触发，2.当弹框被提前关闭了，状态改变失败时依然触发) | ()=>void                                                                                                                     | -      |

## tips

```ts
{
  normal?: string; // ''
  loading?: string; // '加载中，请稍后...',
  success?: string; // ''
  error?: string; // '发生错误，请稍后再试'
}
```

# 注意

- 按钮触发请求接口，保持按钮的状态和 ModalProgress 的状态一致，主要用来避免弹框被提前关闭的可能

```html
<a-button :loading="state.status === 'loading'">保存</a-button>
```

# 蓝湖参考

[蓝湖参考](https://lanhuapp.com/web/#/item/project/detailDetach?pid=bd06380a-47e4-4580-a1f2-5ddc62bbd6b1&image_id=96903e63-86bd-44b5-b58e-b80fd5b75608&project_id=bd06380a-47e4-4580-a1f2-5ddc62bbd6b1&fromEditor=true&type=image)
