1# Search 2 3The **\<Search>** component provides an area for users to enter search queries. 4 5> **NOTE** 6> 7> This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. 8 9## Child Components 10 11Not supported 12 13## APIs 14 15Search(options?: { value?: string; placeholder?: string; icon?: string; controller?: SearchController }) 16 17**Parameters** 18 19| Name | Type | Mandatory| Description | 20| ----------- | ---------------- | ---- | ------------------------------------------------------------ | 21| value | string | No | Text input in the search text box. | 22| placeholder | string | No | Text displayed when there is no input. | 23| icon | string | No | Path to the search icon. By default, the system search icon is used. The supported icon formats are .svg, .jpg, and .png.| 24| controller | SearchController | No | Controller of the **\<Search>** component. | 25 26## Attributes 27 28In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 29 30| Name | Type | Description | 31| ----------------------- | ------------------------------------------------ | ---------------------------------------------- | 32| searchButton | string | Text on the search button located next to the search text box. By default, there is no search button. | 33| placeholderColor | [ResourceColor](ts-types.md#resourcecolor) | Placeholder text color. | 34| placeholderFont | [Font](ts-types.md#font) | Placeholder text font. | 35| textFont | [Font](ts-types.md#font) | Text font for the search text box. | 36| textAlign | [TextAlign](ts-appendix-enums.md#textalign) | Text alignment mode in the search text box.<br>Default value: **TextAlign.Start** | 37| copyOption<sup>9+</sup> | [CopyOptions](ts-appendix-enums.md#copyoptions9) | Whether copy and paste is allowed. | 38 39## Events 40 41In addition to the [universal events](ts-universal-events-click.md), the following events are supported. 42 43| Name | Description | 44| ------------------------------------------- | ------------------------------------------------------------ | 45| onSubmit(callback: (value: string) => void) | Invoked when users click the search icon or the search button, or touch the search button on a soft keyboard.<br> - **value**: current text input. | 46| onChange(callback: (value: string) => void) | Invoked when the input in the text box changes.<br> - **value**: current text input. | 47| onCopy(callback: (value: string) => void) | Invoked when data is copied to the pasteboard, which is displayed when the search text box is long pressed.<br> - **value**: text copied. | 48| onCut(callback: (value: string) => void) | Invoked when data is cut from the pasteboard, which is displayed when the search text box is long pressed.<br> - **value**: text cut. | 49| onPaste(callback: (value: string) => void) | Invoked when data is pasted from the pasteboard, which is displayed when the search text box is long pressed.<br> -**value**: text pasted. | 50 51## SearchController 52 53Implements the controller of the **\<Search>** component. Currently, the controller can be used to control the caret position. 54 55### Objects to Import 56``` 57controller: SearchController = new SearchController() 58``` 59### caretPosition 60 61caretPosition(value: number): void 62 63Sets the position of the caret. 64 65**Parameters** 66 67| Name| Type| Mandatory| Description | 68| ------ | -------- | ---- | ---------------------------------- | 69| value | number | Yes | Length from the start of the character string to the position where the caret is located.| 70 71## Example 72 73```ts 74// xxx.ets 75@Entry 76@Component 77struct SearchExample { 78 @State changeValue: string = '' 79 @State submitValue: string = '' 80 controller: SearchController = new SearchController() 81 82 build() { 83 Column() { 84 Text('onSubmit:' + this.submitValue).fontSize(18).margin(15) 85 Text('onChange:' + this.changeValue).fontSize(18).margin(15) 86 Search({ value: this.changeValue, placeholder: 'Type to search...', controller: this.controller }) 87 .searchButton('SEARCH') 88 .width(400) 89 .height(40) 90 .backgroundColor('#F5F5F5') 91 .placeholderColor(Color.Grey) 92 .placeholderFont({ size: 14, weight: 400 }) 93 .textFont({ size: 14, weight: 400 }) 94 .onSubmit((value: string) => { 95 this.submitValue = value 96 }) 97 .onChange((value: string) => { 98 this.changeValue = value 99 }) 100 .margin(20) 101 Button('Set caretPosition 1') 102 .onClick(() => { 103 // Move the caret to after the first entered character. 104 this.controller.caretPosition(1) 105 }) 106 }.width('100%') 107 } 108} 109``` 110 111 112
