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. <br>**NOTE**<br>For dragging, **copyOption** only restricts whether text is selected and does not involve the dragging scope.| 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**: offset in the X coordinate of the text in the content area, in px.<br>**totalOffsetY**: offset in the Y coordinate of the text in the content area, in px.| 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 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 135Sets the position and size, in pixels. 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 SearchExample { 208 @State changeValue: string = '' 209 @State submitValue: string = '' 210 211 build() { 212 Column() { 213 Text('onSubmit:' + this.submitValue).fontSize(18).margin(15) 214 Search({ value: this.changeValue, placeholder: 'Type to search...' }) 215 .searchButton('SEARCH') 216 .searchIcon({ 217 src: $r('app.media.search') 218 }) 219 .cancelButton({ 220 style: CancelButtonStyle.CONSTANT, 221 icon: { 222 src: $r('app.media.cancel') 223 } 224 }) 225 .width('90%') 226 .height(40) 227 .backgroundColor('#F5F5F5') 228 .placeholderColor(Color.Grey) 229 .placeholderFont({ size: 14, weight: 400 }) 230 .textFont({ size: 14, weight: 400 }) 231 .onSubmit((value: string) => { 232 this.submitValue = value 233 }) 234 .onChange((value: string) => { 235 this.changeValue = value 236 }) 237 .margin(20) 238 }.width('100%') 239 } 240} 241``` 242 243 244 245 246### Example 3 247 248```ts 249// xxx.ets 250@Entry 251@Component 252struct SearchExample { 253 controller: SearchController = new SearchController() 254 @State inputValue: string = "" 255 256 // Create a custom keyboard component. 257 @Builder CustomKeyboardBuilder() { 258 Column() { 259 Button('x').onClick(() => { 260 // Disable the custom keyboard. 261 this.controller.stopEditing() 262 }) 263 Grid() { 264 ForEach([1, 2, 3, 4, 5, 6, 7, 8, 9, '*', 0, '#'], (item: number | string) => { 265 GridItem() { 266 Button(item + "") 267 .width(110).onClick(() => { 268 this.inputValue += item 269 }) 270 } 271 }) 272 }.maxCount(3).columnsGap(10).rowsGap(10).padding(5) 273 }.backgroundColor(Color.Gray) 274 } 275 276 build() { 277 Column() { 278 Search({ controller: this.controller, value: this.inputValue}) 279 // Bind the custom keyboard. 280 .customKeyboard(this.CustomKeyboardBuilder()).margin(10).border({ width: 1 }) 281 } 282 } 283} 284```` 285 286 287
