feat(Cascader): add field-names prop (#7933)

src/cascader/README.md

@@ -147,6 +147,50 @@ export default {
 };
 ```
 
+### Custom Field Names
+
+```html
+<van-cascader
+  v-model="code"
+  title="Select Area"
+  :options="options"
+  :field-names="fieldNames"
+/>
+```
+
+```js
+import { ref } from 'vue';
+
+export default {
+  setup() {
+    const code = ref('');
+    const fieldNames = {
+      text: 'name',
+      value: 'code',
+      children: 'items',
+    };
+    const options = [
+      {
+        name: 'Zhejiang',
+        code: '330000',
+        items: [{ name: 'Hangzhou', code: '330100' }],
+      },
+      {
+        name: 'Jiangsu',
+        code: '320000',
+        items: [{ name: 'Nanjing', code: '320100' }],
+      },
+    ];
+
+    return {
+      code,
+      options,
+      fieldNames,
+    };
+  },
+};
+```
+
 ## API
 
 ### Props
@@ -159,6 +203,7 @@ export default {
 | placeholder | Placeholder of unselected tab | _string_ | `Select` |
 | active-color | Active color | _string_ | `#ee0a24` |
 | closeable | Whether to show close icon | _boolean_ | `true` |
+| field-names `v3.0.4` | Custom the fields of options | _object_ | `{ text: 'text', value: 'value', children: 'children' }` |
 
 ### Events
 

src/cascader/README.zh-CN.md

@@ -159,18 +159,65 @@ export default {
 };
 ```
 
+### 自定义字段名
+
+通过 `field-names` 属性可以自定义 `options` 里的字段名称。
+
+```html
+<van-cascader
+  v-model="code"
+  title="请选择所在地区"
+  :options="options"
+  :field-names="fieldNames"
+/>
+```
+
+```js
+import { ref } from 'vue';
+
+export default {
+  setup() {
+    const code = ref('');
+    const fieldNames = {
+      text: 'name',
+      value: 'code',
+      children: 'items',
+    };
+    const options = [
+      {
+        name: '浙江省',
+        code: '330000',
+        items: [{ name: '杭州市', code: '330100' }],
+      },
+      {
+        name: '江苏省',
+        code: '320000',
+        items: [{ name: '南京市', code: '320100' }],
+      },
+    ];
+
+    return {
+      code,
+      options,
+      fieldNames,
+    };
+  },
+};
+```
+
 ## API
 
 ### Props
 
-| 参数         | 说明               | 类型               | 默认值    |
-| ------------ | ------------------ | ------------------ | --------- |
-| title        | 顶部标题           | _string_           | -         |
-| value        | 选中项的值         | _string \| number_ | -         |
-| options      | 可选项数据源       | _Option[]_         | `[]`      |
-| placeholder  | 未选中时的提示文案 | _string_           | `请选择`  |
-| active-color | 选中状态的高亮颜色 | _string_           | `#ee0a24` |
-| closeable    | 是否显示关闭图标   | _boolean_          | `true`    |
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| title | 顶部标题 | _string_ | - |
+| value | 选中项的值 | _string \| number_ | - |
+| options | 可选项数据源 | _Option[]_ | `[]` |
+| placeholder | 未选中时的提示文案 | _string_ | `请选择` |
+| active-color | 选中状态的高亮颜色 | _string_ | `#ee0a24` |
+| closeable | 是否显示关闭图标 | _boolean_ | `true` |
+| field-names `v3.0.4` | 自定义 `options` 结构中的字段 | _object_ | `{ text: 'text', value: 'value', children: 'children' }` |
 
 ### Events
 

src/cascader/demo/index.vue

@@ -8,7 +8,7 @@
       :placeholder="t('selectArea')"
       @click="base.show = true"
     />
-    <van-popup v-model:show="base.show" round position="bottom">
+    <van-popup v-model:show="base.show" round teleport="body" position="bottom">
       <van-cascader
         v-model="base.value"
         :title="t('selectArea')"
@@ -28,7 +28,12 @@
       :placeholder="t('selectArea')"
       @click="customColor.show = true"
     />
-    <van-popup v-model:show="customColor.show" round position="bottom">
+    <van-popup
+      v-model:show="customColor.show"
+      round
+      teleport="body"
+      position="bottom"
+    >
       <van-cascader
         v-model="customColor.value"
         :title="t('selectArea')"
@@ -49,7 +54,12 @@
       :placeholder="t('selectArea')"
       @click="async.show = true"
     />
-    <van-popup v-model:show="async.show" round position="bottom">
+    <van-popup
+      v-model:show="async.show"
+      round
+      teleport="body"
+      position="bottom"
+    >
       <van-cascader
         v-model="async.value"
         :title="t('selectArea')"
@@ -60,13 +70,41 @@
       />
     </van-popup>
   </demo-block>
+
+  <demo-block card :title="t('customFieldNames')">
+    <van-field
+      v-model="customFieldNames.result"
+      is-link
+      readonly
+      :label="t('area')"
+      :placeholder="t('selectArea')"
+      @click="customFieldNames.show = true"
+    />
+    <van-popup
+      v-model:show="customFieldNames.show"
+      round
+      teleport="body"
+      position="bottom"
+      safe-area-inset-bottom
+    >
+      <van-cascader
+        v-model="customFieldNames.value"
+        :title="t('selectArea')"
+        :options="customFieldOptions"
+        :field-names="fieldNames"
+        @close="customFieldNames.show = false"
+        @finish="onFinish('customFieldNames', $event)"
+      />
+    </van-popup>
+  </demo-block>
 </template>
 
 <script>
 import zhCNOptions from './area-zh-CN';
 import enUSOptions from './area-en-US';
-import { reactive, toRefs } from 'vue';
+import { computed, reactive, toRefs } from 'vue';
 import { useTranslate } from '@demo/use-translate';
+import { deepClone } from '../../utils/deep-clone';
 
 const i18n = {
   'zh-CN': {
@@ -86,6 +124,7 @@ const i18n = {
       { text: '杭州市', value: '330100' },
       { text: '宁波市', value: '330200' },
     ],
+    customFieldNames: '自定义字段名',
   },
   'en-US': {
     area: 'Area',
@@ -104,6 +143,7 @@ const i18n = {
       { text: 'Hangzhou', value: '330100' },
       { text: 'Ningbo', value: '330200' },
     ],
+    customFieldNames: 'Custom Field Names',
   },
 };
 
@@ -127,6 +167,38 @@ export default {
         result: '',
         options: t('asyncOptions1'),
       },
+      customFieldNames: {
+        show: false,
+        value: null,
+        result: '',
+      },
+    });
+
+    const fieldNames = {
+      text: 'name',
+      value: 'code',
+      children: 'items',
+    };
+
+    const customFieldOptions = computed(() => {
+      const options = deepClone(t('options'));
+      const adjustFieldName = (item) => {
+        if ('text' in item) {
+          item.name = item.text;
+          delete item.text;
+        }
+        if ('value' in item) {
+          item.code = item.value;
+          delete item.value;
+        }
+        if ('children' in item) {
+          item.items = item.children;
+          delete item.children;
+          item.items.forEach(adjustFieldName);
+        }
+      };
+      options.forEach(adjustFieldName);
+      return options;
     });
 
     const loadDynamicOptions = ({ value }) => {
@@ -138,7 +210,10 @@ export default {
     };
 
     const onFinish = (type, { value, selectedOptions }) => {
-      const result = selectedOptions.map((option) => option.text).join('/');
+      const result = selectedOptions
+        .map((option) => option.text || option.name)
+        .join('/');
+
       state[type] = {
         ...state[type],
         show: false,
@@ -151,6 +226,8 @@ export default {
       ...toRefs(state),
       t,
       onFinish,
+      fieldNames,
+      customFieldOptions,
       loadDynamicOptions,
     };
   },

src/cascader/index.js

@@ -12,6 +12,7 @@ export default createComponent({
   props: {
     title: String,
     modelValue: [Number, String],
+    fieldNames: Object,
     placeholder: String,
     activeColor: String,
     options: {
@@ -32,17 +33,24 @@ export default createComponent({
       activeTab: 0,
     });
 
+    const { text: textKey, value: valueKey, children: childrenKey } = {
+      text: 'text',
+      value: 'value',
+      children: 'children',
+      ...props.fieldNames,
+    };
+
     const getSelectedOptionsByValue = (options, value) => {
       for (let i = 0; i < options.length; i++) {
         const option = options[i];
 
-        if (option.value === value) {
+        if (option[valueKey] === value) {
           return [option];
         }
 
-        if (option.children) {
+        if (option[childrenKey]) {
           const selectedOptions = getSelectedOptionsByValue(
-            option.children,
+            option[childrenKey],
             value
           );
           if (selectedOptions) {
@@ -69,10 +77,10 @@ export default createComponent({
             };
 
             const next = optionsCursor.filter(
-              (item) => item.value === option.value
+              (item) => item[valueKey] === option[valueKey]
             );
             if (next.length) {
-              optionsCursor = next[0].children;
+              optionsCursor = next[0][childrenKey];
             }
 
             return tab;
@@ -108,9 +116,9 @@ export default createComponent({
         state.tabs = state.tabs.slice(0, tabIndex + 1);
       }
 
-      if (option.children) {
+      if (option[childrenKey]) {
         const nextTab = {
-          options: option.children,
+          options: option[childrenKey],
           selectedOption: null,
         };
 
@@ -130,14 +138,14 @@ export default createComponent({
         .filter((item) => !!item);
 
       const eventParams = {
-        value: option.value,
+        value: option[valueKey],
         tabIndex,
         selectedOptions,
       };
-      emit('update:modelValue', option.value);
+      emit('update:modelValue', option[valueKey]);
       emit('change', eventParams);
 
-      if (!option.children) {
+      if (!option[childrenKey]) {
         emit('finish', eventParams);
       }
     };
@@ -160,7 +168,7 @@ export default createComponent({
     const renderOptions = (options, selectedOption, tabIndex) => {
       const renderOption = (option) => {
         const isSelected =
-          selectedOption && option.value === selectedOption.value;
+          selectedOption && option[valueKey] === selectedOption[valueKey];
 
         return (
           <li
@@ -170,7 +178,7 @@ export default createComponent({
               onSelect(option, tabIndex);
             }}
           >
-            <span>{option.text}</span>
+            <span>{option[textKey]}</span>
             {isSelected ? (
               <Icon name="success" class={bem('selected-icon')} />
             ) : null}
@@ -184,7 +192,7 @@ export default createComponent({
     const renderTab = (item, tabIndex) => {
       const { options, selectedOption } = item;
       const title = selectedOption
-        ? selectedOption.text
+        ? selectedOption[textKey]
         : props.placeholder || t('select');
 
       return (
@@ -219,7 +227,9 @@ export default createComponent({
       () => props.modelValue,
       (value) => {
         if (value || value === 0) {
-          const values = state.tabs.map((tab) => tab.selectedOption?.value);
+          const values = state.tabs.map(
+            (tab) => tab.selectedOption?.[valueKey]
+          );
           if (values.indexOf(value) !== -1) {
             return;
           }

src/cascader/test/__snapshots__/demo.spec.js.snap

@@ -23,10 +23,6 @@ exports[`should render demo and match snapshot 1`] = `
     <i class="van-badge__wrapper van-icon van-icon-arrow van-cell__right-icon">
     </i>
   </div>
-  <transition-stub>
-  </transition-stub>
-  <transition-stub>
-  </transition-stub>
 </div>
 <div>
   <div class="van-cell van-cell--clickable van-field"
@@ -50,10 +46,6 @@ exports[`should render demo and match snapshot 1`] = `
     <i class="van-badge__wrapper van-icon van-icon-arrow van-cell__right-icon">
     </i>
   </div>
-  <transition-stub>
-  </transition-stub>
-  <transition-stub>
-  </transition-stub>
 </div>
 <div>
   <div class="van-cell van-cell--clickable van-field"
@@ -77,9 +69,28 @@ exports[`should render demo and match snapshot 1`] = `
     <i class="van-badge__wrapper van-icon van-icon-arrow van-cell__right-icon">
     </i>
   </div>
-  <transition-stub>
-  </transition-stub>
-  <transition-stub>
-  </transition-stub>
+</div>
+<div>
+  <div class="van-cell van-cell--clickable van-field"
+       role="button"
+       tabindex="0"
+  >
+    <div class="van-cell__title van-field__label">
+      <span>
+        Area
+      </span>
+    </div>
+    <div class="van-cell__value van-field__value">
+      <div class="van-field__body">
+        <input type="text"
+               class="van-field__control"
+               readonly
+               placeholder="Select Area"
+        >
+      </div>
+    </div>
+    <i class="van-badge__wrapper van-icon van-icon-arrow van-cell__right-icon">
+    </i>
+  </div>
 </div>
 `;

src/cascader/test/index.spec.js

@@ -121,3 +121,50 @@ test('should update tabs when previous tab is clicked', async () => {
   await later();
   expect(wrapper.html()).toMatchSnapshot();
 });
+
+test('should allow to custom field names', async () => {
+  const fieldNames = {
+    text: 'name',
+    value: 'code',
+    children: 'items',
+  };
+  const options = [
+    {
+      name: 'Zhejiang',
+      code: '330000',
+      items: [{ name: 'Hangzhou', code: '330100' }],
+    },
+  ];
+  const wrapper = mount(Cascader, {
+    props: {
+      options,
+      fieldNames,
+    },
+  });
+
+  await later();
+  wrapper.find('.van-cascader__option').trigger('click');
+
+  const firstOption = options[0];
+  expect(wrapper.emitted('change')[0]).toEqual([
+    {
+      value: firstOption.code,
+      tabIndex: 0,
+      selectedOptions: [firstOption],
+    },
+  ]);
+
+  await later();
+  wrapper
+    .findAll('.van-cascader__options')[1]
+    .find('.van-cascader__option')
+    .trigger('click');
+  const secondOption = options[0].items[0];
+  expect(wrapper.emitted('change')[1]).toEqual([
+    {
+      value: secondOption.code,
+      tabIndex: 1,
+      selectedOptions: [firstOption, secondOption],
+    },
+  ]);
+});