Merge pull request #146 from Tencent/fix/steps/controlled

refactor(steps): turn into controlled component
Tencent · Jan 25, 2022 · a614dbb · a614dbb
2 parents c3beed2 + a3d165c
commit a614dbb
Show file tree

Hide file tree

Showing 6 changed files with 85 additions and 34 deletions.
diff --git a/example/pages/steps/steps.ts b/example/pages/steps/steps.ts
@@ -1 +1,11 @@
-Page({});
+Page({
+  data: {
+    current: 0,
+  },
+  handleChange({ detail }) {
+    console.log(detail.current);
+    this.setData({
+      current: detail.current,
+    });
+  },
+});
diff --git a/example/pages/steps/steps.wxml b/example/pages/steps/steps.wxml
@@ -4,37 +4,37 @@
 
   <t-demo title="01 类型" desc="横向可操作步骤条">
     <view class="group">
-      <t-steps class="demo-steps" current="1">
+      <t-steps class="demo-steps" defaultCurrent="1">
         <t-step title="步骤描述" />
         <t-step title="选中步骤" />
       </t-steps>
-      <t-steps class="demo-steps" current="1">
+      <t-steps class="demo-steps" bind:change="handleChange" current="{{current}}">
         <t-step title="步骤描述" content="辅助信息文字最多两行" />
         <t-step title="选中步骤" content="辅助信息文字最多两行" />
       </t-steps>
     </view>
 
     <view class="group">
-      <t-steps class="demo-steps" current="1">
+      <t-steps class="demo-steps" defaultCurrent="1">
         <t-step title="步骤描述" />
         <t-step title="选中步骤" />
         <t-step title="步骤描述" />
       </t-steps>
-      <t-steps class="demo-steps" current="1">
+      <t-steps class="demo-steps" defaultCurrent="1">
         <t-step title="步骤描述" content="辅助信息文字最多两行" />
         <t-step title="选中步骤" content="辅助信息文字最多两行" />
         <t-step title="步骤描述" content="辅助信息文字最多两行" />
       </t-steps>
     </view>
 
     <view class="group">
-      <t-steps class="demo-steps" current="1">
+      <t-steps class="demo-steps" defaultCurrent="1">
         <t-step title="步骤描述" />
         <t-step title="选中步骤" />
         <t-step title="步骤描述" />
         <t-step title="步骤描述" />
       </t-steps>
-      <t-steps class="demo-steps" current="1">
+      <t-steps class="demo-steps" defaultCurrent="1">
         <t-step title="步骤描述" content="辅助信息文字最多两行" />
         <t-step title="选中步骤" content="辅助信息文字最多两行" />
         <t-step title="步骤描述" content="辅助信息文字最多两行" />
@@ -45,12 +45,12 @@
     <view class="demo-section__desc">横向带图标可操作步骤条</view>
 
     <view class="group">
-      <t-steps class="demo-steps" current="1">
+      <t-steps class="demo-steps" defaultCurrent="1">
         <t-step title="步骤描述" icon="user"></t-step>
         <t-step title="选中步骤" icon="location" />
         <t-step title="步骤描述" icon="time" />
       </t-steps>
-      <t-steps class="demo-steps" current="1">
+      <t-steps class="demo-steps" defaultCurrent="1">
         <t-step title="步骤描述" icon="user" content="辅助信息文字最多两行"></t-step>
         <t-step title="选中步骤" icon="location" content="辅助信息文字最多两行" />
         <t-step title="步骤描述" icon="time" content="辅助信息文字最多两行" />
@@ -60,52 +60,52 @@
     <view class="demo-section__desc">横向只读步骤条</view>
 
     <view class="group">
-      <t-steps class="demo-steps" current="0" readonly="true">
+      <t-steps class="demo-steps" defaultCurrent="0" readonly="true">
         <t-step title="当前步骤" />
         <t-step title="未完成步骤" />
       </t-steps>
