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?: ResourceStr, 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| placeholder | [ResourceStr](ts-types.md#resourcestr)<sup>10+</sup> | 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.<br>**NOTE**<br>The icon data source can be a local or online image.<br>- The supported formats include PNG, JPG, BMP, SVG, GIF, and pixelmap.<br>- The Base64 string is supported in the following format: data:image/[png\|jpeg\|bmp\|webp];base64,[base64 data], where [base64 data] is a Base64 string.<br>If this attribute and the **searchIcon** attribute are both set, the **searchIcon** attribute takes precedence.| 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<sup>10+</sup> | value: string,<br>option?: [SearchButtonOptions](#searchbuttonoptions10) | 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.<br>Default value: **'#99182431'** | 34| 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. | 35| 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. | 36| textAlign | [TextAlign](ts-appendix-enums.md#textalign) | Text alignment mode in the search text box. Currently, the following alignment modes are supported: **Start**, **Center**, and **End**.<br>Default value: **TextAlign.Start** | 37| copyOption<sup>9+</sup> | [CopyOptions](ts-appendix-enums.md#copyoptions9) | Whether copy and paste is allowed.<br>Default value: **CopyOptions.LocalDevice**<br>If this attribute is set to **CopyOptions.None**, the text can be pasted, but copy or cut is not allowed. | 38| searchIcon<sup>10+</sup> | [IconOptions](#iconoptions10) | Style of the search icon on the left. | 39| cancelButton<sup>10+</sup> | {<br>style? : [CancelButtonStyle](#cancelbuttonstyle10)<br>icon?: [IconOptions](#iconoptions10) <br>} | Style of the Cancel button on the right.<br>Default value:<br>{<br>style: CancelButtonStyle.INPUT<br>} | 40| fontColor<sup>10+</sup> | [ResourceColor](ts-types.md#resourcecolor) | Font color of the input text.<br>Default value: **'#FF182431'**<br>**NOTE**<br>[Universal text attributes](ts-universal-attributes-text-style.md) **fontSize**, **fontStyle**, **fontWeight**, and **fontFamily** are set in the **textFont** attribute.| 41| caretStyle<sup>10+</sup> | [CaretStyle](#caretstyle10) | Caret style.<br>Default value:<br>{<br>width: 1.5vp<br>color: '#007DFF'<br>} | 42| enableKeyboardOnFocus<sup>10+</sup> | boolean | Whether to enable the input method when the component obtains focus.<br>Default value: **true** | 43| selectionMenuHidden<sup>10+</sup> | boolean | Whether to display the text selection menu when the text box is long-pressed or right-clicked.<br>Default value: **false**| 44| customKeyboard<sup>10+</sup> | [CustomBuilder](ts-types.md#custombuilder8) | Custom keyboard.<br>**NOTE**<br>When a custom keyboard is set, activating the text box opens the specified custom component, instead of the system input method.<br>The custom keyboard's height can be set through the **height** attribute of the custom component's root node, and its width is fixed at the default value.<br>The custom keyboard is displayed on top of the current page, without compressing or raising the page.<br>The custom keyboard cannot obtain the focus, but it blocks gesture events.<br>By default, the custom keyboard is closed when the input component loses the focus. You can also use the [stopEditing](#stopediting10) API to close the keyboard.| 45 46## IconOptions<sup>10+</sup> 47 48| Name| Type | Mandatory| Description | 49| ------ | ------------------------------------------ | ---- | ----------- | 50| size | [Length](ts-types.md#length) | No | Icon size. It cannot be set in percentage. | 51| color | [ResourceColor](ts-types.md#resourcecolor) | No | Icon color. | 52| src | [ResourceStr](ts-types.md#resourcestr) | No | Image source of the icon.| 53 54## CaretStyle<sup>10+</sup> 55 56| Name| Type | Mandatory| Description| 57| ------ | ------------------------------------------ | ---- | -------- | 58| width | [Length](ts-types.md#length) | No | Caret size. It cannot be set in percentage.| 59| color | [ResourceColor](ts-types.md#resourcecolor) | No | Caret color.| 60 61## SearchButtonOptions<sup>10+</sup> 62 63| Name | Type | Mandatory| Description | 64| --------- | ------------------------------------------ | ---- | ---------------- | 65| fontSize | [Length](ts-types.md#length) | No | Font size of the button. It cannot be set in percentage.| 66| fontColor | [ResourceColor](ts-types.md#resourcecolor) | No | Font color of the button.| 67 68## CancelButtonStyle<sup>10+</sup> 69 70| Name | Description | 71| ----------------------- | ---------------- | 72| CONSTANT | The Cancel button is always displayed.| 73| INVISIBLE | The Cancel button is always hidden.| 74| INPUT | The Cancel button is displayed when there is text input.| 75 76## Events 77 78In addition to the [universal events](ts-universal-events-click.md), the following events are supported. 79 80| Name | Description | 81| ------------------------------------------------------------ | ------------------------------------------------------------ | 82| onSubmit(callback: (value: string) => void) | Triggered when users click the search icon or the search button, or touch the search button on a soft keyboard.<br> - **value**: current text input.| 83| onChange(callback: (value: string) => void) | Triggered when the input in the text box changes.<br> - **value**: current text input.| 84| onCopy(callback: (value: string) => void) | Triggered when data is copied to the pasteboard, which is displayed when the search text box is long pressed.<br> - **value**: text copied.| 85| onCut(callback: (value: string) => void) | Triggered when data is cut from the pasteboard, which is displayed when the search text box is long pressed.<br> - **value**: text cut.| 86| onPaste(callback: (value: string) => void) | Triggered when data is pasted from the pasteboard, which is displayed when the search text box is long pressed.<br> -**value**: text pasted.| 87| onTextSelectionChange(callback: (selectionStart: number, selectionEnd: number) => void)<sup>10+</sup> | Triggered when the text selection position changes.<br>**selectionStart**: start position of the text selection area. The start position of text in the text box is **0**.<br>**selectionEnd**: end position of the text selection area.| 88| onContentScroll(callback: (totalOffsetX: number, totalOffsetY: number) => void)<sup>10+</sup> | Triggered when the text content is scrolled.<br>**totalOffsetX**: X coordinate offset of the text in the content area.<br>**totalOffsetY**: Y coordinate offset of the text in the content area.| 89 90## SearchController 91 92Implements the controller of the **\<Search>** component. Currently, the controller can be used to control the caret position. 93 94### Objects to Import 95``` 96controller: SearchController = new SearchController() 97``` 98### caretPosition 99 100caretPosition(value: number): void 101 102Sets the position of the caret. 103 104**Parameters** 105 106| Name| Type| Mandatory| Description | 107| ------ | -------- | ---- | ---------------------------------- | 108| value | number | Yes | Length from the start of the character string to the position where the caret is located.| 109 110### stopEditing<sup>10+</sup> 111 112stopEditing(): void 113 114Exits the editing state. 115 116### getTextContentRect<sup>10+</sup> 117 118getTextContentRect(): [RectResult](#rectresult10) 119 120Obtains the position of the edited text area relative to the component and its size. The unit of the return value is pixel. 121 122**Return value** 123 124| Type | Description | 125| ------------------- | -------- | 126| [RectResult](#rectresult10) | Position of the edited text area relative to the component and its size.| 127 128> **NOTE** 129> 130> - The returned position information is the offset of the first character relative to the search icon in the **\<Search>** component. 131> - If no text is entered, the return value contains the position information, but the size is 0. 132 133### RectResult<sup>10+</sup> 134 135Describes the position and size. 136 137| Parameter | Type | Description| 138| ------- | ------ | ----------------------- | 139| x | number | X coordinate.| 140| y | number | Y coordinate.| 141| width | number | Content width.| 142| height | number | Content height.| 143 144 145### getTextContentLineCount<sup>10+</sup> 146 147getTextContentLineCount(): number 148 149Obtains the number of lines of the edited text. 150 151**Return value** 152 153| Type | Description | 154| ----- | -------- | 155| number| Number of lines of the edited text.| 156 157## Example 158 159### Example 1 160 161```ts 162// xxx.ets 163@Entry 164@Component 165struct SearchExample { 166 @State changeValue: string = '' 167 @State submitValue: string = '' 168 controller: SearchController = new SearchController() 169 170 build() { 171 Column() { 172 Text('onSubmit:' + this.submitValue).fontSize(18).margin(15) 173 Text('onChange:' + this.changeValue).fontSize(18).margin(15) 174 Search({ value: this.changeValue, placeholder: 'Type to search...', controller: this.controller }) 175 .searchButton('SEARCH') 176 .width('95%') 177 .height(40) 178 .backgroundColor('#F5F5F5') 179 .placeholderColor(Color.Grey) 180 .placeholderFont({ size: 14, weight: 400 }) 181 .textFont({ size: 14, weight: 400 }) 182 .onSubmit((value: string) => { 183 this.submitValue = value 184 }) 185 .onChange((value: string) => { 186 this.changeValue = value 187 }) 188 .margin(20) 189 Button('Set caretPosition 1') 190 .onClick(() => { 191 // Move the caret to after the first entered character. 192 this.controller.caretPosition(1) 193 }) 194 }.width('100%') 195 } 196} 197``` 198 199 200 201### Example 2 202 203```ts 204// xxx.ets 205@Entry 206@Component 207struct SearchButtoonExample { 208 @State submitValue: string = '' 209 210 build() { 211 Column() { 212 Text('onSubmit:' + this.submitValue).fontSize(18).margin(15) 213 Search({ placeholder: 'Type to search...' }) 214 .searchButton('SEARCH') 215 .searchIcon({ 216 src: $r('app.media.search') 217 }) 218 .cancelButton({ 219 style: CancelButtonStyle.CONSTANT, 220 icon: { 221 src: $r('app.media.cancel') 222 } 223 }) 224 .width('90%') 225 .height(40) 226 .backgroundColor('#F5F5F5') 227 .placeholderColor(Color.Grey) 228 .placeholderFont({ size: 14, weight: 400 }) 229 .textFont({ size: 14, weight: 400 }) 230 .onSubmit((value: string) => { 231 this.submitValue = value 232 }) 233 .margin(20) 234 }.width('100%') 235 } 236} 237``` 238 239 240 241 242### Example 3 243 244```ts 245// xxx.ets 246@Entry 247@Component 248struct SearchExample { 249 controller: SearchController = new SearchController() 250 @State inputValue: string = "" 251 252 // Create a custom keyboard component. 253 @Builder CustomKeyboardBuilder() { 254 Column() { 255 Button('x').onClick(() => { 256 // Disable the custom keyboard. 257 this.controller.stopEditing() 258 }) 259 Grid() { 260 ForEach([1, 2, 3, 4, 5, 6, 7, 8, 9, '*', 0, '#'], (item) => { 261 GridItem() { 262 Button(item + "") 263 .width(110).onClick(() => { 264 this.inputValue += item 265 }) 266 } 267 }) 268 }.maxCount(3).columnsGap(10).rowsGap(10).padding(5) 269 }.backgroundColor(Color.Gray) 270 } 271 272 build() { 273 Column() { 274 Search({ controller: this.controller, value: this.inputValue}) 275 // Bind the custom keyboard. 276 .customKeyboard(this.CustomKeyboardBuilder()).margin(10).border({ width: 1 }) 277 } 278 } 279} 280```` 281 282 283
