[new feature] List 考虑错误情况，增加 error-text 属性 #2567 (#2568)

packages/list/demo/index.vue

@@ -1,7 +1,15 @@
 <template>
   <demo-section>
     <demo-block :title="$t('basicUsage')">
-      <p class="page-desc">{{ $t('text') }}</p>
+      <div class="page-desc">
+        <p class="page-desc--text">{{ $t('text') }}</p>
+        <van-checkbox
+          class="page-desc--option"
+          v-model="loadedError"
+        >
+          模拟加载失败
+        </van-checkbox>
+      </div>
       <van-pull-refresh
         v-model="refreshing"
         @refresh="onRefresh"
@@ -9,7 +17,9 @@
         <van-list
           v-model="loading"
           :finished="finished"
+          :error.sync="error"
           :finished-text="$t('finishedText')"
+          :error-text="$t('errorText')"
           @load="onLoad"
         >
           <van-cell
@@ -28,11 +38,13 @@ export default {
   i18n: {
     'zh-CN': {
       text: '当即将滚动到元素底部时，会自动加载更多',
-      finishedText: '没有更多了'
+      finishedText: '没有更多了',
+      errorText: '请求失败，点击重新加载...'
     },
     'en-US': {
       text: 'This list will load items will scroll to bottom.',
-      finishedText: 'Finished'
+      finishedText: 'Finished',
+      errorText: 'Request failed. Click to reload...'
     }
   },
 
@@ -41,23 +53,35 @@ export default {
       list: [],
       refreshing: false,
       loading: false,
-      finished: false
+      error: false,
+      finished: false,
+      loadedError: false
     };
   },
 
   methods: {
     onLoad() {
-      setTimeout(() => {
-        for (let i = 0; i < 10; i++) {
-          const text = this.list.length + 1;
-          this.list.push(text < 10 ? '0' + text : text);
-        }
-        this.loading = false;
+      if (this.loadedError) {
+        setTimeout(() => {
+          fetch('http://www.baidu.com').then(res => {
+          }).catch(err => {
+            this.loading = false;
+            this.error = true;
+          });
+        }, 500);
+      } else {
+        setTimeout(() => {
+          for (let i = 0; i < 10; i++) {
+            const text = this.list.length + 1;
+            this.list.push(text < 10 ? '0' + text : text);
+          }
+          this.loading = false;
 
-        if (this.list.length >= 40) {
-          this.finished = true;
-        }
-      }, 500);
+          if (this.list.length >= 40) {
+            this.finished = true;
+          }
+        }, 500);
+      }
     },
 
     onRefresh() {
@@ -82,10 +106,22 @@ export default {
 
   .page-desc {
     padding: 5px 0;
-    line-height: 1.4;
+    margin: 0;
     font-size: 14px;
     text-align: center;
     color: @gray-darker;
+
+    &--text {
+      margin: 0;
+    }
+
+    &--option {
+      margin: 12px;
+    }
+  }
+
+  .van-checkbox__label {
+    color: @gray-darker;
   }
 }
 </style>

packages/list/en-US.md

@@ -16,7 +16,9 @@ Vue.use(List);
 <van-list
   v-model="loading"
   :finished="finished"
+  :error.sync="error"
   finished-text="Finished"
+  error-text="Request failed. Click to reload..."
   @load="onLoad"
 >
   <van-cell
@@ -34,6 +36,7 @@ export default {
       list: [],
       loading: false,
       finished: false
+      error: false
     };
   },
 
@@ -45,6 +48,9 @@ export default {
         }
         this.loading = false;
 
+        // when error loaded:
+        // this.error = true;
+
         if (this.list.length >= 40) {
           this.finished = true;
         }
@@ -60,9 +66,11 @@ export default {
 |------|------|------|------|
 | loading | Whether to show loading info，the `load` event will not be triggered when loading | `Boolean` | `false` |
 | finished | Whether loading is finished，the `load` event will not be triggered when finished | `Boolean` | `false` |
+| error | Whether loading is error，the `load` event will be triggered only when error text clicked, the `sync` modifier is needed | `Boolean` | `false` |
 | offset | The load event will be triggered when the distance between the scrollbar and the bottom is less than offset | `Number` | `300` |
 | loading-text | Loading text | `String` | `Loading...` |
 | finished-text | Finished text | `String` | - |
+| error-text | Error loaded text | `String` | - |
 | immediate-check | Whether to check loading position immediately after mounted | `Boolean` | `true` |
 
 ### Event

packages/list/index.js

@@ -13,8 +13,10 @@ export default sfc({
   props: {
     loading: Boolean,
     finished: Boolean,
+    error: Boolean,
     loadingText: String,
     finishedText: String,
+    errorText: String,
     immediateCheck: {
       type: Boolean,
       default: true
@@ -58,7 +60,7 @@ export default sfc({
 
   methods: {
     check() {
-      if (this.loading || this.finished) {
+      if (this.loading || this.finished || this.error) {
         return;
       }
 
@@ -96,6 +98,11 @@ export default sfc({
       }
     },
 
+    clickErrorText() {
+      this.$emit('update:error', false);
+      this.$nextTick(this.check);
+    },
+
     handler(bind) {
       /* istanbul ignore else */
       if (this.binded !== bind) {
@@ -120,6 +127,9 @@ export default sfc({
         {this.finished && this.finishedText && (
           <div class={bem('finished-text')}>{this.finishedText}</div>
         )}
+        {this.error && this.errorText && (
+          <div onClick={this.clickErrorText} class={bem('error-text')}>{this.errorText}</div>
+        )}
       </div>
     );
   }

packages/list/index.less

@@ -2,7 +2,8 @@
 
 .van-list {
   &__loading-text,
-  &__finished-text {
+  &__finished-text,
+  &__error-text {
     color: @list-text-color;
     font-size: @list-text-font-size;
     line-height: @list-text-line-height;

packages/list/test/__snapshots__/demo.spec.js.snap

@@ -3,7 +3,15 @@
 exports[`renders demo correctly 1`] = `
 <div>
   <div>
-    <p class="page-desc">当即将滚动到元素底部时，会自动加载更多</p>
+    <div class="page-desc">
+      <p class="page-desc--text">当即将滚动到元素底部时，会自动加载更多</p>
+      <div class="page-desc--option van-checkbox">
+        <div class="van-checkbox__icon van-checkbox__icon--round"><i class="van-icon van-icon-success" style="color:undefined;font-size:undefined;">
+            <!----></i></div><span class="van-checkbox__label">
+        模拟加载失败
+      </span>
+      </div>
+    </div>
     <div class="van-pull-refresh">
       <div class="van-pull-refresh__track" style="transition:0ms;transform:translate3d(0,0px, 0);">
         <div class="van-pull-refresh__head">

packages/list/test/index.spec.js

@@ -29,6 +29,35 @@ test('load event', async () => {
   wrapper.destroy();
 });
 
+test('error loaded, click error-text and reload', async () => {
+  const wrapper = mount(List, {
+    propsData: {
+      errorText: 'Request failed. Click to reload...',
+      error: true
+    }
+  });
+
+  mockOffsetParent(wrapper.vm.$el);
+
+  await later();
+
+  expect(wrapper.emitted('load')).toBeFalsy();
+  expect(wrapper.emitted('input')).toBeFalsy();
+
+  // 模拟点击error-text的行为
+  wrapper.setProps({
+    error: false
+  });
+  wrapper.vm.$emit('input', true);
+  wrapper.vm.$emit('load');
+
+  expect(wrapper.vm.$props.error).toBeFalsy();
+  expect(wrapper.emitted('load')).toBeTruthy();
+  expect(wrapper.emitted('input')).toBeTruthy();
+
+  wrapper.destroy();
+});
+
 test('finished', async () => {
   const wrapper = mount(List, {
     propsData: {

packages/list/zh-CN.md

@@ -12,13 +12,15 @@ Vue.use(List);
 
 #### 基础用法
 
-List 组件通过`loading`和`finished`两个变量控制加载状态，当组件滚动到底部时，会触发`load`事件并将`loading`设置成`true`。此时可以发起异步操作并更新数据，数据更新完毕后，将`loading`设置成`false`即可。若数据已全部加载完毕，则直接将`finished`设置成`true`即可。
+List 组件通过`loading`、`finished`和`error`三个变量控制加载状态，当组件滚动到底部时，会触发`load`事件并将`loading`设置成`true`。此时可以发起异步操作并更新数据，数据更新完毕后，将`loading`设置成`false`即可。若数据已全部加载完毕，则直接将`finished`设置成`true`即可。若数据加载失败，将`error`设置成`true`，出现错误提示，用户点击错误提示，重新请求。
 
 ```html
 <van-list
   v-model="loading"
   :finished="finished"
+  :error.sync="error"
   finished-text="没有更多了"
+  error-text="请求失败，点击重新加载..."
   @load="onLoad"
 >
   <van-cell
@@ -35,7 +37,8 @@ export default {
     return {
       list: [],
       loading: false,
-      finished: false
+      finished: false,
+      error: false
     };
   },
 
@@ -49,6 +52,9 @@ export default {
         // 加载状态结束
         this.loading = false;
 
+        // 当请求错误时
+        // this.error = true;
+
         // 数据全部加载完成
         if (this.list.length >= 40) {
           this.finished = true;
@@ -65,9 +71,11 @@ export default {
 |------|------|------|------|------|
 | loading | 是否处于加载状态，加载过程中不触发`load`事件 | `Boolean` | `false` | - |
 | finished | 是否已加载完成，加载完成后不再触发`load`事件 | `Boolean` | `false` | - |
+| error | 是否加载失败，加载失败后只能通过点击错误提示重新加载`load`事件，必须使用`sync`修饰符 | `Boolean` | `false` | - |
 | offset | 滚动条与底部距离小于 offset 时触发`load`事件 | `Number` | `300` | - |
 | loading-text | 加载过程中的提示文案 | `String` | `加载中...` | 1.1.1 |
 | finished-text | 加载完成后的提示文案 | `String` | - | 1.4.7 |
+| error-text | 加载失败后的提示文案 | `String` | - | - |
 | immediate-check | 是否在初始化时立即执行滚动位置检查 | `Boolean` | `true` | - |
 
 ### Event