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?: SearchOptions) 16 17**Atomic service API**: This API can be used in atomic services since API version 11. 18 19**System capability**: SystemCapability.ArkUI.ArkUI.Full 20 21**Parameters** 22 23| Name | Type | Mandatory| Description | 24| ----------- | ------------- | ---- | ------------- | 25| options | [SearchOptions](#searchoptions18)| No | Initialization options of the **Search** component.| 26 27## SearchOptions<sup>18+</sup> 28 29Describes the initialization options of the **Search** component. 30 31**Atomic service API**: This API can be used in atomic services since API version 18. 32 33**System capability**: SystemCapability.ArkUI.ArkUI.Full 34 35| Name | Type | Mandatory| Description | 36| ----------- | ------------- | ---- | ------------- | 37| value<sup>8+</sup> | 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).<br>Since API version 18, this parameter supports two-way binding through [!!](../../../quick-start/arkts-new-binding.md#two-way-binding-between-built-in-component-parameters).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 38| placeholder<sup>8+</sup> | [ResourceStr](ts-types.md#resourcestr) | No | Text displayed when there is no input.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 39| icon<sup>8+</sup> | 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, pixelmap, and HEIF.<br>- The Base64 string is supported in the following format: data:image/[png\|jpeg\|bmp\|webp\|heif];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.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 40| controller<sup>8+</sup> | [SearchController](#searchcontroller) | No | Controller of the **Search** component.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 41 42## Attributes 43 44In addition to the [universal attributes](ts-component-general-attributes.md), the following attributes are supported. 45 46### searchButton 47 48searchButton(value: string, option?: SearchButtonOptions) 49 50Sets the text on the search button located next to the search text box. 51 52Clicking the search button triggers both **onSubmit** and **onClick** callbacks. 53 54The default font size on wearable devices is 18 fp. 55 56**Atomic service API**: This API can be used in atomic services since API version 11. 57 58**System capability**: SystemCapability.ArkUI.ArkUI.Full 59 60**Parameters** 61 62| Name| Type | Mandatory| Description | 63| ------ | ----------------------------------------------------- | ---- | ---------------------------- | 64| value | string | Yes | Text on the search button located next to the search text box.| 65| option | [SearchButtonOptions](#searchbuttonoptions10) | No | Font of the search text box.<br>Default value:<br>{<br>fontSize: '16fp',<br>fontColor: '#ff3f97e9'<br>} | 66 67### placeholderColor 68 69placeholderColor(value: ResourceColor) 70 71Sets the placeholder text color. The default value on wearable devices is **#99ffffff.** 72 73**Atomic service API**: This API can be used in atomic services since API version 11. 74 75**System capability**: SystemCapability.ArkUI.ArkUI.Full 76 77**Parameters** 78 79| Name| Type | Mandatory| Description | 80| ------ | ------------------------------------------ | ---- | ------------------------------------------------ | 81| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Placeholder text color.<br>Default value: **'#99182431'**| 82 83### placeholderFont 84 85placeholderFont(value?: Font) 86 87Sets the placeholder text style, including the font size, font width, font family, and font style. The 'HarmonyOS Sans' font and [registered custom fonts](../js-apis-font.md) are supported. 88 89The default font size on wearable devices is 18 px. 90 91**Atomic service API**: This API can be used in atomic services since API version 11. 92 93**System capability**: SystemCapability.ArkUI.ArkUI.Full 94 95**Parameters** 96 97| Name| Type | Mandatory| Description | 98| ------ | ------------------------ | ---- | --------------------- | 99| value | [Font](ts-types.md#font) | No | Placeholder text style.| 100 101### textFont 102 103textFont(value?: Font) 104 105Sets the 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. 106 107The default font size on wearable devices is 18 fp. 108 109**Atomic service API**: This API can be used in atomic services since API version 11. 110 111**System capability**: SystemCapability.ArkUI.ArkUI.Full 112 113**Parameters** 114 115| Name| Type | Mandatory| Description | 116| ------ | ------------------------ | ---- | ---------------------- | 117| value | [Font](ts-types.md#font) | No | Text font of the search text box.| 118 119### textAlign<sup>9+</sup> 120 121textAlign(value: TextAlign) 122 123Sets the text alignment mode in the search text box. Currently, the following alignment modes are supported: **Start**, **Center**, and **End**. 124 125**Atomic service API**: This API can be used in atomic services since API version 11. 126 127**System capability**: SystemCapability.ArkUI.ArkUI.Full 128 129**Parameters** 130 131| Name| Type | Mandatory| Description | 132| ------ | ------------------------------------------- | ---- | ------------------------------------------------------ | 133| value | [TextAlign](ts-appendix-enums.md#textalign) | Yes | Text alignment mode in the search text box.<br>Default value: **TextAlign.Start**| 134 135### copyOption<sup>9+</sup> 136 137copyOption(value: CopyOptions) 138 139Sets whether copy and paste is allowed. If this attribute is set to **CopyOptions.None**, the text can only be pasted; all other actions, such as copying, cutting, and sharing, are disabled. 140 141Dragging is not allowed when **CopyOptions.None** is set. 142 143**Atomic service API**: This API can be used in atomic services since API version 11. 144 145**System capability**: SystemCapability.ArkUI.ArkUI.Full 146 147**Parameters** 148 149| Name| Type | Mandatory| Description | 150| ------ | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 151| value | [CopyOptions](ts-appendix-enums.md#copyoptions9) | Yes | Whether copy and paste is allowed.<br>Default value: **CopyOptions.LocalDevice**| 152 153### searchIcon<sup>10+</sup> 154 155searchIcon(value: IconOptions | SymbolGlyphModifier) 156 157Sets the style of the search icon on the left. 158 159The default icon size on wearable devices is 16 vp. 160 161**Atomic service API**: This API can be used in atomic services since API version 11. 162 163**System capability**: SystemCapability.ArkUI.ArkUI.Full 164 165**Parameters** 166 167| Name| Type | Mandatory| Description | 168| ------ | ------------------------------------- | ---- | ------------------ | 169| value | [IconOptions](#iconoptions10) \| [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | Yes | Style of the search icon on the left.<!--RP1--><br>Default value in light mode:<br>{<br>size: '16vp',<br>color: '#99182431',<br>src: ' '<br>}<br>Default value in dark mode:<br>{<br>size: '16vp',<br>color: '#99ffffff',<br>src: ' '<br>} <!--RP1End-->| 170 171### cancelButton<sup>10+</sup> 172 173cancelButton(value: CancelButtonOptions | CancelButtonSymbolOptions) 174 175Sets the style of the Cancel button on the right. 176 177The default icon size on wearable devices is 18 vp. 178 179**Atomic service API**: This API can be used in atomic services since API version 11. 180 181**System capability**: SystemCapability.ArkUI.ArkUI.Full 182 183**Parameters** 184 185| Name| Type | Mandatory| Description | 186| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 187| value | [CancelButtonOptions](#cancelbuttonoptions12) \| [CancelButtonSymbolOptions](#cancelbuttonsymboloptions12) | Yes | Style of the Cancel button on the right.<br>Default value:<br>{<br>style: CancelButtonStyle.INPUT,<br>icon: {<br>size: '16vp',<br>color: '#99ffffff',<br>src: ' '<br>}<br>}<br>When **style** is set to **CancelButtonStyle.CONSTANT**, the Cancel button is always displayed.| 188 189### fontColor<sup>10+</sup> 190 191fontColor(value: ResourceColor) 192 193Sets the font color of the input text. [Universal text attributes](ts-universal-attributes-text-style.md) **fontSize**, **fontStyle**, **fontWeight**, and **fontFamily** are set in the [textFont](#textfont) attribute. 194 195The default value on wearable devices is **'#dbffffff'**. 196 197**Atomic service API**: This API can be used in atomic services since API version 11. 198 199**System capability**: SystemCapability.ArkUI.ArkUI.Full 200 201**Parameters** 202 203| Name| Type | Mandatory| Description | 204| ------ | ------------------------------------------ | ---- | ----------------------------------------------- | 205| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Font color of the input text.<br>Default value: **'#FF182431'**| 206 207### caretStyle<sup>10+</sup> 208 209caretStyle(value: CaretStyle) 210 211Sets the caret style. 212 213**Atomic service API**: This API can be used in atomic services since API version 11. 214 215**System capability**: SystemCapability.ArkUI.ArkUI.Full 216 217**Parameters** 218 219| Name| Type | Mandatory| Description | 220| ------ | ----------------------------------- | ---- | ------------------------------------------------------------ | 221| value | [CaretStyle](ts-text-common.md#caretstyle10) | Yes | Caret style.<br>Default value:<br>{<br>width: '1.5vp',<br>color: '#007DFF'<br>} | 222 223> **NOTE** 224> Since API version 12, this API can be used to set the text handle color, which is the same as the caret color. 225 226### enableKeyboardOnFocus<sup>10+</sup> 227 228enableKeyboardOnFocus(value: boolean) 229 230Sets whether to enable the input method when the **Search** component obtains focus in a way other than clicking. 231 232Since API version 10, the **Search** component brings up the keyboard by default when it obtains focus. 233 234**Atomic service API**: This API can be used in atomic services since API version 11. 235 236**System capability**: SystemCapability.ArkUI.ArkUI.Full 237 238**Parameters** 239 240| Name| Type | Mandatory| Description | 241| ------ | ------- | ---- | ----------------------------------------------- | 242| value | boolean | Yes | Whether to enable the input method when the component obtains focus in a way other than clicking.<br>Default value: **true**| 243 244### selectionMenuHidden<sup>10+</sup> 245 246selectionMenuHidden(value: boolean) 247 248Sets whether to hide the system text selection menu. 249 250**Atomic service API**: This API can be used in atomic services since API version 11. 251 252**System capability**: SystemCapability.ArkUI.ArkUI.Full 253 254**Parameters** 255 256| Name| Type | Mandatory| Description | 257| ------ | ------- | ---- | ------------------------------------------------------------ | 258| value | boolean | Yes | Whether to hide the system text selection menu.<br>**true**: Tapping, long-pressing, double-tapping, triple-tapping, or right-clicking the text box will not trigger the system text selection menu.<br>**false**: Tapping, long-pressing, double-tapping, triple-tapping, or right-clicking the text box will trigger the system text selection menu.<br>Default value: **false**| 259 260### customKeyboard<sup>10+</sup> 261 262customKeyboard(value: CustomBuilder, options?: KeyboardOptions) 263 264Sets the custom keyboard. 265 266When a custom keyboard is set, activating the text box opens the specified custom component, instead of the system input method. 267 268The 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. 269 270The custom keyboard is presented by overlaying the original screen. It is not compressed or lifted if avoid mode is not enabled or avoidance is not needed for the text box. 271 272The custom keyboard cannot obtain the focus, but it blocks gesture events. 273 274By 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. 275 276When a custom keyboard is set, the text box does not support camera input, even when the device supports. 277 278When setting a custom keyboard, you can bind the [onKeyPrelme](ts-universal-events-key.md#onkeypreime12) event to prevent input from the physical keyboard. 279 280**Atomic service API**: This API can be used in atomic services since API version 11. 281 282**System capability**: SystemCapability.ArkUI.ArkUI.Full 283 284**Parameters** 285 286| Name | Type | Mandatory| Description | 287| --------------------- | ------------------------------------------- | ---- | -------------------------------- | 288| value | [CustomBuilder](ts-types.md#custombuilder8) | Yes | Custom keyboard. | 289| options<sup>12+</sup> | [KeyboardOptions](ts-basic-components-richeditor.md#keyboardoptions12) | No | Whether to support keyboard avoidance.| 290 291### type<sup>11+</sup> 292 293type(value: SearchType) 294 295Sets the text box type. 296 297**Atomic service API**: This API can be used in atomic services since API version 12. 298 299**System capability**: SystemCapability.ArkUI.ArkUI.Full 300 301**Parameters** 302 303| Name| Type | Mandatory| Description | 304| ------ | ----------------------------------- | ---- | -------------------------- | 305| value | [SearchType](#searchtype11) | Yes | Text box type.<br>Default value: **SearchType.Normal**| 306 307### maxLength<sup>11+</sup> 308 309maxLength(value: number) 310 311Sets the maximum number of characters for text input. By default, there is no maximum number of characters. When the maximum number is reached, no more characters can be entered. 312 313**Atomic service API**: This API can be used in atomic services since API version 12. 314 315**System capability**: SystemCapability.ArkUI.ArkUI.Full 316 317**Parameters** 318 319| Name| Type | Mandatory| Description | 320| ------ | ----------------------------------- | ---- | ---------------------- | 321| value | number | Yes | Maximum number of characters for text input.| 322 323### enterKeyType<sup>12+</sup> 324 325enterKeyType(value: EnterKeyType) 326 327Sets the type of the Enter key. 328 329**Atomic service API**: This API can be used in atomic services since API version 12. 330 331**System capability**: SystemCapability.ArkUI.ArkUI.Full 332 333**Parameters** 334 335| Name| Type | Mandatory| Description | 336| ------ | ------------------------------------------------ | ---- | -------------------------------------------------- | 337| value | [EnterKeyType](ts-basic-components-textinput.md#enterkeytype) | Yes | Type of the Enter key.<br>Default value: **EnterKeyType.Search**| 338 339### lineHeight<sup>12+</sup> 340 341lineHeight(value: number | string | Resource) 342 343Sets the text line height. If the value is less than or equal to **0**, the line height is not limited and the font size is adaptive. If the value is of the number type, the unit fp is used. 344 345**Atomic service API**: This API can be used in atomic services since API version 12. 346 347**System capability**: SystemCapability.ArkUI.ArkUI.Full 348 349**Parameters** 350 351| Name| Type | Mandatory| Description | 352| ------ | ------------------------------------------------------------ | ---- | ---------------- | 353| value | number \| string \| [Resource](ts-types.md#resource) | Yes | Text line height.| 354 355### decoration<sup>12+</sup> 356 357decoration(value: TextDecorationOptions) 358 359Sets the color, type, and style of the text decorative line. 360 361**Atomic service API**: This API can be used in atomic services since API version 12. 362 363**System capability**: SystemCapability.ArkUI.ArkUI.Full 364 365**Parameters** 366 367| Name| Type | Mandatory| Description | 368| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 369| value | [TextDecorationOptions](ts-types.md#textdecorationoptions12) | Yes | Text decorative line options.<br>Default value: {<br> type: TextDecorationType.None,<br> color: Color.Black,<br> style: TextDecorationStyle.SOLID <br>} | 370 371### letterSpacing<sup>12+</sup> 372 373letterSpacing(value: number | string | Resource) 374 375Sets the letter spacing for a text style. If the value specified is a percentage or 0, the default value is used. For the string type, numeric string values with optional units, for example, **"10"** or **"10fp"**, are supported. 376 377If the value specified is a negative value, the text is compressed. A negative value too small may result in the text being compressed to 0 and no content being displayed. 378 379**Atomic service API**: This API can be used in atomic services since API version 12. 380 381**System capability**: SystemCapability.ArkUI.ArkUI.Full 382 383**Parameters** 384 385| Name| Type | Mandatory| Description | 386| ------ | -------------------------- | ---- | -------------- | 387| value | number \| string \| [Resource](ts-types.md#resource) | Yes | Letter spacing.<br>Unit: fp| 388 389### fontFeature<sup>12+</sup> 390 391fontFeature(value: string) 392 393Sets the font feature, for example, monospaced digits. 394 395Format: normal \| \<feature-tag-value\> 396 397Format of **\<feature-tag-value\>**: \<string\> \[ \<integer\> \| on \| off ] 398 399There can be multiple **\<feature-tag-value\>** values, which are separated by commas (,). 400 401For example, the input format for monospaced clock fonts is "ss01" on. 402 403**Atomic service API**: This API can be used in atomic services since API version 12. 404 405**System capability**: SystemCapability.ArkUI.ArkUI.Full 406 407**Parameters** 408 409| Name| Type | Mandatory| Description | 410| ------ | ------ | ---- | -------------- | 411| value | string | Yes | Font feature.| 412 413For details about the supported font features, see [Font Feature List](ts-basic-components-text.md#fontfeature12). 414Font features are advanced typographic features, such as ligatures and monospace, for OpenType fonts. They are typically used in custom fonts and require the support of the font itself. 415For more information about the font features, see [Low-level font feature settings control: the font-feature-settings property](https://www.w3.org/TR/css-fonts-3/#font-feature-settings-prop) and [The Complete CSS Demo for OpenType Features](https://sparanoid.com/lab/opentype-features/). 416 417### selectedBackgroundColor<sup>12+</sup> 418 419selectedBackgroundColor(value: ResourceColor) 420 421Sets the background color of the selected text. If the opacity is not set, a 20% opacity will be used. 422 423**Atomic service API**: This API can be used in atomic services since API version 12. 424 425**System capability**: SystemCapability.ArkUI.ArkUI.Full 426 427**Parameters** 428 429| Name| Type | Mandatory| Description | 430| ------ | ------------------------------------------ | ---- | ------------------------------------------ | 431| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Background color of the selected text.<br>By default, a 20% opacity is applied.| 432 433### inputFilter<sup>12+</sup> 434 435inputFilter(value: ResourceStr, error?: Callback< string >) 436 437Sets the regular expression for input filtering. Only inputs that comply with the regular expression can be displayed. Other inputs are filtered out. The specified regular expression can match single characters, but not strings. 438 439If **inputFilter** is set and the entered characters are not null, the filtering effect attached to the text box type (specified through the **type** attribute) does not take effect. 440 441**Atomic service API**: This API can be used in atomic services since API version 12. 442 443**System capability**: SystemCapability.ArkUI.ArkUI.Full 444 445**Parameters** 446 447| Name| Type | Mandatory| Description | 448| ------ | -------------------------------------- | ---- | ---------------------------------- | 449| value | [ResourceStr](ts-types.md#resourcestr) | Yes | Regular expression. | 450| error | Callback< string > | No | Filtered-out content to return when regular expression matching fails.| 451 452### textIndent<sup>12+</sup> 453 454textIndent(value: Dimension) 455 456Sets the indent of the first line text. 457 458**Atomic service API**: This API can be used in atomic services since API version 12. 459 460**System capability**: SystemCapability.ArkUI.ArkUI.Full 461 462**Parameters** 463 464| Name| Type | Mandatory| Description | 465| ------ | ----------------------------------- | ---- | ---------------------------- | 466| value | [Dimension](ts-types.md#dimension10)| Yes | Indent of the first line text.<br>Default value: **0** | 467 468### minFontSize<sup>12+</sup> 469 470minFontSize(value: number | string | Resource) 471 472Sets the minimum font size. For the string type, numeric string values with optional units, for example, **"10"** or **"10fp"**, are supported. 473 474For the setting to take effect, this attribute must be used together with [maxFontSize](#maxfontsize12) or layout constraint settings. 475 476When the adaptive font size is used, the **fontSize** settings do not take effect. 477 478**Atomic service API**: This API can be used in atomic services since API version 12. 479 480**System capability**: SystemCapability.ArkUI.ArkUI.Full 481 482**Parameters** 483 484| Name| Type | Mandatory| Description | 485| ------ | ------------------------------------------------------------ | ---- | ------------------ | 486| value | number \| string \| [Resource](ts-types.md#resource) | Yes | Minimum font size.<br>Unit: fp| 487 488### maxFontSize<sup>12+</sup> 489 490maxFontSize(value: number | string | Resource) 491 492Sets the maximum font size. For the string type, numeric string values with optional units, for example, **"10"** or **"10fp"**, are supported. 493 494For the setting to take effect, this attribute must be used together with [minFontSize](#minfontsize12) or layout constraint settings. 495 496When the adaptive font size is used, the **fontSize** settings do not take effect. 497 498**Atomic service API**: This API can be used in atomic services since API version 12. 499 500**System capability**: SystemCapability.ArkUI.ArkUI.Full 501 502**Parameters** 503 504| Name| Type | Mandatory| Description | 505| ------ | ------------------------------------------------------------ | ---- | ------------------ | 506| value | number \| string \| [Resource](ts-types.md#resource) | Yes | Maximum font size.<br>Unit: fp| 507 508### halfLeading<sup>18+</sup> 509 510halfLeading(halfLeading: Optional\<boolean>) 511 512Sets whether half leading is enabled. 513 514**Atomic service API**: This API can be used in atomic services since API version 18. 515 516**System capability**: SystemCapability.ArkUI.ArkUI.Full 517 518**Parameters** 519 520| Name| Type | Mandatory| Description | 521| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 522| halfLeading | [Optional](ts-universal-attributes-custom-property.md#optional12)\<boolean> | Yes | Whether half leading is enabled.<br>Half leading is the leading split in half and applied equally to the top and bottom edges. The value **true** means that half leading is enabled, and **false** means the opposite.<br>Default value: **false**| 523 524### minFontScale<sup>18+</sup> 525 526minFontScale(scale: Optional\<number | Resource>) 527 528Sets the minimum font scale factor for text. 529 530**Atomic service API**: This API can be used in atomic services since API version 18. 531 532**System capability**: SystemCapability.ArkUI.ArkUI.Full 533 534**Parameters** 535 536| Name| Type | Mandatory| Description | 537| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 538| scale | [Optional](ts-universal-attributes-custom-property.md#optional12)\<number \| [Resource](ts-types.md#resource)> | Yes | Minimum font scale factor for text. The **undefined** type is supported.<br>Value range: [0, 1]<br>**NOTE**<br>A value less than 0 is handled as 0. A value greater than 1 is handled as 1. Abnormal values are ineffective by default.| 539 540### maxFontScale<sup>18+</sup> 541 542maxFontScale(scale: Optional\<number | Resource>) 543 544Sets the maximum font scale factor for text. 545 546**Atomic service API**: This API can be used in atomic services since API version 18. 547 548**System capability**: SystemCapability.ArkUI.ArkUI.Full 549 550**Parameters** 551 552| Name| Type | Mandatory| Description | 553| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 554| scale | [Optional](ts-universal-attributes-custom-property.md#optional12)\<number \| [Resource](ts-types.md#resource)> | Yes | Maximum font scale factor for text. The **undefined** type is supported.<br>Value range: [1, +∞)<br>**NOTE**<br>A value less than 1 is handled as 1. Abnormal values are ineffective by default.| 555 556### editMenuOptions<sup>12+</sup> 557 558editMenuOptions(editMenu: EditMenuOptions) 559 560Sets the extended options of the custom context menu on selection, including the text content, icon, and callback. 561 562**Atomic service API**: This API can be used in atomic services since API version 12. 563 564**System capability**: SystemCapability.ArkUI.ArkUI.Full 565 566**Parameters** 567 568| Name| Type | Mandatory| Description | 569| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 570| editMenu | [EditMenuOptions](ts-text-common.md#editmenuoptions) | Yes | Extended options of the custom context menu on selection.| 571 572### enablePreviewText<sup>12+</sup> 573 574enablePreviewText(enable: boolean) 575 576Sets whether to enable preview text. 577 578Preview text is in a temporary state and does not support text interception. As such, it does not trigger **onWillInsert**, **onDidInsert**, **onWillDelete**, or **onDidDelete** callbacks. 579 580**Atomic service API**: This API can be used in atomic services since API version 12. 581 582**System capability**: SystemCapability.ArkUI.ArkUI.Full 583 584**Parameters** 585 586| Name| Type | Mandatory| Description | 587| ------ | ------- | ---- | ---------------------------------- | 588| enable | boolean | Yes | Whether to enable preview text.<br>Default value: **true**| 589 590### enableHapticFeedback<sup>13+</sup> 591 592enableHapticFeedback(isEnabled: boolean) 593 594Specifies whether to enable haptic feedback. 595 596**Atomic service API**: This API can be used in atomic services since API version 13. 597 598**System capability**: SystemCapability.ArkUI.ArkUI.Full 599 600**Parameters** 601 602| Name| Type | Mandatory| Description | 603| ------ | ------- | ---- | ---------------------------------- | 604| isEnabled | boolean | Yes | Whether to enable haptic feedback.<br>Default value: **true**| 605 606> **NOTE** 607> 608> To enable haptic feedback, you must declare the ohos.permission.VIBRATE permission under **requestPermissions** in the **module.json5** file of the project. 609> ```json 610> "requestPermissions": [ 611> { 612> "name": "ohos.permission.VIBRATE", 613> } 614> ] 615> ``` 616 617### keyboardAppearance<sup>15+</sup> 618 619keyboardAppearance(appearance: Optional\<KeyboardAppearance>) 620 621Sets the appearance of the keyboard when the text box is focused. 622 623**Atomic service API**: This API can be used in atomic services since API version 15. 624 625**System capability**: SystemCapability.ArkUI.ArkUI.Full 626 627**Parameters** 628 629| Name| Type| Mandatory| Description| 630| ------ | ----------------------------------------- | ---- | ------------------------------------------------------ | 631| appearance | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[KeyboardAppearance](ts-text-common.md#keyboardappearance15)> | Yes | Appearance of the keyboard.<br>Default value: **KeyboardAppearance.NONE_IMMERSIVE**| 632 633### stopBackPress<sup>15+</sup> 634 635stopBackPress(isStopped: Optional\<boolean>) 636 637Sets whether to prevent the back button press from being propagated to other components or applications. 638 639**Atomic service API**: This API can be used in atomic services since API version 15. 640 641**System capability**: SystemCapability.ArkUI.ArkUI.Full 642 643**Parameters** 644 645| Name| Type | Mandatory| Description | 646| ------ | ------- | ---- | ---------------------------------- | 647| isStopped | [Optional](ts-universal-attributes-custom-property.md#optional12)\<boolean> | Yes | Whether to consume the back button press.<br>Default value: **true**| 648 649## IconOptions<sup>10+</sup> 650 651**Atomic service API**: This API can be used in atomic services since API version 11. 652 653**System capability**: SystemCapability.ArkUI.ArkUI.Full 654 655| Name| Type | Mandatory| Description | 656| ------ | ------------------------------------------ | ---- | ----------- | 657| size | [Length](ts-types.md#length) | No | Icon size. It cannot be set in percentage. | 658| color | [ResourceColor](ts-types.md#resourcecolor) | No | Icon color. | 659| src | [ResourceStr](ts-types.md#resourcestr) | No | Image source of the icon.| 660 661## SearchButtonOptions<sup>10+</sup> 662 663**System capability**: SystemCapability.ArkUI.ArkUI.Full 664 665| Name | Type | Mandatory| Description | 666| --------- | ------------------------------------------ | ---- | ---------------- | 667| fontSize | [Length](ts-types.md#length) | No | Font size of the button. It cannot be set in percentage. **Atomic service API**: This API can be used in atomic services since API version 11.| 668| fontColor | [ResourceColor](ts-types.md#resourcecolor) | No | Font color of the button. **Atomic service API**: This API can be used in atomic services since API version 11.| 669| autoDisable<sup>18+</sup> | Boolean | No | Whether to disable the search button when there is no text input.<br>Default value: **false**<br>**true**: The search button is disabled when there is no text input.<br>**false**: The search button remains enabled regardless of the text input.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 670 671## CancelButtonStyle<sup>10+</sup> 672 673**Atomic service API**: This API can be used in atomic services since API version 11. 674 675**System capability**: SystemCapability.ArkUI.ArkUI.Full 676 677| Name | Description | 678| ----------------------- | ---------------- | 679| CONSTANT | The Cancel button is always displayed.| 680| INVISIBLE | The Cancel button is always hidden.| 681| INPUT | The Cancel button is displayed when there is text input.| 682 683## SearchType<sup>11+</sup> 684 685**Atomic service API**: This API can be used in atomic services since API version 12. 686 687**System capability**: SystemCapability.ArkUI.ArkUI.Full 688 689| Name | Value | Description | 690| ------------------ | ------ | ------------- | 691| NORMAL | 0 | Normal input mode.<br>The value can contain digits, letters, underscores (_), spaces, and special characters.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 692| NUMBER | 2 | Digit input mode.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 693| PHONE_NUMBER | 3 | Phone number input mode.<br>In this mode, the following are allowed: digits, spaces, plus signs (+), hyphens (-), asterisks (*), and number signs (#); the length is not limited.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 694| EMAIL | 5 | Email address input mode.<br>This mode accepts only digits, letters, underscores (_), dots (.), and the following special characters: ! # $ % & ' * + - / = ? ^ ` \{ \| \} ~ @ (which can only appear once)<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 695| NUMBER_DECIMAL<sup>12+</sup> | 12 | Number input mode with a decimal point.<br>The value can contain digits and one decimal point.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 696| URL<sup>12+</sup> | 13 | URL input mode.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 697 698## CancelButtonOptions<sup>12+</sup> 699 700**Atomic service API**: This API can be used in atomic services since API version 12. 701 702**System capability**: SystemCapability.ArkUI.ArkUI.Full 703 704| Name | Type | Mandatory| Description | 705| --------- | ------------------------------------------ | ---- | ---------------- | 706| style | [CancelButtonStyle](#cancelbuttonstyle10) | No | Display state of the Cancel button on the right.| 707| icon | [IconOptions](#iconoptions10) | No | Icon of the Cancel button on the right.| 708 709## CancelButtonSymbolOptions<sup>12+</sup> 710 711**Atomic service API**: This API can be used in atomic services since API version 12. 712 713**System capability**: SystemCapability.ArkUI.ArkUI.Full 714 715| Name | Type | Mandatory| Description | 716| --------- | ------------------------------------------ | ---- | ---------------- | 717| style | [CancelButtonStyle](#cancelbuttonstyle10) | No | Display state of the Cancel button on the right.| 718| icon | [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | No | Symbol icon of the Cancel button on the right.| 719 720## Events 721 722In addition to the [universal events](ts-component-general-events.md), the following events are supported. 723 724### onSubmit 725 726onSubmit(callback: Callback\<string>) 727 728Invoked when users click the search icon or the search button, or touch the search button on a soft keyboard. 729 730**Atomic service API**: This API can be used in atomic services since API version 11. 731 732**System capability**: SystemCapability.ArkUI.ArkUI.Full 733 734**Parameters** 735 736| Name| Type | Mandatory| Description | 737| ------ | ------ | ---- | ---------------------------- | 738| callback | Callback\<string> | Yes | Search submission callback, which returns the text content currently in the search box.| 739 740### onSubmit<sup>14+</sup> 741 742onSubmit(callback: SearchSubmitCallback) 743 744Invoked when the search icon, search button, or soft keyboard search button is clicked. The submission event provides a method to maintain the edit state of the **Search** component. 745 746**Atomic service API**: This API can be used in atomic services since API version 14. 747 748**System capability**: SystemCapability.ArkUI.ArkUI.Full 749 750**Parameters** 751 752| Name| Type | Mandatory| Description | 753| ------ | ------- | ---- | ----------------------------- | 754| callback | [SearchSubmitCallback](#searchsubmitcallback14) | Yes | Callback triggered when the search icon, search button, or soft keyboard search button is clicked.| 755 756### onChange 757 758onChange(callback: EditableTextOnChangeCallback) 759 760Invoked when the input in the text box changes. 761 762In this callback, if cursor operations are performed, developers need to adjust the cursor logic based on the **previewText** parameter to ensure it works seamlessly within the preview display scenario. 763 764**Atomic service API**: This API can be used in atomic services since API version 11. 765 766**System capability**: SystemCapability.ArkUI.ArkUI.Full 767 768**Parameters** 769 770| Name| Type | Mandatory| Description | 771| ------ | ------ | ---- | ---------------------------- | 772| callback | [EditableTextOnChangeCallback](ts-text-common.md#editabletextonchangecallback12) | Yes | Callback invoked when the input in the text box changes.| 773 774### onCopy 775 776onCopy(callback:Callback\<string>) 777 778Invoked when a copy operation is performed. 779 780**Atomic service API**: This API can be used in atomic services since API version 11. 781 782**System capability**: SystemCapability.ArkUI.ArkUI.Full 783 784**Parameters** 785 786| Name | Type | Mandatory| Description | 787| --------- | ------- | ---- | ---------------- | 788| callback | Callback\<string> | Yes | Callback used to return the copied text content.| 789 790### onCut 791 792onCut(callback:Callback\<string>) 793 794Invoked when a cut operation is performed. 795 796**Atomic service API**: This API can be used in atomic services since API version 11. 797 798**System capability**: SystemCapability.ArkUI.ArkUI.Full 799 800**Parameters** 801 802| Name | Type | Mandatory| Description | 803| --------- | ------- | ---- | ---------------- | 804| callback | Callback\<string> | Yes | Callback used to return the cut text content.| 805 806### onPaste 807 808onPaste(callback:OnPasteCallback ) 809 810Invoked when a paste operation is performed. 811 812**Atomic service API**: This API can be used in atomic services since API version 11. 813 814**System capability**: SystemCapability.ArkUI.ArkUI.Full 815 816**Parameters** 817| Name | Type | Mandatory| Description | 818| ------------------- | ------------------------------------------------------------ | ---- | ---------------------- | 819| callback | [OnPasteCallback](ts-basic-components-textinput.md#onpastecallback18) | Yes | Callback used to return the pasted text content.| 820 821### onTextSelectionChange<sup>10+</sup> 822 823onTextSelectionChange(callback: OnTextSelectionChangeCallback) 824 825Invoked when the position of the text selection changes or when the cursor position changes during the editing state. 826 827**Atomic service API**: This API can be used in atomic services since API version 11. 828 829**System capability**: SystemCapability.ArkUI.ArkUI.Full 830 831**Parameters** 832 833| Name | Type | Mandatory| Description | 834| -------------- | ------ | ---- | ------------------------------------------------- | 835| callback | [OnTextSelectionChangeCallback](ts-basic-components-textinput.md#ontextselectionchangecallback18) | Yes | Callback for text selection changes or cursor position changes.| 836 837### onContentScroll<sup>10+</sup> 838 839onContentScroll(callback: OnContentScrollCallback) 840 841Invoked when the text content is scrolled. 842 843**Atomic service API**: This API can be used in atomic services since API version 11. 844 845**System capability**: SystemCapability.ArkUI.ArkUI.Full 846 847**Parameters** 848 849| Name | Type | Mandatory| Description | 850| ------------ | ------ | ---- | ---------------------------------- | 851| callback | [OnContentScrollCallback](ts-basic-components-textinput.md#oncontentscrollcallback18) | Yes | Callback for text content scrolling.| 852 853### onEditChange<sup>12+</sup> 854 855onEditChange(callback: Callback< boolean >) 856 857Invoked when the input status changes. The text box is in the editing state when it has the caret placed in it, and is in the non-editing state otherwise. The callback returns **true** when the component is in an editing state. 858 859**Atomic service API**: This API can be used in atomic services since API version 12. 860 861**System capability**: SystemCapability.ArkUI.ArkUI.Full 862 863**Parameters** 864 865| Name | Type | Mandatory| Description | 866| --------- | ---------------------------------- | ---- | -------------------- | 867| callback | Callback< boolean > | Yes | Callback triggered when the editing state changes. Returns **true** if the component is in an editing state.| 868 869### onWillInsert<sup>12+</sup> 870 871onWillInsert(callback: Callback\<InsertValue, boolean>) 872 873Invoked when text is about to be inserted. 874 875**Atomic service API**: This API can be used in atomic services since API version 12. 876 877**System capability**: SystemCapability.ArkUI.ArkUI.Full 878 879**Parameters** 880 881| Name| Type | Mandatory| Description | 882| ------ | ------------------------------------------------------------ | ---- | ------------------ | 883| callback | Callback\<[InsertValue](ts-text-common.md#insertvalue12), boolean> | Yes | Callback invoked when text is about to be inserted.<br>It returns **true** if the text is inserted; returns **false** otherwise.<br>This callback is not triggered for pre-edit or candidate word operations.<br>It is available only for system input methods.| 884 885### onDidInsert<sup>12+</sup> 886 887onDidInsert(callback: Callback\<InsertValue>) 888 889Invoked when text is inserted. 890 891**Atomic service API**: This API can be used in atomic services since API version 12. 892 893**System capability**: SystemCapability.ArkUI.ArkUI.Full 894 895**Parameters** 896 897| Name| Type | Mandatory| Description | 898| ------ | ------------------------------------------------------------ | ---- | ------------------ | 899| callback | Callback\<[InsertValue](ts-text-common.md#insertvalue12)> | Yes | Callback invoked when text is inserted.<br>It is available only for system input methods.| 900 901### onWillDelete<sup>12+</sup> 902 903onWillDelete(callback: Callback\<DeleteValue, boolean>) 904 905Invoked when text is about to be deleted. 906 907**Atomic service API**: This API can be used in atomic services since API version 12. 908 909**System capability**: SystemCapability.ArkUI.ArkUI.Full 910 911**Parameters** 912 913| Name| Type | Mandatory| Description | 914| ------ | ------------------------------------------------------------ | ---- | ------------------ | 915| callback | Callback\<[DeleteValue](ts-text-common.md#deletevalue12), boolean> | Yes | Callback invoked when text is about to be deleted.<br>It returns **true** if the text is deleted; returns **false** otherwise.<br>This callback is not invoked for text preview.<br>It is available only for system input methods.| 916 917### onDidDelete<sup>12+</sup> 918 919onDidDelete(callback: Callback\<DeleteValue>) 920 921Called when text is deleted. 922 923**Atomic service API**: This API can be used in atomic services since API version 12. 924 925**System capability**: SystemCapability.ArkUI.ArkUI.Full 926 927**Parameters** 928 929| Name| Type | Mandatory| Description | 930| ------ | ------------------------------------------------------------ | ---- | ------------------ | 931| callback | Callback\<[DeleteValue](ts-text-common.md#deletevalue12)> | Yes | Callback invoked when text is deleted.<br>It is available only for system input methods.| 932 933### onWillChange<sup>15+</sup> 934 935onWillChange(callback: Callback\<EditableTextChangeValue, boolean>) 936 937Called when the text content is about to change. 938 939This callback is triggered after **onWillInsert** and **onWillDelete**, but before **onDidInsert** and **onDidDelete**. 940 941**Atomic service API**: This API can be used in atomic services since API version 15. 942 943**System capability**: SystemCapability.ArkUI.ArkUI.Full 944 945**Parameters** 946 947| Name| Type | Mandatory| Description | 948| ------ | ------------------------------------------------------------ | ---- | ------------------ | 949| callback | Callback\<[EditableTextChangeValue](ts-text-common.md#editabletextchangevalue15), boolean> | Yes | Callback triggered when the text content is about to change.<br>Returning **true** allows the change to proceed, while returning **false** cancels the change.| 950 951## SearchController 952 953Inherits from [TextContentControllerBase](ts-types.md#textcontentcontrollerbase10). 954 955### Objects to Import 956``` 957controller: SearchController = new SearchController() 958``` 959 960### constructor<sup>8+</sup> 961 962constructor() 963 964A constructor used to create a **SearchController** object. 965 966**Atomic service API**: This API can be used in atomic services since API version 11. 967 968**System capability**: SystemCapability.ArkUI.ArkUI.Full 969 970### caretPosition<sup>8+</sup> 971 972caretPosition(value: number): void 973 974Sets the position of the caret. 975 976**Atomic service API**: This API can be used in atomic services since API version 11. 977 978**System capability**: SystemCapability.ArkUI.ArkUI.Full 979 980**Parameters** 981 982| Name| Type| Mandatory| Description | 983| ------ | -------- | ---- | ---------------------------------- | 984| value | number | Yes | Length from the start of the character string to the position where the caret is located.| 985 986### stopEditing<sup>10+</sup> 987 988stopEditing(): void 989 990Exits the editing state. 991 992**Atomic service API**: This API can be used in atomic services since API version 11. 993 994**System capability**: SystemCapability.ArkUI.ArkUI.Full 995 996### setTextSelection<sup>12+</sup> 997 998setTextSelection(selectionStart: number, selectionEnd: number, options?: SelectionOptions): void; 999 1000Sets the text selection range and highlights the selected text when the component is focused. This API works only when the value of **selectionStart** is less than that of **selectionEnd**. 1001 1002**Atomic service API**: This API can be used in atomic services since API version 12. 1003 1004**System capability**: SystemCapability.ArkUI.ArkUI.Full 1005 1006**Parameters** 1007 1008| Name | Type| Mandatory| Description | 1009| -------------- | -------- | ---- | -------- | 1010| selectionStart | number | Yes | Start position of the text selection range. The start position of text in the text box is 0.<br>A value less than 0 is handled as **0**. A value greater than the maximum text length is handled as the maximum text length.<br>| 1011| selectionEnd | number | Yes | End position of the text selection range.<br>A value less than 0 is handled as the value **0**. A value greater than the maximum text length is handled as the maximum text length.<br>| 1012| options | [SelectionOptions](ts-types.md#selectionoptions12) | No | Configuration options for text selection.<br>Default value: **MenuPolicy.DEFAULT**| 1013 1014> **NOTE** 1015> 1016> If **selectionStart** or **selectionEnd** is set to **undefined**, the value **0** will be used. 1017> 1018> If **selectionMenuHidden** is set to **true** or a 2-in-1 device is used, calling **setTextSelection** does not display the context menu even when **options** is set to **MenuPolicy.SHOW**. 1019> 1020> If the selected text contains an emoji, the emoji is selected when its start position is within the text selection range. 1021 1022## SearchSubmitCallback<sup>14+</sup> 1023 1024type SearchSubmitCallback = (searchContent: string, event?: SubmitEvent) => void 1025 1026Represents the callback triggered when the search icon, search button, or soft keyboard search button is clicked. 1027 1028**Atomic service API**: This API can be used in atomic services since API version 14. 1029 1030**System capability**: SystemCapability.ArkUI.ArkUI.Full 1031 1032**Parameters** 1033 1034| Name | Type | Mandatory| Description | 1035| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- | 1036| searchContent | string | Yes | Current text input.| 1037| event | [SubmitEvent](ts-basic-components-textinput.md#submitevent11) | No | Submit event. | 1038 1039## Example 1040 1041### Example 1: Setting and Obtaining the Cursor Position 1042 1043This example demonstrates how to use the controller to set and obtain the cursor position within a text box. 1044 1045```ts 1046// xxx.ets 1047@Entry 1048@Component 1049struct SearchExample { 1050 @State changeValue: string = '' 1051 @State submitValue: string = '' 1052 @State positionInfo: CaretOffset = { index: 0, x: 0, y: 0 } 1053 controller: SearchController = new SearchController() 1054 1055 build() { 1056 Column({space: 10}) { 1057 Text('onSubmit:' + this.submitValue).fontSize(18).margin(15) 1058 Text('onChange:' + this.changeValue).fontSize(18).margin(15) 1059 Search({ value: this.changeValue, placeholder: 'Type to search...', controller: this.controller }) 1060 .searchButton('SEARCH') 1061 .width('95%') 1062 .height(40) 1063 .backgroundColor('#F5F5F5') 1064 .placeholderColor(Color.Grey) 1065 .placeholderFont({ size: 14, weight: 400 }) 1066 .textFont({ size: 14, weight: 400 }) 1067 .onSubmit((value: string) => { 1068 this.submitValue = value 1069 }) 1070 .onChange((value: string) => { 1071 this.changeValue = value 1072 }) 1073 .margin(20) 1074 Button('Set caretPosition 1') 1075 .onClick(() => { 1076 // Move the caret to after the first entered character. 1077 this.controller.caretPosition(1) 1078 }) 1079 Button('Get CaretOffset') 1080 .onClick(() => { 1081 this.positionInfo = this.controller.getCaretOffset() 1082 }) 1083 }.width('100%') 1084 } 1085} 1086``` 1087 1088 1089 1090### Example 2: Setting Search and Delete Icons 1091 1092This example demonstrates how to set search and delete icons using the **searchButton**, **searchIcon**, and **cancelButton** attributes. 1093 1094```ts 1095// xxx.ets 1096@Entry 1097@Component 1098struct SearchExample { 1099 @State changeValue: string = '' 1100 @State submitValue: string = '' 1101 1102 build() { 1103 Column() { 1104 Text('onSubmit:' + this.submitValue).fontSize(18).margin(15) 1105 Search({ value: this.changeValue, placeholder: 'Type to search...' }) 1106 .searchButton('SEARCH') 1107 .searchIcon({ 1108 src: $r('sys.media.ohos_ic_public_search_filled') 1109 }) 1110 .cancelButton({ 1111 style: CancelButtonStyle.CONSTANT, 1112 icon: { 1113 src: $r('sys.media.ohos_ic_public_cancel_filled') 1114 } 1115 }) 1116 .width('90%') 1117 .height(40) 1118 .maxLength(20) 1119 .backgroundColor('#F5F5F5') 1120 .placeholderColor(Color.Grey) 1121 .placeholderFont({ size: 14, weight: 400 }) 1122 .textFont({ size: 14, weight: 400 }) 1123 .onSubmit((value: string) => { 1124 this.submitValue = value 1125 }) 1126 .onChange((value: string) => { 1127 this.changeValue = value 1128 }) 1129 .margin(20) 1130 }.width('100%') 1131 } 1132} 1133``` 1134 1135 1136 1137 1138### Example 3: Implementing a Custom Keyboard 1139 1140This example demonstrates how to implement a custom keyboard using the **customKeyboard** attribute. 1141 1142```ts 1143// xxx.ets 1144@Entry 1145@Component 1146struct SearchExample { 1147 controller: SearchController = new SearchController() 1148 @State inputValue: string = "" 1149 1150 // Create a custom keyboard component. 1151 @Builder CustomKeyboardBuilder() { 1152 Column() { 1153 Button('x').onClick(() => { 1154 // Disable the custom keyboard. 1155 this.controller.stopEditing() 1156 }) 1157 Grid() { 1158 ForEach([1, 2, 3, 4, 5, 6, 7, 8, 9, '*', 0, '#'], (item: number | string) => { 1159 GridItem() { 1160 Button(item + "") 1161 .width(110).onClick(() => { 1162 this.inputValue += item 1163 }) 1164 } 1165 }) 1166 }.maxCount(3).columnsGap(10).rowsGap(10).padding(5) 1167 }.backgroundColor(Color.Gray) 1168 } 1169 1170 build() { 1171 Column() { 1172 Search({ controller: this.controller, value: this.inputValue}) 1173 // Bind the custom keyboard. 1174 .customKeyboard(this.CustomKeyboardBuilder()).margin(10).border({ width: 1 }) 1175 } 1176 } 1177} 1178``` 1179 1180 1181 1182### Example 4: Setting the Enter Key Type 1183 1184This example shows how to use the **enterKeyType** attribute to dynamically change the effect of the Enter key on the soft keyboard. 1185 1186```ts 1187// xxx.ets 1188@Entry 1189@Component 1190struct SearchExample { 1191 @State text: string = '' 1192 @State enterTypes: Array<EnterKeyType> = [EnterKeyType.Go, EnterKeyType.Search, EnterKeyType.Send, EnterKeyType.Done, EnterKeyType.Next, EnterKeyType.PREVIOUS, EnterKeyType.NEW_LINE] 1193 @State index: number = 0 1194 build() { 1195 Column({ space: 20 }) { 1196 Search({ placeholder: 'Enter text', value: this.text }) 1197 .width(380) 1198 .enterKeyType(this.enterTypes[this.index]) 1199 .onChange((value: string) => { 1200 this.text = value 1201 }) 1202 .onSubmit((value: String) => { 1203 console.log("trigger search onsubmit" + value); 1204 }) 1205 1206 Button('Change EnterKeyType').onClick(() => { 1207 this.index = (this.index + 1) % this.enterTypes.length; 1208 }) 1209 }.width('100%') 1210 } 1211} 1212``` 1213 1214 1215 1216### Example 5: Setting the Text Style 1217 1218This example showcases various text styles by using the **lineHeight**, **letterSpacing**, and **decoration** attributes. 1219 1220```ts 1221// xxx.ets 1222@Entry 1223@Component 1224struct SearchExample { 1225 build() { 1226 Row() { 1227 Column() { 1228 Text('lineHeight').fontSize(9).fontColor(0xCCCCCC) 1229 Search({value: 'lineHeight unset'}) 1230 .border({ width: 1 }).padding(10) 1231 Search({value: 'lineHeight 15'}) 1232 .border({ width: 1 }).padding(10).lineHeight(15) 1233 Search({value: 'lineHeight 30'}) 1234 .border({ width: 1 }).padding(10).lineHeight(30) 1235 1236 Text('letterSpacing').fontSize(9).fontColor(0xCCCCCC) 1237 Search({value: 'letterSpacing 0'}) 1238 .border({ width: 1 }).padding(5).letterSpacing(0) 1239 Search({value: 'letterSpacing 3'}) 1240 .border({ width: 1 }).padding(5).letterSpacing(3) 1241 Search({value: 'letterSpacing -1'}) 1242 .border({ width: 1 }).padding(5).letterSpacing(-1) 1243 1244 Text('decoration').fontSize(9).fontColor(0xCCCCCC) 1245 Search({value: 'LineThrough, Red'}) 1246 .border({ width: 1 }).padding(5) 1247 .decoration({type: TextDecorationType.LineThrough, color: Color.Red}) 1248 Search({value: 'Overline, Red, DOTTED'}) 1249 .border({ width: 1 }).padding(5) 1250 .decoration({type: TextDecorationType.Overline, color: Color.Red, style: TextDecorationStyle.DOTTED}) 1251 Search({value: 'Underline, Red, WAVY'}) 1252 .border({ width: 1 }).padding(5) 1253 .decoration({type: TextDecorationType.Underline, color: Color.Red, style: TextDecorationStyle.WAVY}) 1254 }.height('90%') 1255 } 1256 .width('90%') 1257 .margin(10) 1258 } 1259} 1260 1261``` 1262 1263 1264 1265### Example 6: Setting Text Feature Effects 1266 1267This example demonstrates how to use the **fontFeature** attribute to display text with various typographic features. 1268 1269```ts 1270// xxx.ets 1271@Entry 1272@Component 1273struct SearchExample { 1274 @State text1: string = 'This is ss01 on : 0123456789' 1275 @State text2: string = 'This is ss01 off: 0123456789' 1276 1277 build() { 1278 Column(){ 1279 Search({value: this.text1}) 1280 .margin({top:200}) 1281 .fontFeature("\"ss01\" on") 1282 Search({value: this.text2}) 1283 .margin({top:10}) 1284 .fontFeature("\"ss01\" off") 1285 } 1286 .width("90%") 1287 .margin("5%") 1288 } 1289} 1290``` 1291 1292 1293### Example 7: Setting Custom Keyboard Avoidance 1294 1295This example illustrates the implementation of a custom keyboard that automatically adjusts its position to avoid covering the text box. 1296 1297```ts 1298// xxx.ets 1299@Entry 1300@Component 1301struct SearchExample { 1302 controller: SearchController = new SearchController() 1303 @State inputValue: string = "" 1304 @State height1: string | number = '80%' 1305 @State supportAvoidance: boolean = true 1306 1307 // Create a custom keyboard component. 1308 @Builder 1309 CustomKeyboardBuilder() { 1310 Column() { 1311 Row() { 1312 Button('x').onClick(() => { 1313 // Disable the custom keyboard. 1314 this.controller.stopEditing() 1315 }).margin(10) 1316 } 1317 1318 Grid() { 1319 ForEach([1, 2, 3, 4, 5, 6, 7, 8, 9, '*', 0, '#'], (item: number | string) => { 1320 GridItem() { 1321 Button(item + "") 1322 .width(110).onClick(() => { 1323 this.inputValue += item 1324 }) 1325 } 1326 }) 1327 }.maxCount(3).columnsGap(10).rowsGap(10).padding(5) 1328 } 1329 .backgroundColor(Color.Gray) 1330 } 1331 1332 build() { 1333 Column() { 1334 Row() { 1335 Button("20%") 1336 .fontSize(24) 1337 .onClick(() => { 1338 this.height1 = "20%" 1339 }) 1340 Button("80%") 1341 .fontSize(24) 1342 .margin({ left: 20 }) 1343 .onClick(() => { 1344 this.height1 = "80%" 1345 }) 1346 } 1347 .justifyContent(FlexAlign.Center) 1348 .alignItems(VerticalAlign.Bottom) 1349 .height(this.height1) 1350 .width("100%") 1351 .padding({ bottom: 50 }) 1352 1353 Search({ controller: this.controller, value: this.inputValue })// Bind a custom keyboard. 1354 .customKeyboard(this.CustomKeyboardBuilder(), { supportAvoidance: this.supportAvoidance }) 1355 .margin(10) 1356 .border({ width: 1 }) 1357 .onChange((value: string) => { 1358 this.inputValue = value 1359 }) 1360 } 1361 } 1362} 1363``` 1364 1365 1366 1367### Example 8: Setting Text Auto-Adaptation 1368 1369This example showcases the implementation of text auto-adaptation features using the **minFontSize** and **maxFontSize** attributes. 1370 1371```ts 1372// xxx.ets 1373@Entry 1374@Component 1375struct SearchExample { 1376 build() { 1377 Row() { 1378 Column() { 1379 Text('adaptive font').fontSize(9).fontColor(0xCCCCCC) 1380 1381 Search({value: 'This is the text without the adaptive font'}) 1382 .width('80%').height(90).borderWidth(1) 1383 Search({value: 'This is the text without the adaptive font'}) 1384 .width('80%').height(90).borderWidth(1) 1385 .minFontSize(4) 1386 .maxFontSize(40) 1387 }.height('90%') 1388 } 1389 .width('90%') 1390 .margin(10) 1391 } 1392} 1393``` 1394 1395 1396 1397### Example 9: Setting Insert and Delete Callbacks 1398 1399This example showcases the implementation of insert and delete operations using the **onWillInsert**, **onDidInsert**, **onWillDelete**, and **onDidDelete** APIs. 1400 1401```ts 1402// xxx.ets 1403@Entry 1404@Component 1405struct SearchExample { 1406 @State insertValue: string = "" 1407 @State deleteValue: string = "" 1408 @State insertOffset: number = 0 1409 @State deleteOffset: number = 0 1410 @State deleteDirection: number = 0 1411 1412 build() { 1413 Row() { 1414 Column() { 1415 Search({ value: "Insert callbacks are supported" }) 1416 .height(60) 1417 .onWillInsert((info: InsertValue) => { 1418 this.insertValue = info.insertValue 1419 return true; 1420 }) 1421 .onDidInsert((info: InsertValue) => { 1422 this.insertOffset = info.insertOffset 1423 }) 1424 1425 Text("insertValue:" + this.insertValue + " insertOffset:" + this.insertOffset).height(30) 1426 1427 Search({ value: "Delete callbacks are supported" }) 1428 .height(60) 1429 .onWillDelete((info: DeleteValue) => { 1430 this.deleteValue = info.deleteValue 1431 info.direction 1432 return true; 1433 }) 1434 .onDidDelete((info: DeleteValue) => { 1435 this.deleteOffset = info.deleteOffset 1436 this.deleteDirection = info.direction 1437 }) 1438 1439 Text("deleteValue:" + this.deleteValue + " deleteOffset:" + this.deleteOffset).height(30) 1440 Text("deleteDirection:" + (this.deleteDirection == 0 ? "BACKWARD" : "FORWARD")).height(30) 1441 1442 }.width('100%') 1443 } 1444 .height('100%') 1445 } 1446} 1447``` 1448 1449 1450 1451### Example 10: Setting Custom Menu Extensions 1452 1453This example demonstrates how to use the **editMenuOptions** API to create custom menu extensions for text settings. It includes customizing text content, icons, and callbacks for these extensions. 1454 1455```ts 1456// xxx.ets 1457@Entry 1458@Component 1459struct SearchExample { 1460 @State text: string = 'Search editMenuOptions' 1461 onCreateMenu = (menuItems: Array<TextMenuItem>) => { 1462 let item1: TextMenuItem = { 1463 content: 'Custom 1', 1464 icon: $r('app.media.startIcon'), 1465 id: TextMenuItemId.of('custom1'), 1466 } 1467 let item2: TextMenuItem = { 1468 content: 'Custom 2', 1469 id: TextMenuItemId.of('custom2'), 1470 icon: $r('app.media.startIcon'), 1471 } 1472 menuItems.push(item1) 1473 menuItems.unshift(item2) 1474 return menuItems 1475 } 1476 onMenuItemClick = (menuItem: TextMenuItem, textRange: TextRange) => { 1477 if (menuItem.id.equals(TextMenuItemId.of("custom2"))) { 1478 console.log("Intercept id: custom2 start:" + textRange.start + "; end:" + textRange.end) 1479 return true 1480 } 1481 if (menuItem.id.equals(TextMenuItemId.COPY)) { 1482 console.log("Intercept COPY start:" + textRange.start + "; end:" + textRange.end) 1483 return true 1484 } 1485 if (menuItem.id.equals(TextMenuItemId.SELECT_ALL)) { 1486 console.log("Do not intercept SELECT_ALL start:" + textRange.start + "; end:" + textRange.end) 1487 return false 1488 } 1489 return false 1490 } 1491 @State editMenuOptions: EditMenuOptions = { 1492 onCreateMenu: this.onCreateMenu, onMenuItemClick: this.onMenuItemClick 1493 } 1494 1495 build() { 1496 Column() { 1497 Search({ value: this.text }) 1498 .width('95%') 1499 .editMenuOptions(this.editMenuOptions) 1500 .margin({ top: 100 }) 1501 } 1502 .width("90%") 1503 .margin("5%") 1504 } 1505} 1506``` 1507 1508 1509 1510### Example 11: Setting a Custom Symbol-Type Cancel Button 1511 1512This example demonstrates how to use the **searchIcon** and **cancelButton** attributes to customize the style of the symbol-type cancel button on the right side of the text box. 1513 1514```ts 1515// xxx.ets 1516import { SymbolGlyphModifier } from '@kit.ArkUI' 1517 1518@Entry 1519@Component 1520struct SearchExample { 1521 controller: SearchController = new SearchController() 1522 @State changeValue: string = '' 1523 @State submitValue: string = '' 1524 1525 build() { 1526 Column() { 1527 Search({ value: this.changeValue, placeholder: 'Type to search...', controller: this.controller }) 1528 .searchIcon(new SymbolGlyphModifier($r('sys.symbol.magnifyingglass')).fontColor([Color.Red])) 1529 .cancelButton({ 1530 style: CancelButtonStyle.CONSTANT, 1531 icon: new SymbolGlyphModifier($r('sys.symbol.xmark')).fontColor([Color.Green]) 1532 }) 1533 .searchButton('SEARCH') 1534 .width('95%') 1535 .height(40) 1536 .backgroundColor('#F5F5F5') 1537 .placeholderColor(Color.Grey) 1538 .placeholderFont({ size: 14, weight: 400 }) 1539 .textFont({ size: 14, weight: 400 }) 1540 .margin(10) 1541 } 1542 .width('100%') 1543 .height('100%') 1544 } 1545} 1546``` 1547 1548 1549 1550### Example 12: Setting Whether Text is Copyable 1551 1552This example demonstrates how to set whether text is copyable using **copyOption**. 1553 1554```ts 1555// xxx.ets 1556 1557@Entry 1558@Component 1559struct SearchExample { 1560 controller: SearchController = new SearchController() 1561 @State copyValue: string = '' 1562 @State cutValue: string = '' 1563 1564 build() { 1565 Column({ space: 3 }) { 1566 Text("copy: " + this.copyValue) 1567 Text("cut:" + this.cutValue) 1568 Search({ value: 'Search CopyOption:None', controller: this.controller }) 1569 .width('95%') 1570 .height(40) 1571 .copyOption(CopyOptions.None) 1572 .onCopy((value: string) => { 1573 this.copyValue = value; 1574 }) 1575 .onCut((value: string) => { 1576 this.cutValue = value; 1577 }) 1578 Search({ value: 'Search CopyOption:InApp', controller: this.controller }) 1579 .width('95%') 1580 .height(40) 1581 .copyOption(CopyOptions.InApp) 1582 .onCopy((value: string) => { 1583 this.copyValue = value; 1584 }) 1585 .onCut((value: string) => { 1586 this.cutValue = value; 1587 }) 1588 Search({ value: 'Search CopyOption:LocalDevice', controller: this.controller }) 1589 .width('95%') 1590 .height(40) 1591 .copyOption(CopyOptions.LocalDevice) 1592 .onCopy((value: string) => { 1593 this.copyValue = value; 1594 }) 1595 .onCut((value: string) => { 1596 this.cutValue = value; 1597 }) 1598 } 1599 .width('100%') 1600 .height('100%') 1601 } 1602} 1603``` 1604 1605 1606 1607### Example 13: Setting the Horizontal Alignment, Caret Style, and Background Color of the Selected Text 1608 1609This example shows how to set the horizontal alignment, caret style, and background color of the selected text using **textAlign**, **caretStyle**, and **selectedBackgroundColor**. 1610 1611```ts 1612// xxx.ets 1613 1614@Entry 1615@Component 1616struct SearchExample { 1617 controller: SearchController = new SearchController() 1618 1619 build() { 1620 Column({ space: 3 }) { 1621 Search({ value: 'Search textAlign sample', controller: this.controller }) 1622 .width('95%') 1623 .height(40) 1624 .stopBackPress(true) 1625 .textAlign(TextAlign.Center) 1626 .caretStyle({ width: 3, color: Color.Green }) 1627 .selectedBackgroundColor(Color.Gray) 1628 } 1629 .width('100%') 1630 .height('100%') 1631 } 1632} 1633``` 1634 1635 1636 1637### Example 14: Configuring the Text Box to Receive Default Focus and Bring Up the Soft Keyboard 1638 1639This example illustrates how to configure the text box to receive default focus and bring up the soft keyboard using **defaultFocus** and **enableKeyboardOnFocus**. 1640 1641```ts 1642// xxx.ets 1643 1644@Entry 1645@Component 1646struct SearchExample { 1647 controller: SearchController = new SearchController() 1648 @State value: string = 'false' 1649 1650 build() { 1651 Column({ space: 3 }) { 1652 Text('editing: ' + this.value) 1653 Search({ placeholder: 'please enter...', controller: this.controller }) 1654 .width('95%') 1655 .height(40) 1656 .defaultFocus(true) 1657 .enableKeyboardOnFocus(true) 1658 .enablePreviewText(true) 1659 .enableHapticFeedback(true) 1660 .onEditChange((data: boolean) => { 1661 this.value = data ? 'true' : 'false' 1662 }) 1663 } 1664 .width('100%') 1665 .height('100%') 1666 } 1667} 1668``` 1669 1670 1671 1672### Example 15: Disabling the System Context Menu on Selection 1673 1674This example shows how to disable the system context menu on selection using **defaultFocus** and **enableKeyboardOnFocus**. 1675 1676```ts 1677// xxx.ets 1678 1679@Entry 1680@Component 1681struct SearchExample { 1682 controller: SearchController = new SearchController() 1683 1684 build() { 1685 Column({ space: 3 }) { 1686 Search({ value: '123456', controller: this.controller }) 1687 .width('95%') 1688 .height(40) 1689 .type(SearchType.NUMBER) 1690 .selectionMenuHidden(true) 1691 } 1692 .width('100%') 1693 .height('100%') 1694 } 1695} 1696``` 1697 1698 1699 1700### Example 16: Setting Input Filtering 1701 1702This example shows how to set input filtering using **inputFilter**. 1703 1704```ts 1705// xxx.ets 1706 1707@Entry 1708@Component 1709struct SearchExample { 1710 controller: SearchController = new SearchController() 1711 @State filterValue: string = '' 1712 1713 build() { 1714 Column({ space: 3 }) { 1715 Text('Filter:' + this.filterValue) 1716 Search({ placeholder: 'please enter...', controller: this.controller }) 1717 .width('95%') 1718 .height(40) 1719 .textIndent(5) 1720 .halfLeading(true) 1721 .inputFilter('[a-z]', (filterValue: string) => { 1722 this.filterValue = filterValue 1723 }) 1724 } 1725 .width('100%') 1726 .height('100%') 1727 } 1728} 1729``` 1730 1731 1732 1733### Example 17: Selecting a Specific Text Range 1734 1735This example illustrates how to select a specific range of text content using **setTextSelection**. 1736 1737```ts 1738// xxx.ets 1739 1740@Entry 1741@Component 1742struct SearchExample { 1743 controller: SearchController = new SearchController() 1744 @State startIndex: number = 0 1745 @State endIndex: number = 0 1746 1747 build() { 1748 Column({ space: 3 }) { 1749 Text('Selection start:' + this.startIndex + ' end:' + this.endIndex) 1750 Search({ value: 'Hello World', controller: this.controller }) 1751 .width('95%') 1752 .height(40) 1753 .minFontScale(1) 1754 .maxFontScale(1.5) 1755 .defaultFocus(true) 1756 .onTextSelectionChange((selectionStart: number, selectionEnd: number) => { 1757 this.startIndex = selectionStart 1758 this.endIndex = selectionEnd 1759 }) 1760 1761 Button('Selection [0,3]') 1762 .onClick(() => { 1763 this.controller.setTextSelection(0, 3) 1764 }) 1765 } 1766 .width('100%') 1767 .height('100%') 1768 } 1769} 1770``` 1771 1772 1773 1774### Example 18: Handling Text Scrolling Events 1775 1776This example demonstrates how to set a callback for text scrolling events using **onContentScroll**. 1777 1778```ts 1779// xxx.ets 1780 1781@Entry 1782@Component 1783struct SearchExample { 1784 controller: SearchController = new SearchController() 1785 @State offsetX: number = 0 1786 @State offsetY: number = 0 1787 1788 build() { 1789 Column({ space: 3 }) { 1790 Text('offset x:' + this.offsetX + ' y:' + this.offsetY) 1791 Search({ value: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', controller: this.controller }) 1792 .width(200) 1793 .height(40) 1794 .onContentScroll((totalOffsetX: number, totalOffsetY: number) => { 1795 this.offsetX = totalOffsetX 1796 this.offsetY = totalOffsetY 1797 }) 1798 } 1799 .width('100%') 1800 .height('100%') 1801 } 1802} 1803``` 1804 1805 1806 1807### Example 19: Setting the Minimum and Maximum Font Scale Factor 1808 1809This example demonstrates how to set the minimum and maximum font scale factor using **minFontScale** and **maxFontScale**. 1810 1811```ts 1812import { abilityManager, Configuration } from '@kit.AbilityKit'; 1813import { BusinessError } from '@kit.BasicServicesKit'; 1814 1815// xxx.ets 1816@Entry 1817@Component 1818export struct TextAreaExample11 { 1819 @State minFontScale: number = 0.85; 1820 @State maxFontScale: number = 2; 1821 @State changeValue: string = 'abcde'; 1822 1823 build() { 1824 Column() { 1825 Column({ space: 30 }) { 1826 Text("System font size changes: small and large, small and large") 1827 TextArea({ 1828 placeholder: 'The text area can hold an unlimited amount of text. input your word...', 1829 }) 1830 // Set the minimum font scale factor; if the value is undefined, the text follows the default font scale factor. 1831 .minFontScale(0.85) 1832 // Set the maximum font scale factor; if the value is undefined, the text follows the default font scale factor. 1833 .maxFontScale(2) 1834 }.width('100%') 1835 } 1836 } 1837} 1838``` 1839 1840```ts 1841Create a new directory named profile in the following path: AppScope/resources/base. 1842Inside the newly created profile directory, create a file named configuration.json. 1843Add the following JSON code to the configuration.json file: 1844{ 1845 "configuration":{ 1846 "fontSizeScale": "followSystem", 1847 "fontSizeMaxScale": "3.2" 1848} 1849} 1850``` 1851 1852```ts 1853Modify the app.json5 file in AppScope as follows: 1854{ 1855 "app": { 1856 "bundleName": "com.example.myapplication", 1857 "vendor": "example", 1858 "versionCode": 1000000, 1859 "versionName": "1.0.0", 1860 "icon": "$media:app_icon", 1861 "label": "$string:app_name", 1862 "configuration": "$profile:configuration" 1863 } 1864} 1865``` 1866
