1# Search 2 3搜索框组件，适用于浏览器的搜索内容输入框等应用场景。 4 5> **说明：** 6> 7> 该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9## 子组件 10 11无 12 13## 接口 14 15Search(options?: SearchOptions) 16 17**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 18 19**系统能力：** SystemCapability.ArkUI.ArkUI.Full 20 21**参数:** 22 23| 参数名 | 类型 | 必填 | 说明 | 24| ----------- | ------------- | ---- | ------------- | 25| options | [SearchOptions](#searchoptions18对象说明)| 否 | 搜索框组件初始化选项 | 26 27## SearchOptions<sup>18+</sup>对象说明 28 29Search初始化参数。 30 31**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 32 33**系统能力：** SystemCapability.ArkUI.ArkUI.Full 34 35| 名称 | 类型 | 必填 | 说明 | 36| ----------- | ------------- | ---- | ------------- | 37| value<sup>8+</sup> | string | 否 | 设置当前显示的搜索文本内容。<br />从API version 10开始，该参数支持[$$](../../../ui/state-management/arkts-two-way-sync.md)双向绑定变量。<br />从API version 18开始，该参数支持[!!](../../../ui/state-management/arkts-new-binding.md#系统组件参数双向绑定)双向绑定变量。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 38| placeholder<sup>8+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 设置无输入时的提示文本。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 39| icon<sup>8+</sup> | string | 否 | 设置搜索图标路径，默认使用系统搜索图标。<br/>**说明：** <br/>icon的数据源支持本地图片和网络图片。<br/>- 支持的图片格式包括png、jpg、bmp、svg、gif、pixelmap和heif。<br/>- 支持Base64字符串。格式data:image/[png\|jpeg\|bmp\|webp\|heif];base64,[base64 data], 其中[base64 data]为Base64字符串数据。<br/>如果与属性searchIcon同时设置，则searchIcon优先。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 40| controller<sup>8+</sup> | [SearchController](#searchcontroller) | 否 | 设置Search组件控制器。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 41 42## 属性 43 44除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 45 46### searchButton 47 48searchButton(value: string, option?: SearchButtonOptions) 49 50设置搜索框末尾搜索按钮。 51 52点击搜索按钮，同时触发onSubmit与onClick回调。 53 54Wearable设备上默认字体大小为18fp。 55 56**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 57 58**系统能力：** SystemCapability.ArkUI.ArkUI.Full 59 60**参数：** 61 62| 参数名 | 类型 | 必填 | 说明 | 63| ------ | ----------------------------------------------------- | ---- | ---------------------------- | 64| value | string | 是 | 搜索框末尾搜索按钮文本内容。 | 65| option | [SearchButtonOptions](#searchbuttonoptions10对象说明) | 否 | 配置搜索框文本样式。<br />默认值：<br />{<br />fontSize: '16fp',<br />fontColor: '#ff3f97e9'<br />} | 66 67### placeholderColor 68 69placeholderColor(value: ResourceColor) 70 71设置placeholder文本颜色，Wearable设备上默认值为'#99ffffff'。 72 73**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 74 75**系统能力：** SystemCapability.ArkUI.ArkUI.Full 76 77**参数：** 78 79| 参数名 | 类型 | 必填 | 说明 | 80| ------ | ------------------------------------------ | ---- | ------------------------------------------------ | 81| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | placeholder文本颜色。<br />默认值：'#99182431'。 | 82 83### placeholderFont 84 85placeholderFont(value?: Font) 86 87设置placeholder文本样式，包括字体大小，字体粗细，字体族，字体风格。当前支持'HarmonyOS Sans'字体和[注册自定义字体](../js-apis-font.md)。 88 89Wearable设备上默认字体大小为18fp。 90 91**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 92 93**系统能力：** SystemCapability.ArkUI.ArkUI.Full 94 95**参数：** 96 97| 参数名 | 类型 | 必填 | 说明 | 98| ------ | ------------------------ | ---- | --------------------- | 99| value | [Font](ts-types.md#font) | 否 | placeholder文本样式。 | 100 101### textFont 102 103textFont(value?: Font) 104 105设置搜索框内输入文本样式，包括字体大小，字体粗细，字体族，字体风格。目前仅支持默认字体族。 106 107Wearable设备上默认字体大小为18fp。 108 109**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 110 111**系统能力：** SystemCapability.ArkUI.ArkUI.Full 112 113**参数：** 114 115| 参数名 | 类型 | 必填 | 说明 | 116| ------ | ------------------------ | ---- | ---------------------- | 117| value | [Font](ts-types.md#font) | 否 | 搜索框内输入文本样式。 | 118 119### textAlign<sup>9+</sup> 120 121textAlign(value: TextAlign) 122 123设置文本在搜索框中的对齐方式。目前支持的对齐方式有：Start、Center、End。 124 125**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 126 127**系统能力：** SystemCapability.ArkUI.ArkUI.Full 128 129**参数：** 130 131| 参数名 | 类型 | 必填 | 说明 | 132| ------ | ------------------------------------------- | ---- | ------------------------------------------------------ | 133| value | [TextAlign](ts-appendix-enums.md#textalign) | 是 | 文本在搜索框中的对齐方式。<br/>默认值：TextAlign.Start | 134 135### copyOption<sup>9+</sup> 136 137copyOption(value: CopyOptions) 138 139设置输入的文本是否可复制。设置CopyOptions.None时，当前Search中的文字无法被复制、剪切、翻译、分享、搜索和帮写，仅支持粘贴。 140 141设置CopyOptions.None时，不允许拖拽。 142 143**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 144 145**系统能力：** SystemCapability.ArkUI.ArkUI.Full 146 147**参数：** 148 149| 参数名 | 类型 | 必填 | 说明 | 150| ------ | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 151| value | [CopyOptions](ts-appendix-enums.md#copyoptions9) | 是 | 输入的文本是否可复制。<br />默认值：CopyOptions.LocalDevice，支持设备内复制。 | 152 153### searchIcon<sup>10+</sup> 154 155searchIcon(value: IconOptions | SymbolGlyphModifier) 156 157设置左侧搜索图标样式。 158 159Wearable设备上默认图标大小为16vp。 160 161**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 162 163**系统能力：** SystemCapability.ArkUI.ArkUI.Full 164 165**参数：** 166 167| 参数名 | 类型 | 必填 | 说明 | 168| ------ | ------------------------------------- | ---- | ------------------ | 169| value | [IconOptions](#iconoptions10对象说明) \| [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | 是 | 左侧搜索图标样式。<!--RP1--><br />浅色模式默认值：<br />{<br />size: '16vp',<br />color: '#99182431',<br />src: ' '<br />}<br />深色模式默认值：<br />{<br />size: '16vp',<br />color: '#99ffffff',<br />src: ' '<br />} <!--RP1End-->| 170 171### cancelButton<sup>10+</sup> 172 173cancelButton(value: CancelButtonOptions | CancelButtonSymbolOptions) 174 175设置右侧清除按钮样式。 176 177Wearable设备上默认图标大小为18fp。 178 179**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 180 181**系统能力：** SystemCapability.ArkUI.ArkUI.Full 182 183**参数：** 184 185| 参数名 | 类型 | 必填 | 说明 | 186| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 187| value | [CancelButtonOptions](#cancelbuttonoptions12对象说明) \| [CancelButtonSymbolOptions](#cancelbuttonsymboloptions12对象说明) | 是 | 右侧清除按钮样式。<br>默认值：<br />{<br/>style: CancelButtonStyle.INPUT,<br/>icon: {<br/>size: '16vp',<br/>color: '#99ffffff',<br/>src: ' '<br/>}<br/>}<br/>当style为CancelButtonStyle.CONSTANT时，默认显示清除样式。 | 188 189### fontColor<sup>10+</sup> 190 191fontColor(value: ResourceColor) 192 193设置输入文本的字体颜色。[文本通用属性](ts-universal-attributes-text-style.md)fontSize、fontStyle、fontWeight和fontFamily在[textFont](#textfont)属性中设置。 194 195Wearable设备上默认值为'#dbffffff'。 196 197**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 198 199**系统能力：** SystemCapability.ArkUI.ArkUI.Full 200 201**参数：** 202 203| 参数名 | 类型 | 必填 | 说明 | 204| ------ | ------------------------------------------ | ---- | ----------------------------------------------- | 205| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 输入文本的字体颜色。<br />默认值：'#FF182431'。 | 206 207### caretStyle<sup>10+</sup> 208 209caretStyle(value: CaretStyle) 210 211设置光标样式。 212 213**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 214 215**系统能力：** SystemCapability.ArkUI.ArkUI.Full 216 217**参数：** 218 219| 参数名 | 类型 | 必填 | 说明 | 220| ------ | ----------------------------------- | ---- | ------------------------------------------------------------ | 221| value | [CaretStyle](ts-text-common.md#caretstyle10) | 是 | 光标样式。<br />默认值：<br />{<br />width: '1.5vp',<br />color: '#007DFF'<br />} | 222 223> **说明：** 224> 从API version 12开始，此接口支持设置文本手柄颜色，光标和文本手柄颜色保持一致。 225 226### enableKeyboardOnFocus<sup>10+</sup> 227 228enableKeyboardOnFocus(value: boolean) 229 230设置Search通过点击以外的方式获焦时，是否主动拉起软键盘。 231 232从API version 10开始，获焦默认绑定输入法。 233 234**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 235 236**系统能力：** SystemCapability.ArkUI.ArkUI.Full 237 238**参数：** 239 240| 参数名 | 类型 | 必填 | 说明 | 241| ------ | ------- | ---- | ----------------------------------------------- | 242| value | boolean | 是 | Search获焦时，是否主动拉起软键盘。<br/>true表示主动拉起，false表示不主动拉起。<br/>默认值：true | 243 244### selectionMenuHidden<sup>10+</sup> 245 246selectionMenuHidden(value: boolean) 247 248设置是否不弹出系统文本选择菜单。 249 250**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 251 252**系统能力：** SystemCapability.ArkUI.ArkUI.Full 253 254**参数：** 255 256| 参数名 | 类型 | 必填 | 说明 | 257| ------ | ------- | ---- | ------------------------------------------------------------ | 258| value | boolean | 是 | 是否不弹出系统文本选择菜单。<br />设置为true时，单击输入框光标、长按输入框、双击输入框、三击输入框或者右键输入框，不弹出系统文本选择菜单。<br />设置为false时，弹出系统文本选择菜单。<br />默认值：false | 259 260### customKeyboard<sup>10+</sup> 261 262customKeyboard(value: CustomBuilder, options?: KeyboardOptions) 263 264设置自定义键盘。 265 266当设置自定义键盘时，输入框激活后不会打开系统输入法，而是加载指定的自定义组件。 267 268自定义键盘的高度可以通过自定义组件根节点的height属性设置，宽度不可设置，使用系统默认值。 269 270自定义键盘采用覆盖原始界面的方式呈现，当没有开启避让模式或者输入框不需要避让的场景不会对应用原始界面产生压缩或者上提。 271 272自定义键盘无法获取焦点，但是会拦截手势事件。 273 274默认在输入控件失去焦点时，关闭自定义键盘，开发者也可以通过[stopEditing](#stopediting10)方法控制键盘关闭。 275 276如果设备支持拍摄输入，设置自定义键盘后，该输入框会不支持拍摄输入。 277 278当设置自定义键盘时，可以通过绑定[onKeyPrelme](ts-universal-events-key.md#onkeypreime12)事件规避物理键盘的输入。 279 280**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 281 282**系统能力：** SystemCapability.ArkUI.ArkUI.Full 283 284**参数：** 285 286| 参数名 | 类型 | 必填 | 说明 | 287| --------------------- | ------------------------------------------- | ---- | -------------------------------- | 288| value | [CustomBuilder](ts-types.md#custombuilder8) | 是 | 自定义键盘。 | 289| options<sup>12+</sup> | [KeyboardOptions](ts-basic-components-richeditor.md#keyboardoptions12) | 否 | 设置自定义键盘是否支持避让功能。 | 290 291### type<sup>11+</sup> 292 293type(value: SearchType) 294 295设置输入框类型。 296 297**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 298 299**系统能力：** SystemCapability.ArkUI.ArkUI.Full 300 301**参数：** 302 303| 参数名 | 类型 | 必填 | 说明 | 304| ------ | ----------------------------------- | ---- | -------------------------- | 305| value | [SearchType](#searchtype11枚举说明) | 是 | 输入框类型。<br/>默认值：SearchType.Normal | 306 307### maxLength<sup>11+</sup> 308 309maxLength(value: number) 310 311设置文本的最大输入字符数。默认不设置最大输入字符数限制。到达文本最大字符限制，将无法继续输入字符。 312 313**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 314 315**系统能力：** SystemCapability.ArkUI.ArkUI.Full 316 317**参数：** 318 319| 参数名 | 类型 | 必填 | 说明 | 320| ------ | ----------------------------------- | ---- | ---------------------- | 321| value | number | 是 | 文本的最大输入字符数。 | 322 323### enterKeyType<sup>12+</sup> 324 325enterKeyType(value: EnterKeyType) 326 327设置输入法回车键类型。 328 329**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 330 331**系统能力：** SystemCapability.ArkUI.ArkUI.Full 332 333**参数：** 334 335| 参数名 | 类型 | 必填 | 说明 | 336| ------ | ------------------------------------------------ | ---- | -------------------------------------------------- | 337| value | [EnterKeyType](ts-basic-components-textinput.md#enterkeytype枚举说明) | 是 | 输入法回车键类型。<br/>默认值：EnterKeyType.Search | 338 339### lineHeight<sup>12+</sup> 340 341lineHeight(value: number | string | Resource) 342 343设置文本的文本行高，设置值不大于0时，不限制文本行高，自适应字体大小，number类型时单位为fp。 344 345**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 346 347**系统能力：** SystemCapability.ArkUI.ArkUI.Full 348 349**参数：** 350 351| 参数名 | 类型 | 必填 | 说明 | 352| ------ | ------------------------------------------------------------ | ---- | ---------------- | 353| value | number \| string \| [Resource](ts-types.md#resource) | 是 | 文本的文本行高。 | 354 355### decoration<sup>12+</sup> 356 357decoration(value: TextDecorationOptions) 358 359设置文本装饰线类型样式及其颜色。 360 361**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 362 363**系统能力：** SystemCapability.ArkUI.ArkUI.Full 364 365**参数：** 366 367| 参数名 | 类型 | 必填 | 说明 | 368| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 369| value | [TextDecorationOptions](ts-types.md#textdecorationoptions12对象说明) | 是 | 文本装饰线对象。<br />默认值：{<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 375设置文本字符间距。设置该值为百分比时，按默认值显示。设置该值为0时，按默认值显示。string类型支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"。 376 377当取值为负值时，文字会发生压缩，负值过小时会将组件内容区大小压缩为0，导致无内容显示。 378 379**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 380 381**系统能力：** SystemCapability.ArkUI.ArkUI.Full 382 383**参数：** 384 385| 参数名 | 类型 | 必填 | 说明 | 386| ------ | -------------------------- | ---- | -------------- | 387| value | number \| string \| [Resource](ts-types.md#resource) | 是 | 文本字符间距。<br/>单位：fp | 388 389### fontFeature<sup>12+</sup> 390 391fontFeature(value: string) 392 393设置文字特性效果，比如数字等宽的特性。 394 395格式为：normal \| \<feature-tag-value\> 396 397\<feature-tag-value\>的格式为：\<string\> \[ \<integer\> \| on \| off ] 398 399\<feature-tag-value\>的个数可以有多个，中间用','隔开。 400 401例如，使用等宽数字的输入格式为："ss01" on。 402 403**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 404 405**系统能力：** SystemCapability.ArkUI.ArkUI.Full 406 407**参数：** 408 409| 参数名 | 类型 | 必填 | 说明 | 410| ------ | ------ | ---- | -------------- | 411| value | string | 是 | 文字特性效果。 | 412 413Font Feature当前支持的属性见 [fontFeature属性列表](ts-basic-components-text.md#fontfeature12)。 414设置 Font Feature 属性，Font Feature 是 OpenType 字体的高级排版能力，如支持连字、数字等宽等特性，一般用在自定义字体中，其能力需要字体本身支持。 415更多 Font Feature 能力介绍可参考 https://www.w3.org/TR/css-fonts-3/#font-feature-settings-prop 和 https://sparanoid.com/lab/opentype-features/ 416 417### selectedBackgroundColor<sup>12+</sup> 418 419selectedBackgroundColor(value: ResourceColor) 420 421设置文本选中底板颜色。如果未设置不透明度，默认为20%不透明度。 422 423**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 424 425**系统能力：** SystemCapability.ArkUI.ArkUI.Full 426 427**参数：** 428 429| 参数名 | 类型 | 必填 | 说明 | 430| ------ | ------------------------------------------ | ---- | ------------------------------------------ | 431| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 文本选中底板颜色。<br/>默认为20%不透明度。 | 432 433### inputFilter<sup>12+</sup> 434 435inputFilter(value: ResourceStr, error?: Callback< string >) 436 437通过正则表达式设置输入过滤器。匹配表达式的输入允许显示，不匹配的输入将被过滤。仅支持单个字符匹配，不支持字符串匹配。 438 439设置inputFilter且输入的字符不为空字符，会导致设置输入框类型(即type接口)附带的文本过滤效果失效。 440 441**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 442 443**系统能力：** SystemCapability.ArkUI.ArkUI.Full 444 445**参数：** 446 447| 参数名 | 类型 | 必填 | 说明 | 448| ------ | -------------------------------------- | ---- | ---------------------------------- | 449| value | [ResourceStr](ts-types.md#resourcestr) | 是 | 正则表达式。 | 450| error | Callback< string > | 否 | 正则匹配失败时，返回被过滤的内容。 | 451 452### textIndent<sup>12+</sup> 453 454textIndent(value: Dimension) 455 456设置首行文本缩进。 457 458**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 459 460**系统能力：** SystemCapability.ArkUI.ArkUI.Full 461 462**参数：** 463 464| 参数名 | 类型 | 必填 | 说明 | 465| ------ | ----------------------------------- | ---- | ---------------------------- | 466| value | [Dimension](ts-types.md#dimension10)| 是 | 首行文本缩进。<br/>默认值：0 | 467 468### minFontSize<sup>12+</sup> 469 470minFontSize(value: number | string | Resource) 471 472设置文本最小显示字号。string类型支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"。 473 474需配合[maxFontSize](#maxfontsize12)以及布局大小限制使用，单独设置不生效。 475 476自适应字号生效时，fontSize设置不生效。 477 478**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 479 480**系统能力：** SystemCapability.ArkUI.ArkUI.Full 481 482**参数：** 483 484| 参数名 | 类型 | 必填 | 说明 | 485| ------ | ------------------------------------------------------------ | ---- | ------------------ | 486| value | number \| string \| [Resource](ts-types.md#resource) | 是 | 文本最小显示字号。<br/>单位：fp | 487 488### maxFontSize<sup>12+</sup> 489 490maxFontSize(value: number | string | Resource) 491 492设置文本最大显示字号。string类型支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"。 493 494需配合[minFontSize](#minfontsize12)以及布局大小限制使用，单独设置不生效。 495 496自适应字号生效时，fontSize设置不生效。 497 498**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 499 500**系统能力：** SystemCapability.ArkUI.ArkUI.Full 501 502**参数：** 503 504| 参数名 | 类型 | 必填 | 说明 | 505| ------ | ------------------------------------------------------------ | ---- | ------------------ | 506| value | number \| string \| [Resource](ts-types.md#resource) | 是 | 文本最大显示字号。<br/>单位：fp | 507 508### halfLeading<sup>18+</sup> 509 510halfLeading(halfLeading: Optional\<boolean>) 511 512设置文本是否将行间距平分至行的顶部与底部。 513 514**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 515 516**系统能力：** SystemCapability.ArkUI.ArkUI.Full 517 518**参数：** 519 520| 参数名 | 类型 | 必填 | 说明 | 521| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 522| halfLeading | [Optional](ts-universal-attributes-custom-property.md#optional12)\<boolean> | 是 | 文本是否将行间距平分至行的顶部与底部。<br/>true表示将行间距平分至行的顶部与底部，false则不平分。<br/>默认值：false | 523 524### minFontScale<sup>18+</sup> 525 526minFontScale(scale: Optional\<number | Resource>) 527 528设置文本最小的字体缩放倍数。 529 530**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 531 532**系统能力：** SystemCapability.ArkUI.ArkUI.Full 533 534**参数：** 535 536| 参数名 | 类型 | 必填 | 说明 | 537| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 538| scale | [Optional](ts-universal-attributes-custom-property.md#optional12)\<number \| [Resource](ts-types.md#resource)> | 是 | 文本最小的字体缩放倍数，支持undefined类型。<br/>取值范围：[0, 1]<br/>**说明：** <br/>设置的值小于0时，按值为0处理。设置的值大于1，按值为1处理。异常值默认不生效。<br/>使用前需在工程中配置configuration.json文件和app.json5文件，具体详见[示例19设置最小字体范围与最大字体范围](#示例19设置最小字体范围与最大字体范围)。 | 539 540### maxFontScale<sup>18+</sup> 541 542maxFontScale(scale: Optional\<number | Resource>) 543 544设置文本最大的字体缩放倍数。 545 546**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 547 548**系统能力：** SystemCapability.ArkUI.ArkUI.Full 549 550**参数：** 551 552| 参数名 | 类型 | 必填 | 说明 | 553| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 554| scale | [Optional](ts-universal-attributes-custom-property.md#optional12)\<number \| [Resource](ts-types.md#resource)> | 是 | 文本最大的字体缩放倍数，支持undefined类型。<br/>取值范围：[1, +∞)<br/>**说明：** <br/>设置的值小于1时，按值为1处理。异常值默认不生效。<br/>使用前需在工程中配置configuration.json文件和app.json5文件，具体详见[示例19设置最小字体范围与最大字体范围](#示例19设置最小字体范围与最大字体范围)。 | 555 556### editMenuOptions<sup>12+</sup> 557 558editMenuOptions(editMenu: EditMenuOptions) 559 560设置自定义菜单扩展项，允许用户设置扩展项的文本内容、图标、回调方法。 561 562**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 563 564**系统能力：** SystemCapability.ArkUI.ArkUI.Full 565 566**参数：** 567 568| 参数名 | 类型 | 必填 | 说明 | 569| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 570| editMenu | [EditMenuOptions](ts-text-common.md#editmenuoptions) | 是 | 扩展菜单选项。 | 571 572### enablePreviewText<sup>12+</sup> 573 574enablePreviewText(enable: boolean) 575 576设置是否开启输入预上屏。 577 578预上屏内容定义为文字暂存态，目前不支持文字拦截功能，因此不触发onWillInsert、onDidInsert、onWillDelete、onDidDelete回调。 579 580**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 581 582**系统能力：** SystemCapability.ArkUI.ArkUI.Full 583 584**参数：** 585 586| 参数名 | 类型 | 必填 | 说明 | 587| ------ | ------- | ---- | ---------------------------------- | 588| enable | boolean | 是 | 是否开启输入预上屏。<br/>默认值：true | 589 590### enableHapticFeedback<sup>13+</sup> 591 592enableHapticFeedback(isEnabled: boolean) 593 594设置是否开启触控反馈。 595 596**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 597 598**系统能力：** SystemCapability.ArkUI.ArkUI.Full 599 600**参数：** 601 602| 参数名 | 类型 | 必填 | 说明 | 603| ------ | ------- | ---- | ---------------------------------- | 604| isEnabled | boolean | 是 | 是否开启触控反馈。<br/>默认值：true | 605 606> **说明：** 607> 608> 开启触控反馈时，需要在工程的module.json5中配置requestPermissions字段以开启振动权限，配置如下： 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 621设置输入框拉起的键盘样式。 622 623**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 624 625**系统能力：** SystemCapability.ArkUI.ArkUI.Full 626 627**参数：** 628 629| 参数名 | 类型 | 必填 | 说明 | 630| ------ | ----------------------------------------- | ---- | ------------------------------------------------------ | 631| appearance | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[KeyboardAppearance](ts-text-common.md#keyboardappearance15枚举说明)> | 是 | 键盘样式。<br/>默认值：KeyboardAppearance.NONE_IMMERSIVE | 632 633### stopBackPress<sup>15+</sup> 634 635stopBackPress(isStopped: Optional\<boolean>) 636 637设置是否阻止返回键向其它组件或应用侧传递。 638 639**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 640 641**系统能力：** SystemCapability.ArkUI.ArkUI.Full 642 643**参数：** 644 645| 参数名 | 类型 | 必填 | 说明 | 646| ------ | ------- | ---- | ---------------------------------- | 647| isStopped | [Optional](ts-universal-attributes-custom-property.md#optional12)\<boolean> | 是 | 是否消费返回键。 <br />默认值：true | 648 649## IconOptions<sup>10+</sup>对象说明 650 651**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 652 653**系统能力：** SystemCapability.ArkUI.ArkUI.Full 654 655| 名称 | 类型 | 必填 | 说明 | 656| ------ | ------------------------------------------ | ---- | ----------- | 657| size | [Length](ts-types.md#length) | 否 | 图标尺寸，不支持百分比。 | 658| color | [ResourceColor](ts-types.md#resourcecolor) | 否 | 图标颜色。 | 659| src | [ResourceStr](ts-types.md#resourcestr) | 否 | 图标/图片源。 | 660 661## SearchButtonOptions<sup>10+</sup>对象说明 662 663**系统能力：** SystemCapability.ArkUI.ArkUI.Full 664 665| 名称 | 类型 | 必填 | 说明 | 666| --------- | ------------------------------------------ | ---- | ---------------- | 667| fontSize | [Length](ts-types.md#length) | 否 | 文本按钮字体大小，不支持百分比。**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 668| fontColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 文本按钮字体颜色。**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 669| autoDisable<sup>18+</sup> | Boolean | 否 | Search无文本内容时按钮置灰且不可点击。<br/>默认值：false <br>true表示开启按钮置灰功能，false表示不开启。 <br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。| 670 671## CancelButtonStyle<sup>10+</sup>枚举说明 672 673**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 674 675**系统能力：** SystemCapability.ArkUI.ArkUI.Full 676 677| 名称 | 说明 | 678| ----------------------- | ---------------- | 679| CONSTANT | 清除按钮常显样式。 | 680| INVISIBLE | 清除按钮常隐样式。 | 681| INPUT | 清除按钮输入样式。 | 682 683## SearchType<sup>11+</sup>枚举说明 684 685**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 686 687**系统能力：** SystemCapability.ArkUI.ArkUI.Full 688 689| 名称 | 值 | 说明 | 690| ------------------ | ------ | ------------- | 691| NORMAL | 0 | 基本输入模式。<br/>支持输入数字、字母、下划线、空格、特殊字符。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 692| NUMBER | 2 | 纯数字输入模式。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 693| PHONE_NUMBER | 3 | 电话号码输入模式。<br/>支持输入数字、空格、+ 、-、*、#、(、)，长度不限。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 694| EMAIL | 5 | 邮箱地址输入模式。<br/>支持数字，字母，下划线、小数点、!、#、$、%、&、'、*、+、-、/、=、?、^、`、\{、\|、\}、~，以及@字符（只能存在一个@字符）。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 695| NUMBER_DECIMAL<sup>12+</sup> | 12 | 带小数点的数字输入模式。<br/>支持数字，小数点（只能存在一个小数点）。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 696| URL<sup>12+</sup> | 13 | 带URL的输入模式。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 697 698## CancelButtonOptions<sup>12+</sup>对象说明 699 700**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 701 702**系统能力：** SystemCapability.ArkUI.ArkUI.Full 703 704| 名称 | 类型 | 必填 | 说明 | 705| --------- | ------------------------------------------ | ---- | ---------------- | 706| style | [CancelButtonStyle](#cancelbuttonstyle10枚举说明) | 否 | 右侧清除按钮显示状态。 | 707| icon | [IconOptions](#iconoptions10对象说明) | 否 | 右侧清除按钮图标。 | 708 709## CancelButtonSymbolOptions<sup>12+</sup>对象说明 710 711**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 712 713**系统能力：** SystemCapability.ArkUI.ArkUI.Full 714 715| 名称 | 类型 | 必填 | 说明 | 716| --------- | ------------------------------------------ | ---- | ---------------- | 717| style | [CancelButtonStyle](#cancelbuttonstyle10枚举说明) | 否 | 右侧清除按钮显示状态。 | 718| icon | [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | 否 | 右侧清除按钮Symbol图标。 | 719 720## 事件 721 722除支持[通用事件](ts-component-general-events.md)外，还支持以下事件： 723 724### onSubmit 725 726onSubmit(callback: Callback\<string>) 727 728点击搜索图标、搜索按钮或者按下软键盘搜索按钮时触发该回调。 729 730**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 731 732**系统能力：** SystemCapability.ArkUI.ArkUI.Full 733 734**参数：** 735 736| 参数名 | 类型 | 必填 | 说明 | 737| ------ | ------ | ---- | ---------------------------- | 738| callback | Callback\<string> | 是 | 搜索提交回调，其返回值为当前搜索框中输入的文本内容。 | 739 740### onSubmit<sup>14+</sup> 741 742onSubmit(callback: SearchSubmitCallback) 743 744点击搜索图标、搜索按钮或者按下软键盘搜索按钮时触发该回调事件，提交事件时提供保持Search编辑状态的方法。 745 746**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 747 748**系统能力：** SystemCapability.ArkUI.ArkUI.Full 749 750**参数：** 751 752| 参数名 | 类型 | 必填 | 说明 | 753| ------ | ------- | ---- | ----------------------------- | 754| callback | [SearchSubmitCallback](#searchsubmitcallback14) | 是 | 点击搜索图标、搜索按钮或者按下软键盘搜索按钮时的回调事件。 | 755 756### onChange 757 758onChange(callback: EditableTextOnChangeCallback) 759 760输入内容发生变化时，触发该回调。 761 762在本回调中，若执行了光标操作，需要开发者在预上屏场景下依据previewText参数调整光标逻辑，以适应预上屏场景。 763 764**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 765 766**系统能力：** SystemCapability.ArkUI.ArkUI.Full 767 768**参数：** 769 770| 参数名 | 类型 | 必填 | 说明 | 771| ------ | ------ | ---- | ---------------------------- | 772| callback | [EditableTextOnChangeCallback](ts-text-common.md#editabletextonchangecallback12) | 是 | 当前输入文本内容变化时的回调。 | 773 774### onCopy 775 776onCopy(callback:Callback\<string>) 777 778进行复制操作时，触发该回调。 779 780**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 781 782**系统能力：** SystemCapability.ArkUI.ArkUI.Full 783 784**参数：** 785 786| 参数名 | 类型 | 必填 | 说明 | 787| --------- | ------- | ---- | ---------------- | 788| callback | Callback\<string> | 是 | 复制回调，其返回值为复制的文本内容。 | 789 790### onCut 791 792onCut(callback:Callback\<string>) 793 794进行剪切操作时，触发该回调。 795 796**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 797 798**系统能力：** SystemCapability.ArkUI.ArkUI.Full 799 800**参数：** 801 802| 参数名 | 类型 | 必填 | 说明 | 803| --------- | ------- | ---- | ---------------- | 804| callback | Callback\<string> | 是 | 剪切回调，其返回值为剪切的文本内容。 | 805 806### onPaste 807 808onPaste(callback:OnPasteCallback ) 809 810进行粘贴操作时，触发该回调。 811 812**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 813 814**系统能力：** SystemCapability.ArkUI.ArkUI.Full 815 816**参数：** 817| 参数名 | 类型 | 必填 | 说明 | 818| ------------------- | ------------------------------------------------------------ | ---- | ---------------------- | 819| callback | [OnPasteCallback](ts-basic-components-textinput.md#onpastecallback18) | 是 | 粘贴回调。 | 820 821### onTextSelectionChange<sup>10+</sup> 822 823onTextSelectionChange(callback: OnTextSelectionChangeCallback) 824 825文本选择的位置或编辑状态下光标位置发生变化时，触发该回调。 826 827**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 828 829**系统能力：** SystemCapability.ArkUI.ArkUI.Full 830 831**参数：** 832 833| 参数名 | 类型 | 必填 | 说明 | 834| -------------- | ------ | ---- | ------------------------------------------------- | 835| callback | [OnTextSelectionChangeCallback](ts-basic-components-textinput.md#ontextselectionchangecallback18) | 是 | 文本选择变化回调或光标位置变化回调。 | 836 837### onContentScroll<sup>10+</sup> 838 839onContentScroll(callback: OnContentScrollCallback) 840 841文本内容滚动时，触发该回调。 842 843**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 844 845**系统能力：** SystemCapability.ArkUI.ArkUI.Full 846 847**参数：** 848 849| 参数名 | 类型 | 必填 | 说明 | 850| ------------ | ------ | ---- | ---------------------------------- | 851| callback | [OnContentScrollCallback](ts-basic-components-textinput.md#oncontentscrollcallback18) | 是 | 文本内容滚动回调。 | 852 853### onEditChange<sup>12+</sup> 854 855onEditChange(callback: Callback< boolean >) 856 857输入状态变化时，触发该回调。有光标时为编辑态，无光标时为非编辑态。callback返回值为true表示正在输入。 858 859**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 860 861**系统能力：** SystemCapability.ArkUI.ArkUI.Full 862 863**参数：** 864 865| 参数名 | 类型 | 必填 | 说明 | 866| --------- | ---------------------------------- | ---- | -------------------- | 867| callback | Callback< boolean > | 是 | 编辑状态改变回调，其返回值为true表示正在输入。 | 868 869### onWillInsert<sup>12+</sup> 870 871onWillInsert(callback: Callback\<InsertValue, boolean>) 872 873在将要输入时，触发该回调。 874 875**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 876 877**系统能力：** SystemCapability.ArkUI.ArkUI.Full 878 879**参数：** 880 881| 参数名 | 类型 | 必填 | 说明 | 882| ------ | ------------------------------------------------------------ | ---- | ------------------ | 883| callback | Callback\<[InsertValue](ts-text-common.md#insertvalue12对象说明), boolean> | 是 | 在将要输入时调用的回调。<br/>在返回true时，表示正常插入，返回false时，表示不插入。<br/>在预上屏和候选词操作时，该回调不触发。<br/>仅支持系统输入法输入的场景。 | 884 885### onDidInsert<sup>12+</sup> 886 887onDidInsert(callback: Callback\<InsertValue>) 888 889在输入完成时，触发该回调。 890 891**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 892 893**系统能力：** SystemCapability.ArkUI.ArkUI.Full 894 895**参数：** 896 897| 参数名 | 类型 | 必填 | 说明 | 898| ------ | ------------------------------------------------------------ | ---- | ------------------ | 899| callback | Callback\<[InsertValue](ts-text-common.md#insertvalue12对象说明)> | 是 | 在输入完成时调用的回调。<br/>仅支持系统输入法输入的场景。 | 900 901### onWillDelete<sup>12+</sup> 902 903onWillDelete(callback: Callback\<DeleteValue, boolean>) 904 905在将要删除时，触发该回调。 906 907**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 908 909**系统能力：** SystemCapability.ArkUI.ArkUI.Full 910 911**参数：** 912 913| 参数名 | 类型 | 必填 | 说明 | 914| ------ | ------------------------------------------------------------ | ---- | ------------------ | 915| callback | Callback\<[DeleteValue](ts-text-common.md#deletevalue12对象说明), boolean> | 是 | 在将要删除时调用的回调。<br/>在返回true时，表示正常删除，返回false时，表示不删除。<br/>在预上屏删除操作时，该回调不触发。<br/>仅支持系统输入法输入的场景。 | 916 917### onDidDelete<sup>12+</sup> 918 919onDidDelete(callback: Callback\<DeleteValue>) 920 921在删除完成时，触发该回调。 922 923**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 924 925**系统能力：** SystemCapability.ArkUI.ArkUI.Full 926 927**参数：** 928 929| 参数名 | 类型 | 必填 | 说明 | 930| ------ | ------------------------------------------------------------ | ---- | ------------------ | 931| callback | Callback\<[DeleteValue](ts-text-common.md#deletevalue12对象说明)> | 是 | 在删除完成时调用的回调。<br/>仅支持系统输入法输入的场景。 | 932 933### onWillChange<sup>15+</sup> 934 935onWillChange(callback: Callback\<EditableTextChangeValue, boolean>) 936 937在文本内容将要发生变化时，触发该回调。 938 939onWillChange的回调时序晚于onWillInsert、onWillDelete，早于onDidInsert、onDidDelete。 940 941**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 942 943**系统能力：** SystemCapability.ArkUI.ArkUI.Full 944 945**参数：** 946 947| 参数名 | 类型 | 必填 | 说明 | 948| ------ | ------------------------------------------------------------ | ---- | ------------------ | 949| callback | Callback\<[EditableTextChangeValue](ts-text-common.md#editabletextchangevalue15), boolean> | 是 | 在文本内容将要发生变化时的回调。<br/>返回true时，表示正常修改。返回false时，表示拦截此次触发。 | 950 951## SearchController 952 953Search组件的控制器继承自[TextContentControllerBase](ts-types.md#textcontentcontrollerbase10)。 954 955### 导入对象 956``` 957controller: SearchController = new SearchController() 958``` 959 960### constructor<sup>8+</sup> 961 962constructor() 963 964SearchController的构造函数。 965 966**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 967 968**系统能力：** SystemCapability.ArkUI.ArkUI.Full 969 970### caretPosition<sup>8+</sup> 971 972caretPosition(value: number): void 973 974设置输入光标的位置。 975 976**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 977 978**系统能力：** SystemCapability.ArkUI.ArkUI.Full 979 980**参数:** 981 982| 参数名 | 类型 | 必填 | 说明 | 983| ------ | -------- | ---- | ---------------------------------- | 984| value | number | 是 | 从字符串开始到光标所在位置的长度。 | 985 986### stopEditing<sup>10+</sup> 987 988stopEditing(): void 989 990退出编辑态。 991 992**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 993 994**系统能力：** SystemCapability.ArkUI.ArkUI.Full 995 996### setTextSelection<sup>12+</sup> 997 998setTextSelection(selectionStart: number, selectionEnd: number, options?: SelectionOptions): void; 999 1000组件在获焦状态下，调用该接口设置文本选择区域并高亮显示，且只有在selectionStart小于selectionEnd时，文字才会被选取并高亮显示。 1001 1002**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1003 1004**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1005 1006**参数：** 1007 1008| 参数名 | 类型 | 必填 | 说明 | 1009| -------------- | -------- | ---- | -------- | 1010| selectionStart | number | 是 | 文本选择区域起始位置，文本框中文字的起始位置为0。<br/>当selectionStart小于0时、按照0处理；当selectionStart大于文字最大长度时、按照文字最大长度处理。<br/> | 1011| selectionEnd | number | 是 | 文本选择区域结束位置。<br/>当selectionEnd小于0时、按照0处理；当selectionEnd大于文字最大长度时、按照文字最大长度处理。<br/> | 1012| options | [SelectionOptions](ts-types.md#selectionoptions12对象说明) | 否 | 选中文字时的配置。<br />默认值：MenuPolicy.DEFAULT。 | 1013 1014> **说明：** 1015> 1016> 如果selectionStart或selectionEnd被赋值为undefined时，当作0处理。 1017> 1018> 如果selectionMenuHidden被赋值为true或设备为2in1时，即使options被赋值为MenuPolicy.SHOW，调用setTextSelection也不弹出菜单。 1019> 1020> 如果选中的文本含有emoji表情时，表情的起始位置包含在设置的文本选中区域内就会被选中。 1021 1022## SearchSubmitCallback<sup>14+</sup> 1023 1024type SearchSubmitCallback = (searchContent: string, event?: SubmitEvent) => void 1025 1026点击搜索图标、搜索按钮或者按下软键盘搜索按钮时的回调事件。 1027 1028**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 1029 1030**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1031 1032**参数：** 1033 1034| 参数名 | 类型 | 必填 | 说明 | 1035| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- | 1036| searchContent | string | 是 | 当前搜索框中输入的文本内容。 | 1037| event | [SubmitEvent](ts-basic-components-textinput.md#submitevent11) | 否 | 提交事件。 | 1038 1039## 示例 1040 1041### 示例1（设置与获取光标位置） 1042 1043该示例通过controller实现了光标位置的设置与获取的功能。 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 // 设置光标位置到输入的第一个字符后 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### 示例2（设置搜索和删除图标） 1091 1092该示例通过searchButton、searchIcon、cancelButton属性展示了设置搜索和删除图标的效果。 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### 示例3（设置自定义键盘） 1139 1140该示例通过customKeyboard属性实现了自定义键盘的功能。 1141 1142```ts 1143// xxx.ets 1144@Entry 1145@Component 1146struct SearchExample { 1147 controller: SearchController = new SearchController() 1148 @State inputValue: string = "" 1149 1150 // 自定义键盘组件 1151 @Builder CustomKeyboardBuilder() { 1152 Column() { 1153 Button('x').onClick(() => { 1154 // 关闭自定义键盘 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 // 绑定自定义键盘 1174 .customKeyboard(this.CustomKeyboardBuilder()).margin(10).border({ width: 1 }) 1175 } 1176 } 1177} 1178``` 1179 1180 1181 1182### 示例4（设置输入法回车键类型） 1183 1184该示例通过enterKeyType属性实现了动态切换输入法回车键的效果。 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: '请输入文本', 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('改变EnterKeyType').onClick(() => { 1207 this.index = (this.index + 1) % this.enterTypes.length; 1208 }) 1209 }.width('100%') 1210 } 1211} 1212``` 1213 1214 1215 1216### 示例5（设置文本样式） 1217 1218该示例通过lineHeight、letterSpacing、decoration属性展示了不同样式的文本效果。 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### 示例6（设置文字特性效果） 1266 1267该示例通过fontFeature属性实现了文本在不同文字特性下的展示效果。 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### 示例7（自定义键盘避让） 1294 1295该示例通过自定义键盘实现了键盘避让的功能。 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 // 自定义键盘组件 1308 @Builder 1309 CustomKeyboardBuilder() { 1310 Column() { 1311 Row() { 1312 Button('x').onClick(() => { 1313 // 关闭自定义键盘 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 })// 绑定自定义键盘 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### 示例8（设置文本自适应） 1368 1369该示例通过minFontSize、maxFontSize属性展示了文本自适应字号的效果。 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### 示例9（支持插入和删除回调） 1398 1399该示例通过onWillInsert、onDidInsert、onWillDelete、onDidDelete接口实现了插入和删除的功能。 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: "Search支持插入回调文本" }) 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: "Search支持删除回调文本b" }) 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### 示例10（文本扩展自定义菜单） 1452 1453该示例通过editMenuOptions接口实现了文本设置自定义菜单扩展项的文本内容、图标以及回调的功能。 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: 'custom1', 1464 icon: $r('app.media.startIcon'), 1465 id: TextMenuItemId.of('custom1'), 1466 } 1467 let item2: TextMenuItem = { 1468 content: 'custom2', 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("拦截 id: custom2 start:" + textRange.start + "; end:" + textRange.end) 1479 return true 1480 } 1481 if (menuItem.id.equals(TextMenuItemId.COPY)) { 1482 console.log("拦截 COPY start:" + textRange.start + "; end:" + textRange.end) 1483 return true 1484 } 1485 if (menuItem.id.equals(TextMenuItemId.SELECT_ALL)) { 1486 console.log("不拦截 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### 示例11（设置symbol类型清除按钮） 1511 1512该示例通过searchIcon、cancelButton属性展示了自定义右侧symbol类型清除按钮样式的效果。 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### 示例12（设置文本是否可复制） 1551 1552该示例通过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### 示例13（设置文本水平对齐/光标样式/选中背景色） 1608 1609该示例通过textAlign、caretStyle、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### 示例14（设置默认获焦并拉起软键盘） 1638 1639该示例通过defaultFocus、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### 示例15（关闭系统文本选择菜单） 1673 1674该示例通过selectionMenuHidden属性展示如何关闭系统文本选择菜单。 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### 示例16（对输入的文本进行过滤） 1701 1702该示例通过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### 示例17（设置选中指定区域的文本内容） 1734 1735该示例通过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, { menuPolicy: MenuPolicy.SHOW }) 1764 }) 1765 } 1766 .width('100%') 1767 .height('100%') 1768 } 1769} 1770``` 1771 1772 1773 1774### 示例18（设置文本滚动事件） 1775 1776该示例通过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### 示例19（设置最小字体范围与最大字体范围） 1808 1809该示例通过minFontScale、maxFontScale设置字体显示最小与最大范围。 1810 1811```json 1812// 开启应用缩放跟随系统 1813// AppScope/resources/base，新建文件夹profile。 1814// AppScope/resources/base/profile，新建文件configuration.json。 1815// AppScope/resources/base/profile/configuration.json，增加如下代码。 1816{ 1817 "configuration": { 1818 "fontSizeScale": "followSystem", 1819 "fontSizeMaxScale": "3.2" 1820 } 1821} 1822``` 1823 1824```json 1825// AppScope/app.json5，修改如下代码。 1826{ 1827 "app": { 1828 "bundleName": "com.example.myapplication", 1829 "vendor": "example", 1830 "versionCode": 1000000, 1831 "versionName": "1.0.0", 1832 "icon": "$media:app_icon", 1833 "label": "$string:app_name", 1834 "configuration": "$profile:configuration" 1835 } 1836} 1837``` 1838 1839```ts 1840// xxx.ets 1841@Entry 1842@Component 1843struct SearchExample { 1844 @State minFontScale: number = 0.85; 1845 @State maxFontScale: number = 2; 1846 1847 build() { 1848 Column() { 1849 Column({ space: 30 }) { 1850 Text("系统字体变大变小，变大变小aaaaaaaAAAAAA") 1851 Search({ 1852 placeholder: 'The text area can hold an unlimited amount of text. input your word...', 1853 }) 1854 .minFontScale(this.minFontScale)// 设置最小字体缩放倍数，参数为undefined则跟随系统默认倍数缩放 1855 .maxFontScale(this.maxFontScale)// 设置最大字体缩放倍数，参数为undefined则跟随系统默认倍数缩放 1856 }.width('100%') 1857 } 1858 } 1859} 1860```