-      <t-steps class="demo-steps" current="0" readonly="true">
+      <t-steps class="demo-steps" defaultCurrent="0" readonly="true">
         <t-step title="当前步骤" content="辅助信息文字最多两行" />
         <t-step title="未完成步骤" content="辅助信息文字最多两行" />
       </t-steps>
-      <t-steps class="demo-steps" current="0" readonly="true">
+      <t-steps class="demo-steps" defaultCurrent="0" readonly="true">
         <t-step title="错误步骤" status="error" content="辅助信息文字最多两行" />
         <t-step title="未完成步骤" content="辅助信息文字最多两行" />
       </t-steps>
     </view>
 
     <view class="group">
-      <t-steps class="demo-steps" current="1" readonly="true">
+      <t-steps class="demo-steps" defaultCurrent="1" readonly="true">
         <t-step title="已完成步骤" />
         <t-step title="当前步骤" />
         <t-step title="未完成步骤" />
       </t-steps>
-      <t-steps class="demo-steps" current="1" readonly="true">
+      <t-steps class="demo-steps" defaultCurrent="1" readonly="true">
         <t-step title="已完成步骤" content="辅助信息文字最多两行" />
         <t-step title="当前步骤" content="辅助信息文字最多两行" />
         <t-step title="未完成步骤" content="辅助信息文字最多两行" />
       </t-steps>
-      <t-steps class="demo-steps" current="1" readonly="true">
+      <t-steps class="demo-steps" defaultCurrent="1" readonly="true">
         <t-step title="已完成步骤" content="辅助信息文字最多两行" />
         <t-step title="错误步骤" status="error" content="辅助信息文字最多两行" />
         <t-step title="未完成步骤" content="辅助信息文字最多两行" />
       </t-steps>
     </view>
 
     <view class="group">
-      <t-steps class="demo-steps" current="1" readonly="true">
+      <t-steps class="demo-steps" defaultCurrent="1" readonly="true">
         <t-step title="已完成步骤" />
         <t-step title="当前步骤" />
         <t-step title="未完成步骤" />
         <t-step title="未完成步骤" />
       </t-steps>
-      <t-steps class="demo-steps" current="1" readonly="true">
+      <t-steps class="demo-steps" defaultCurrent="1" readonly="true">
         <t-step title="已完成步骤" content="辅助信息文字最多两行" />
         <t-step title="当前步骤" content="辅助信息文字最多两行" />
         <t-step title="未完成步骤" content="辅助信息文字最多两行" />
         <t-step title="未完成步骤" content="辅助信息文字最多两行" />
       </t-steps>
-      <t-steps class="demo-steps" current="1" readonly="true">
+      <t-steps class="demo-steps" defaultCurrent="1" readonly="true">
         <t-step title="已完成步骤" content="辅助信息文字最多两行" />
         <t-step title="错误步骤" status="error" content="辅助信息文字最多两行" />
         <t-step title="未完成步骤" content="辅助信息文字最多两行" />

diff --git a/src/steps/README.md b/src/steps/README.md
@@ -25,38 +25,39 @@ isComponent: true
 <img src="https://tdesign.gtimg.com/miniprogram/readme/steps-4.png" width="375px" height="50%">
 
 ```html
-<!-- 横向可操作步骤条 -->
-<t-steps current="1">
+<t-steps defaultCurrent="1">
   <t-step title="步骤描述" />
   <t-step title="选中步骤" />
 </t-steps>
 ```
 
+#### 横向只读步骤条
+
 <img src="https://tdesign.gtimg.com/miniprogram/readme/steps-3.png" width="375px" height="50%">
 
 ```html
-<!-- 横向只读步骤条 -->
 <t-steps current="0" readonly="true">
   <t-step title="当前步骤" />
   <t-step title="未完成步骤" />
 </t-steps>
 ```
+#### 竖向只读步骤条
 
 <img src="https://tdesign.gtimg.com/miniprogram/readme/steps-2.png" width="375px" height="50%">
 
 ```html
-<!-- 竖向只读步骤条 -->
 <t-steps current="1" readonly="true" direction="vertical">
   <t-step title="已完成步骤" />
   <t-step title="当前步骤" />
   <t-step title="未完成步骤" />
 </t-steps>
 ```
 
