doc: remove optionLabelProp, close #5212

Author: tangjinzhou

components/auto-complete/index.en-US.md

@@ -31,7 +31,6 @@ When there is a need for autocomplete functionality.
 | disabled | Whether disabled select | boolean | false |  |
 | dropdownMatchSelectWidth | Determine whether the dropdown menu and the select input are the same width. Default set `min-width` same as input. Will ignore when value less than select width. `false` will disable virtual scroll | boolean \| number | true |  |
 | filterOption | If true, filter options by input, if function, filter options against it. The function will receive two arguments, `inputValue` and `option`, if the function returns `true`, the option will be included in the filtered set; Otherwise, it will be excluded. | boolean or function(inputValue, option) | true |  |
-| optionLabelProp | Which prop value of option will render as content of select. | string | `children` |  |
 | placeholder | placeholder of input | string | - |  |
 | v-model:value | selected option | string\|string\[]\|{ key: string, label: string\|vNodes }\|Array<{ key: string, label: string\|vNodes }> | - |  |
 | defaultOpen | Initial open state of dropdown | boolean | - |  |
@@ -54,3 +53,31 @@ When there is a need for autocomplete functionality.
 | ------- | ------------ | ------- |
 | blur()  | remove focus |         |
 | focus() | get focus    |         |
+
+## FAQ
+
+### Part of the api in v2 are not available in v3?
+
+AutoComplete is an Input component that supports auto complete tips. As such, it should not support props like `labelInValue` that affect value display. In v2, the AutoComplete implementation can not handle the case where the `value` and `label` are identical. v3 not longer support `label` as the value input.
+
+Besides, to unify the API, `dataSource` is replaced with `options`. You can migrate with the following change:
+
+#### v2
+
+```ts
+dataSource = ['light', 'bamboo'];
+// or
+dataSource = [
+  { value: 'light', text: 'Light' },
+  { value: 'bamboo', text: 'Bamboo' },
+];
+```
+
+#### v3
+
+```ts
+options = [
+  { value: 'light', label: 'Light' },
+  { value: 'bamboo', label: 'Bamboo' },
+];
+```

components/auto-complete/index.zh-CN.md

@@ -38,7 +38,6 @@ cover: https://gw.alipayobjects.com/zos/alicdn/qtJm4yt45/AutoComplete.svg
 | disabled | 是否禁用 | boolean | false |  |
 | dropdownMatchSelectWidth | 下拉菜单和选择器同宽。默认将设置 `min-width`，当值小于选择框宽度时会被忽略。false 时会关闭虚拟滚动 | boolean \| number | true |  |
 | filterOption | 是否根据输入项进行筛选。当其为一个函数时，会接收 `inputValue` `option` 两个参数，当 `option` 符合筛选条件时，应返回 `true`，反之则返回 `false`。 | boolean or function(inputValue, option) | true |  |
-| optionLabelProp | 回填到选择框的 Option 的属性值，默认是 Option 的子元素。比如在子元素需要高亮效果时，此值可以设为 `value`。 | string | `children` |  |
 | placeholder | 输入框提示 | string \| slot | - |  |
 | v-model:value | 指定当前选中的条目 | string\|string\[]\|{ key: string, label: string\|vNodes }\|Array<{ key: string, label: string\|vNodes }> | 无 |  |
 | defaultOpen | 是否默认展开下拉菜单 | boolean | - |  |
@@ -61,3 +60,31 @@ cover: https://gw.alipayobjects.com/zos/alicdn/qtJm4yt45/AutoComplete.svg
 | ------- | -------- | ---- |
 | blur()  | 移除焦点 |
 | focus() | 获取焦点 |
+
+## FAQ
+
+### v2 的部分属性为何在 v3 中没有了？
+
+AutoComplete 组件是一个支持自动提示的 Input 组件，因而其不具有 `labelInValue` 等影响 value 展示的属性。在 v2 版本，AutoComplete 实现存在输入值如果遇到 `value` 与 `label` 相同时无法映射的问题。 v3 中不再支持 `label` 为值的输入形态。
+
+此外为了统一 API，`dataSource` 改为 `options` 你可以如下转换：
+
+#### v2
+
+```ts
+dataSource = ['light', 'bamboo'];
+// or
+dataSource = [
+  { value: 'light', text: 'Light' },
+  { value: 'bamboo', text: 'Bamboo' },
+];
+```
+
+#### v3
+
+```ts
+options = [
+  { value: 'light', label: 'Light' },
+  { value: 'bamboo', label: 'Bamboo' },
+];
+```

site/src/vueDocs/migration-v3.en-US.md

@@ -41,6 +41,11 @@ Major updates after the 3.0 version refactoring include `Tree` `TreeSelect` `Dat
   - Added virtual scrolling, discarded using `a-tree-node` `a-tree-select-node` to build nodes, using `treeData` property instead to improve component performance.
   - Deprecated `scopedSlots` `slots` custom rendering node, and replace it with `v-slot:title` to improve ease of use, avoid slot configuration expansion, and also avoid slot conflicts.
 
+- `AutoComplete`
+
+  - no longer support `optionLabelProp`. Please set Option `value` directly.
+  - options definition align with Select. Please use `options` instead of `dataSource`.
+
 - `Table`
 
   - Removed the `rowSelection.hideDefaultSelections` property of Table, please use `SELECTION_ALL` and `SELECTION_INVERT` in `rowSelection.selections` instead, [custom options](/components/table/#components-table-demo- row-selection-custom).

site/src/vueDocs/migration-v3.zh-CN.md

@@ -35,13 +35,18 @@
 
 为了让组件拥有更好的性能和可维护性，我们几乎使用 TS + Composition Api 重构了所有组件，目前还有极个别的组件没有重构，这类组件会在接下来逐步重构，剩余的组件不会有破坏性更新，所以不用担心未来的升级成本。
 
-3.0 版本重构后较大的更新有 `Tree` `TreeSelect` `DatePicker` `TimePicker` `Calendar` `Form` `Table`，其它组件也有相应功能的更新，你可以查看 ChangeLog 进一步了解详情。
+3.0 版本重构后较大的更新有 `Tree` `TreeSelect` `DatePicker` `TimePicker` `Calendar` `Form` `Table` `AutoComplete`，其它组件也有相应功能的更新，你可以查看 ChangeLog 进一步了解详情。
 
 - `Tree` `TreeSelect`
 
   - 新增了虚拟滚动，废弃使用 `a-tree-node` `a-tree-select-node` 构建节点，使用 `treeData` 属性替代，提升组件性能。
   - 废弃 `scopedSlots` `slots` 自定义渲染节点，使用 `v-slot:title` 替换，提升易用性，避免插槽配置膨胀，同时也避免了插槽冲突问题。
 
+- `AutoComplete`
+
+  - 不再支持 `optionLabelProp`，请直接设置 Option `value` 属性。
+  - 选项与 Select 对齐，请使用 `options` 代替 `dataSource`。
+
 - `Table`
 
   - 移除了 Table 的 `rowSelection.hideDefaultSelections` 属性，请在 `rowSelection.selections` 中使用 `SELECTION_ALL` 和 `SELECTION_INVERT` 替代，[自定义选择项](/components/table/#components-table-demo-row-selection-custom)。