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.<br>Since API version 10, this parameter supports two-way binding through [$$](../../quick-start/arkts-two-way-sync.md).| 22| icon | string | No | Path to the search icon. By default, the system search icon is used.<br>For details about the supported image types, see [Image](ts-basic-components-image.md).| 23| controller | SearchController | No | Controller of the **\<Search>** component. | 24 25## Attributes 26 27In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 28 29| Name | Type | Description | 30| ----------------------- | ------------------------------------------------ | ---------------------------------------------- | 31| searchButton | string | Text on the search button located next to the search text box. By default, there is no search button. | 32| placeholderColor | [ResourceColor](ts-types.md#resourcecolor) | Placeholder text color. | 33| placeholderFont | [Font](ts-types.md#font) | Placeholder text style, including the font size, font width, font family, and font style. Currently, only the default font family is supported. | 34| textFont | [Font](ts-types.md#font) | Style of the text entered in the search box, including the font size, font width, font family, and font style. Currently, only the default font family is supported. | 35| textAlign | [TextAlign](ts-appendix-enums.md#textalign) | Text alignment mode in the search text box.<br>Default value: **TextAlign.Start** | 36| copyOption<sup>9+</sup> | [CopyOptions](ts-appendix-enums.md#copyoptions9) | Whether copy and paste is allowed. | 37 38## Events 39 40In addition to the [universal events](ts-universal-events-click.md), the following events are supported. 41 42| Name | Description | 43| ------------------------------------------- | ------------------------------------------------------------ | 44| 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. | 45| onChange(callback: (value: string) => void) | Invoked when the input in the text box changes.<br> - **value**: current text input. | 46| 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. | 47| 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. | 48| 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. | 49 50## SearchController 51 52Implements the controller of the **\<Search>** component. Currently, the controller can be used to control the caret position. 53 54### Objects to Import 55``` 56controller: SearchController = new SearchController() 57``` 58### caretPosition 59 60caretPosition(value: number): void 61 62Sets the position of the caret. 63 64**Parameters** 65 66| Name| Type| Mandatory| Description | 67| ------ | -------- | ---- | ---------------------------------- | 68| value | number | Yes | Length from the start of the character string to the position where the caret is located.| 69 70## Example 71 72```ts 73// xxx.ets 74@Entry 75@Component 76struct SearchExample { 77 @State changeValue: string = '' 78 @State submitValue: string = '' 79 controller: SearchController = new SearchController() 80 81 build() { 82 Column() { 83 Text('onSubmit:' + this.submitValue).fontSize(18).margin(15) 84 Text('onChange:' + this.changeValue).fontSize(18).margin(15) 85 Search({ value: this.changeValue, placeholder: 'Type to search...', controller: this.controller }) 86 .searchButton('SEARCH') 87 .width(400) 88 .height(40) 89 .backgroundColor('#F5F5F5') 90 .placeholderColor(Color.Grey) 91 .placeholderFont({ size: 14, weight: 400 }) 92 .textFont({ size: 14, weight: 400 }) 93 .onSubmit((value: string) => { 94 this.submitValue = value 95 }) 96 .onChange((value: string) => { 97 this.changeValue = value 98 }) 99 .margin(20) 100 Button('Set caretPosition 1') 101 .onClick(() => { 102 // Move the caret to after the first entered character. 103 this.controller.caretPosition(1) 104 }) 105 }.width('100%') 106 } 107} 108``` 109 110 111
