From 29e76b238247f543e5588ea816ccf3ad9f0a309b Mon Sep 17 00:00:00 2001 From: tangjinzhou <415800467@qq.com> Date: Sat, 11 Sep 2021 23:43:58 +0800 Subject: [PATCH] doc: update select --- components/select/index.en-US.md | 80 ++++++++++++++++++-------------- components/select/index.zh-CN.md | 78 +++++++++++++++++-------------- 2 files changed, 87 insertions(+), 71 deletions(-) diff --git a/components/select/index.en-US.md b/components/select/index.en-US.md index 3e33c5a8e..9939e13c6 100644 --- a/components/select/index.en-US.md +++ b/components/select/index.en-US.md @@ -24,43 +24,43 @@ Select component to select value from options. | Property | Description | Type | Default | Version | | --- | --- | --- | --- | --- | -| allowClear | Show clear button. | boolean | false | | -| autoClearSearchValue | Whether the current search will be cleared on selecting an item. Only applies when `mode` is set to `multiple` or `tags`. | boolean | true | | -| autofocus | Get focus by default | boolean | false | | -| bordered | Whether has border style | boolean | true | | -| defaultActiveFirstOption | Whether active first option by default | boolean | true | | -| disabled | Whether disabled select | boolean | false | | -| dropdownClassName | className of dropdown menu | string | - | | -| dropdownMatchSelectWidth | Whether dropdown's width is same with select. | boolean | true | | -| dropdownRender | Customize dropdown content | ({menuNode: VNode, props}) => VNode \| v-slot | - | | -| dropdownStyle | style of dropdown menu | object | - | | -| dropdownMenuStyle | additional style applied to dropdown menu | object | - | | -| 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 | | -| firstActiveValue | Value of action option by default | string\|string\[] | - | | -| getPopupContainer | Parent Node which the selector should be rendered to. Default to `body`. When position issues happen, try to modify it into scrollable content and position it relative. | function(triggerNode) | () => document.body | | -| labelInValue | whether to embed label in value, turn the format of value from `string` to `{key: string, label: vNodes}` | boolean | false | | -| maxTagCount | Max tag count to show | number | - | | -| maxTagPlaceholder | Placeholder for not showing tags | slot/function(omittedValues) | - | | -| maxTagTextLength | Max text length to show | number | - | | -| mode | Set mode of Select | 'multiple' \| 'tags' | - | | -| notFoundContent | Specify content to show when no result matches.. | string\|slot | 'Not Found' | | -| optionFilterProp | Which prop value of option will be used for filter if filterOption is true | string | value | | -| optionLabelProp | Which prop value of option will render as content of select. | string | `value` for `combobox`, `children` for other modes | | -| placeholder | Placeholder of select | string\|slot | - | | -| showSearch | Whether show search input in single mode. | boolean | false | | -| showArrow | Whether to show the drop-down arrow | boolean | true | | -| size | Size of Select input. `default` `large` `small` | string | default | | -| suffixIcon | The custom suffix icon | VNode \| slot | - | | -| removeIcon | The custom remove icon | VNode \| slot | - | | -| clearIcon | The custom clear icon | VNode \| slot | - | | -| menuItemSelectedIcon | The custom menuItemSelected icon | VNode \| slot | - | | -| tokenSeparators | Separator used to tokenize on tag/multiple mode | string\[] | | | -| value(v-model) | Current selected option. | string\|number\|string\[]\|number\[] | - | | -| options | Data of the selectOption, manual construction work is no longer needed if this property has been set | array<{value, label, [disabled, key, title]}> | \[] | | +| allowClear | Show clear button. | boolean | false | | +| autoClearSearchValue | Whether the current search will be cleared on selecting an item. Only applies when `mode` is set to `multiple` or `tags`. | boolean | true | | +| autofocus | Get focus by default | boolean | false | | +| bordered | Whether has border style | boolean | true | | +| defaultActiveFirstOption | Whether active first option by default | boolean | true | | +| disabled | Whether disabled select | boolean | false | | +| dropdownClassName | className of dropdown menu | string | - | | +| dropdownMatchSelectWidth | Whether dropdown's width is same with select. | boolean | true | | +| dropdownRender | Customize dropdown content | ({menuNode: VNode, props}) => VNode \| v-slot | - | | +| dropdownStyle | style of dropdown menu | object | - | | +| dropdownMenuStyle | additional style applied to dropdown menu | object | - | | +| 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 | | +| firstActiveValue | Value of action option by default | string\|string\[] | - | | +| getPopupContainer | Parent Node which the selector should be rendered to. Default to `body`. When position issues happen, try to modify it into scrollable content and position it relative. | function(triggerNode) | () => document.body | | +| labelInValue | whether to embed label in value, turn the format of value from `string` to `{key: string, label: vNodes}` | boolean | false | | +| maxTagCount | Max tag count to show | number | - | | +| maxTagPlaceholder | Placeholder for not showing tags | slot/function(omittedValues) | - | | +| maxTagTextLength | Max text length to show | number | - | | +| mode | Set mode of Select | 'multiple' \| 'tags' | - | | +| notFoundContent | Specify content to show when no result matches.. | string\|slot | 'Not Found' | | +| optionFilterProp | Which prop value of option will be used for filter if filterOption is true | string | value | | +| optionLabelProp | Which prop value of option will render as content of select. | string | `value` for `combobox`, `children` for other modes | | +| placeholder | Placeholder of select | string\|slot | - | | +| showSearch | Whether show search input in single mode. | boolean | false | | +| showArrow | Whether to show the drop-down arrow | boolean | true | | +| size | Size of Select input. `default` `large` `small` | string | default | | +| suffixIcon | The custom suffix icon | VNode \| slot | - | | +| removeIcon | The custom remove icon | VNode \| slot | - | | +| clearIcon | The custom clear icon | VNode \| slot | - | | +| menuItemSelectedIcon | The custom menuItemSelected icon | VNode \| slot | - | | +| tokenSeparators | Separator used to tokenize on tag/multiple mode | string\[] | | | +| value(v-model) | Current selected option. | string\|number\|string\[]\|number\[] | - | | +| options | Data of the selectOption, manual construction work is no longer needed if this property has been set | array<{value, label, [disabled, key, title]}> | \[] | | | option | custom render option by slot | v-slot:option="{value, label, [disabled, key, title]}" | - | 2.2.5 | -| defaultOpen | Initial open state of dropdown | boolean | - | | -| open | Controlled open state of dropdown | boolean | - | | -| loading | indicate loading state | Boolean | false | | +| defaultOpen | Initial open state of dropdown | boolean | - | | +| open | Controlled open state of dropdown | boolean | - | | +| loading | indicate loading state | Boolean | false | | ### events @@ -107,3 +107,11 @@ Select component to select value from options. ### The dropdown is closed when click `dropdownRender` area? See the [dropdownRender example](/components/select/#components-select-demo-custom-dropdown). + +### Why is `placeholder` not displayed? + +`placeholder` will only be displayed when `value = undefined`, and other values such as null, 0,'', etc. are meaningful values for the JS language. + +You can check [JS Language Specification](https://262.ecma-international.org/5.1/#sec-4.3.9) for further details. + +You can also check [antd issue](https://github.com/ant-design/ant-design/issues/2367) to view the discussion. diff --git a/components/select/index.zh-CN.md b/components/select/index.zh-CN.md index 1dde17db9..a6ba8de0e 100644 --- a/components/select/index.zh-CN.md +++ b/components/select/index.zh-CN.md @@ -25,42 +25,42 @@ cover: https://gw.alipayobjects.com/zos/alicdn/_0XzgOis7/Select.svg | 参数 | 说明 | 类型 | 默认值 | 版本 | | --- | --- | --- | --- | --- | -| allowClear | 支持清除 | boolean | false | | -| autoClearSearchValue | 是否在选中项后清空搜索框，只在 `mode` 为 `multiple` 或 `tags` 时有效。 | boolean | true | | -| autofocus | 默认获取焦点 | boolean | false | | -| bordered | 是否有边框 | boolean | true | | -| defaultActiveFirstOption | 是否默认高亮第一个选项。 | boolean | true | | -| disabled | 是否禁用 | boolean | false | | -| dropdownClassName | 下拉菜单的 className 属性 | string | - | | -| dropdownMatchSelectWidth | 下拉菜单和选择器同宽 | boolean | true | 」 -| dropdownRender | 自定义下拉框内容 | ({menuNode: VNode, props}) => VNode \| v-slot | - | | -| dropdownStyle | 下拉菜单的 style 属性 | object | - | | -| dropdownMenuStyle | dropdown 菜单自定义样式 | object | - | | -| filterOption | 是否根据输入项进行筛选。当其为一个函数时，会接收 `inputValue` `option` 两个参数，当 `option` 符合筛选条件时，应返回 `true`，反之则返回 `false`。 | boolean or function(inputValue, option) | true | | -| firstActiveValue | 默认高亮的选项 | string\|string\[] | - | | -| getPopupContainer | 菜单渲染父节点。默认渲染到 body 上，如果你遇到菜单滚动定位问题，试试修改为滚动的区域，并相对其定位。 | Function(triggerNode) | () => document.body | | -| labelInValue | 是否把每个选项的 label 包装到 value 中，会把 Select 的 value 类型从 `string` 变为 `{key: string, label: vNodes}` 的格式 | boolean | false | | -| maxTagCount | 最多显示多少个 tag | number | - | | -| maxTagPlaceholder | 隐藏 tag 时显示的内容 | slot/function(omittedValues) | - | | -| maxTagTextLength | 最大显示的 tag 文本长度 | number | - | | -| mode | 设置 Select 的模式为多选或标签 | 'multiple' \| 'tags' \| 'combobox' | - | | -| notFoundContent | 当下拉列表为空时显示的内容 | string\|slot | 'Not Found' | | -| optionFilterProp | 搜索时过滤对应的 option 属性，不支持 children | string | value | | -| optionLabelProp | 回填到选择框的 Option 的属性值，默认是 Option 的子元素。比如在子元素需要高亮效果时，此值可以设为 `value`。 | string | `children` （combobox 模式下为 `value`） | | -| placeholder | 选择框默认文字 | string\|slot | - | | -| showSearch | 使单选模式可搜索 | boolean | false | | -| showArrow | 是否显示下拉小箭头 | boolean | true | | -| size | 选择框大小，可选 `large` `small` | string | default | | -| suffixIcon | 自定义的选择框后缀图标 | VNode \| slot | - | | -| removeIcon | 自定义的多选框清除图标 | VNode \| slot | - | | -| clearIcon | 自定义的多选框清空图标 | VNode \| slot | - | | -| menuItemSelectedIcon | 自定义当前选中的条目图标 | VNode \| slot | - | | -| tokenSeparators | 在 tags 和 multiple 模式下自动分词的分隔符 | string\[] | | | -| value(v-model) | 指定当前选中的条目 | string\|string\[]\|number\|number\[] | - | | -| options | options 数据，如果设置则不需要手动构造 selectOption 节点 | array<{value, label, [disabled, key, title]}> | \[] | | +| allowClear | 支持清除 | boolean | false | | +| autoClearSearchValue | 是否在选中项后清空搜索框，只在 `mode` 为 `multiple` 或 `tags` 时有效。 | boolean | true | | +| autofocus | 默认获取焦点 | boolean | false | | +| bordered | 是否有边框 | boolean | true | | +| defaultActiveFirstOption | 是否默认高亮第一个选项。 | boolean | true | | +| disabled | 是否禁用 | boolean | false | | +| dropdownClassName | 下拉菜单的 className 属性 | string | - | | +| dropdownMatchSelectWidth | 下拉菜单和选择器同宽 | boolean | true | 」 | +| dropdownRender | 自定义下拉框内容 | ({menuNode: VNode, props}) => VNode \| v-slot | - | | +| dropdownStyle | 下拉菜单的 style 属性 | object | - | | +| dropdownMenuStyle | dropdown 菜单自定义样式 | object | - | | +| filterOption | 是否根据输入项进行筛选。当其为一个函数时，会接收 `inputValue` `option` 两个参数，当 `option` 符合筛选条件时，应返回 `true`，反之则返回 `false`。 | boolean or function(inputValue, option) | true | | +| firstActiveValue | 默认高亮的选项 | string\|string\[] | - | | +| getPopupContainer | 菜单渲染父节点。默认渲染到 body 上，如果你遇到菜单滚动定位问题，试试修改为滚动的区域，并相对其定位。 | Function(triggerNode) | () => document.body | | +| labelInValue | 是否把每个选项的 label 包装到 value 中，会把 Select 的 value 类型从 `string` 变为 `{key: string, label: vNodes}` 的格式 | boolean | false | | +| maxTagCount | 最多显示多少个 tag | number | - | | +| maxTagPlaceholder | 隐藏 tag 时显示的内容 | slot/function(omittedValues) | - | | +| maxTagTextLength | 最大显示的 tag 文本长度 | number | - | | +| mode | 设置 Select 的模式为多选或标签 | 'multiple' \| 'tags' \| 'combobox' | - | | +| notFoundContent | 当下拉列表为空时显示的内容 | string\|slot | 'Not Found' | | +| optionFilterProp | 搜索时过滤对应的 option 属性，不支持 children | string | value | | +| optionLabelProp | 回填到选择框的 Option 的属性值，默认是 Option 的子元素。比如在子元素需要高亮效果时，此值可以设为 `value`。 | string | `children` （combobox 模式下为 `value`） | | +| placeholder | 选择框默认文字 | string\|slot | - | | +| showSearch | 使单选模式可搜索 | boolean | false | | +| showArrow | 是否显示下拉小箭头 | boolean | true | | +| size | 选择框大小，可选 `large` `small` | string | default | | +| suffixIcon | 自定义的选择框后缀图标 | VNode \| slot | - | | +| removeIcon | 自定义的多选框清除图标 | VNode \| slot | - | | +| clearIcon | 自定义的多选框清空图标 | VNode \| slot | - | | +| menuItemSelectedIcon | 自定义当前选中的条目图标 | VNode \| slot | - | | +| tokenSeparators | 在 tags 和 multiple 模式下自动分词的分隔符 | string\[] | | | +| value(v-model) | 指定当前选中的条目 | string\|string\[]\|number\|number\[] | - | | +| options | options 数据，如果设置则不需要手动构造 selectOption 节点 | array<{value, label, [disabled, key, title]}> | \[] | | | option | 通过 option 插槽，自定义节点 | v-slot:option="{value, label, [disabled, key, title]}" | - | 2.2.5 | -| defaultOpen | 是否默认展开下拉菜单 | boolean | - | | -| open | 是否展开下拉菜单 | boolean | - | | +| defaultOpen | 是否默认展开下拉菜单 | boolean | - | | +| open | 是否展开下拉菜单 | boolean | - | | > 注意，如果发现下拉菜单跟随页面滚动，或者需要在其他弹层中触发 Select，请尝试使用 `getPopupContainer={triggerNode => triggerNode.parentNode}` 将下拉弹层渲染节点固定在触发器的父元素中。 @@ -109,3 +109,11 @@ cover: https://gw.alipayobjects.com/zos/alicdn/_0XzgOis7/Select.svg ### 点击 `dropdownRender` 里的内容浮层关闭怎么办？ 看下 [dropdownRender 例子](/components/select-cn/#components-select-demo-custom-dropdown) 里的说明。 + +### 为什么 `placeholder` 不显示 ？ + +`placeholder` 只有在 value = undefined 才会显示，对于其它的 null、0、'' 等等对于 JS 语言都是有意义的值。 + +你可以查看 [JS 语言规范](https://262.ecma-international.org/5.1/#sec-4.3.9) 进一步了解详情。 + +也可以查看 [antd issue](https://github.com/ant-design/ant-design/issues/2367) 查看讨论情况。