+#### 自定义内容步骤条
+
 <img src="https://tdesign.gtimg.com/miniprogram/readme/steps-1.png" width="375px" height="50%">
 
 ```html
-<!-- 自定义内容步骤条 -->
 <t-steps current="1" readonly="true" direction="vertical">
   <t-step title="已完成步骤">
     <view slot="content">可自定义此处内容</view>
@@ -73,12 +74,34 @@ isComponent: true
 </t-steps>
 ```
 
+### 受控用法
+
+```html
+<t-steps current="{{current}}" bind:change="onChange">
+  <t-step title="步骤描述" />
+  <t-step title="选中步骤" />
+</t-steps>
+```
+
+```js
+Page({
+  data: {
+    current: 0
+  },
+  onChange(e) {
+    const { current } = e.detail;
+    this.setData({ current });
+  },
+})
+```
+
 ## API
 ### Steps Props
 
 名称 | 类型 | 默认值 | 说明 | 必传
 -- | -- | -- | -- | --
 current | String / Number | - | 当前步骤，即整个步骤条进度。默认根据步骤下标判断步骤的完成状态，当前步骤为进行中，当前步骤之前的步骤为已完成，当前步骤之后的步骤为未开始。如果每个步骤没有设置 value，current 值为步骤长度则表示所有步骤已完成。如果每个步骤设置了自定义 value，则 current = 'FINISH' 表示所有状态完成 | N
+defaultCurrent | String / Number | - | （非受控）当前步骤，即整个步骤条进度 | N
 external-classes | Array | - | 组件类名，用于设置组件外层元素元素类名。`['t-class']` | N
 layout | String | horizontal | 步骤条方向，有两种：横向和纵向。可选项：horizontal/vertical | N
 readonly | Boolean | false | 是否只读 | N

diff --git a/src/steps/props.ts b/src/steps/props.ts
@@ -12,6 +12,11 @@ const props: TdStepsProps = {
     type: String,
     optionalTypes: [Number],
   },
+  /** 当前步骤 */
+  defaultCurrent: {
+    type: null,
+    value: undefined,
+  },
   /** 组件类名，用于设置组件外层元素元素类名 */
   externalClasses: {
     type: Array,

diff --git a/src/steps/steps.ts b/src/steps/steps.ts
@@ -20,12 +20,25 @@ export default class Steps extends SuperComponent {
 
   properties = props;
 
+  controlledProps = [
+    {
+      key: 'current',
+      event: 'change',
+    },
+  ];
+
   // 组件的内部数据
   data = {
     prefix,
     classPrefix: name,
   };
 
+  observers = {
+    current() {
+      this.updateChildren();
+    },
+  };
+
   methods = {
     updateChildren() {
       const items = this.getRelationNodes('./step-item');
@@ -44,15 +57,7 @@ export default class Steps extends SuperComponent {
       }
       if (!this.data.readonly) {
         const preIndex = this.data.current;
-        this.setData(
-          {
-            current: index,
-          },
-          () => {
-            this.updateChildren();
-          },
-        );
-        this.triggerEvent('change', {
+        this._trigger('change', {
           previous: preIndex,
           current: index,
         });

diff --git a/src/steps/type.ts b/src/steps/type.ts
@@ -15,6 +15,14 @@ export interface TdStepsProps {
     value?: string | number;
     required?: boolean;
   };
+  /**
+   * 当前步骤
+   */
+  defaultCurrent?: {
+    type: StringConstructor;
+    value?: string | number;
+    required?: boolean;
+  };
   /**
    * 组件类名，用于设置组件外层元素元素类名
    */
@@ -50,7 +58,7 @@ export interface TdStepsProps {
     value?: 'default' | 'dot';
     required?: boolean;
   };
-};
+}
 
 export interface TdStepItemProps {
   /**
@@ -96,6 +104,6 @@ export interface TdStepItemProps {
     value?: string;
     required?: boolean;
   };
-};
+}
 
 export type StepStatus = 'default' | 'process' | 'finish' | 'error';