完善 searchBox 补充文档 (#1866)

docs/zh-CN/components/search-box.md

@@ -0,0 +1,130 @@
+---
+title: 搜索框
+description:
+type: 0
+group: ⚙ 组件
+menuName: Search Box
+icon:
+---
+
+## 基本用法
+
+用于展示一个简单搜索框，通常需要搭配其他组件使用。比如 page 配置 `initApi` 后，可以用来实现简单数据过滤查找，`name` keywords 会作为参数传递给 page 的 `initApi`。
+
+```schema
+{
+    "type": "page",
+    "initApi": "https://3xsw4ap8wah59.cfc-execute.bj.baidubce.com/api/amis-mock/mock2/page/initData?keywords=${keywords}",
+    "body": [
+      {
+        "type": "search-box",
+        "name": "keywords"
+      },
+
+      {
+        "type": "tpl",
+        "tpl": "<p>关键字：${keywords}</p><p>返回结果：${&|json}</p>"
+      }
+    ]
+}
+```
+
+## mini 版本
+
+```schema
+{
+    "type": "page",
+    "initApi": "https://3xsw4ap8wah59.cfc-execute.bj.baidubce.com/api/amis-mock/mock2/page/initData?keywords=${keywords}",
+    "body": [
+      {
+        "type": "search-box",
+        "name": "keywords",
+        "mini": true
+      },
+
+      {
+        "type": "tpl",
+        "tpl": "<p>关键字：${keywords}</p><p>返回结果：${&|json}</p>"
+      }
+    ]
+}
+```
+
+## 与 CRUD 搭配
+
+```schema: scope="body"
+{
+    "type": "crud",
+    "api": "https://3xsw4ap8wah59.cfc-execute.bj.baidubce.com/api/amis-mock/sample",
+    "syncLocation": false,
+    "headerToolbar": [
+      {
+        "type": "search-box",
+        "name": "keywords",
+        "align": "right",
+        "placeholder": "关键字检索"
+      }
+    ],
+    "columns": [
+        {
+            "name": "id",
+            "label": "ID"
+        },
+        {
+            "name": "engine",
+            "label": "Rendering engine"
+        },
+        {
+            "name": "browser",
+            "label": "Browser"
+        },
+        {
+            "name": "platform",
+            "label": "Platform(s)"
+        },
+        {
+            "name": "version",
+            "label": "Engine version"
+        },
+        {
+            "name": "grade",
+            "label": "CSS grade"
+        }
+    ]
+}
+```
+
+## 与 Service 搭配
+
+```schema
+{
+    "type": "page",
+    "body": [
+      {
+        "type": "service",
+        "api": "https://3xsw4ap8wah59.cfc-execute.bj.baidubce.com/api/amis-mock/mock2/page/initData?keywords=${keywords}",
+        "body": [
+          {
+            "type": "search-box",
+            "name": "keywords"
+          },
+
+          {
+            "type": "tpl",
+            "tpl": "<p>关键字：${keywords}</p><p>返回结果：${&|json}</p>"
+          }
+        ]
+      }
+
+    ]
+}
+```
+
+## 属性表
+
+| 属性名           | 类型      | 默认值 | 说明             |
+| ---------------- | --------- | ------ | ---------------- |
+| type             | `string`  |        | `search-box`     |
+| className        | `string`  |        | 外层 CSS 类名    |
+| mini             | `boolean` |        | 是否为 mini 模式 |
+| searchImediately | `boolean` |        | 是否立即搜索     |

examples/components/CRUD/ItemActions.jsx

@@ -12,13 +12,21 @@ export default {
         className: 'pull-right',
         align: 'right'
       },
+      {
+        type: 'search-box',
+        align: 'right',
+        name: 'keywords',
+        placeholder: '请输入关键字',
+        mini: true
+      },
+
       {
         type: 'drag-toggler',
-        className: 'pull-right'
+        align: 'right'
       },
       {
         type: 'pagination',
-        className: 'pull-right'
+        align: 'right'
       }
     ],
     itemActions: [

examples/components/Components.tsx

@@ -1030,6 +1030,16 @@ export const components = [
           )
       },
 
+      {
+        label: '搜索框',
+        path: '/zh-CN/components/search-box',
+        getComponent: () =>
+          // @ts-ignore
+          import('../../docs/zh-CN/components/search-box.md').then(
+            makeMarkdownRenderer
+          )
+      },
+
       {
         label: 'Sparkline 走势图',
         path: '/zh-CN/components/sparkline',

src/components/SearchBox.tsx

@@ -87,6 +87,7 @@ export class SearchBox extends React.Component<SearchBoxProps> {
       value,
       active,
       name,
+      className,
       onChange,
       disabled,
       placeholder,
@@ -98,6 +99,7 @@ export class SearchBox extends React.Component<SearchBoxProps> {
       <div
         className={cx(
           'SearchBox',
+          className,
           disabled ? 'is-disabled' : '',
           !mini || active ? 'is-active' : ''
         )}

src/renderers/SearchBox.tsx

@@ -1,7 +1,7 @@
 import Spinner from '../components/Spinner';
 import {Renderer, RendererProps} from '../factory';
 import React from 'react';
-import {BaseSchema} from '../Schema';
+import {BaseSchema, SchemaClassName} from '../Schema';
 import SearchBox from '../components/SearchBox';
 import {autobind, getVariable, setVariable} from '../utils/helper';
 
@@ -16,6 +16,11 @@ export interface SearchBoxSchema extends BaseSchema {
    */
   type: 'search-box';
 
+  /**
+   * 外层 css 类名
+   */
+  className?: SchemaClassName;
+
   /**
    * 关键字名字。
    *
@@ -23,6 +28,11 @@ export interface SearchBoxSchema extends BaseSchema {
    */
   name?: string;
 
+  /**
+   * 占位符
+   */
+  placeholder?: string;
+
   /**
    * 是否为 Mini 样式。
    */
@@ -58,10 +68,13 @@ export class SearchBoxRenderer extends React.Component<SearchBoxProps> {
   handleCancel() {
     const name = this.props.name;
     const onQuery = this.props.onQuery;
+    const value = this.props.value ?? getVariable(this.props.data, name);
+    if (value !== '') {
       const data: any = {};
       setVariable(data, name, '');
       onQuery?.(data);
     }
+  }
 
   @autobind
   handleSearch(text: string) {
@@ -72,19 +85,33 @@ export class SearchBoxRenderer extends React.Component<SearchBoxProps> {
   }
 
   render() {
-    const {data, name, onQuery: onQuery, mini, searchImediately} = this.props;
+    const {
+      data,
+      name,
+      onQuery: onQuery,
+      mini,
+      searchImediately,
+      placeholder,
+      onChange,
+      className
+    } = this.props;
+
+    const value = this.props.value ?? getVariable(data, name);
 
-    const value = getVariable(data, name);
     return (
       <SearchBox
+        className={className}
         name={name}
         disabled={!onQuery}
         defaultActive={!!value}
-        defaultValue={value}
+        defaultValue={onChange ? undefined : value}
+        value={onChange ? value : undefined}
         mini={mini}
         searchImediately={searchImediately}
         onSearch={this.handleSearch}
         onCancel={this.handleCancel}
+        placeholder={placeholder}
+        onChange={onChange}
       />
     );
   }