1# Search 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @kangshihui--> 5<!--Designer: @pssea--> 6<!--Tester: @jiaoaozihao--> 7<!--Adviser: @HelloCrease--> 8 9搜索框组件，适用于浏览器的搜索内容输入框等应用场景。 10 11> **说明：** 12> 13> 该组件从API version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14> 15> 该组件仅支持单文本样式，若需实现富文本样式，建议使用[RichEditor](ts-basic-components-richeditor.md)组件。 16 17## 子组件 18 19无 20 21## 接口 22 23Search(options?: SearchOptions) 24 25**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 26 27**系统能力：** SystemCapability.ArkUI.ArkUI.Full 28 29**参数:** 30 31| 参数名 | 类型 | 必填 | 说明 | 32| ----------- | ------------- | ---- | ------------- | 33| options | [SearchOptions](#searchoptions18对象说明)| 否 | 搜索框组件初始化选项 | 34 35## SearchOptions<sup>18+</sup>对象说明 36 37Search初始化参数。 38 39> **说明：** 40> 41> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 42 43**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 44 45**系统能力：** SystemCapability.ArkUI.ArkUI.Full 46 47| 名称 | 类型 | 只读 | 可选 | 说明 | 48| ----------- | ------------- | ---- | ---- | ------------- | 49| value<sup>8+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 是 | 设置当前显示的搜索文本内容。<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开始，该接口支持在原子化服务中使用。 <br>从API version 20开始，支持Resource类型。| 50| placeholder<sup>8+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 是 | 设置无输入时的提示文本。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 51| 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开始，该接口支持在原子化服务中使用。 | 52| controller<sup>8+</sup> | [SearchController](#searchcontroller) | 否 | 是 | 设置Search组件控制器。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 53 54## 属性 55 56除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 57 58### searchButton 59 60searchButton(value: ResourceStr, option?: SearchButtonOptions) 61 62设置搜索框末尾搜索按钮。 63 64点击搜索按钮，同时触发onSubmit与onClick回调。 65 66Wearable设备上默认字体大小为18fp。 67 68**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 69 70**系统能力：** SystemCapability.ArkUI.ArkUI.Full 71 72**参数：** 73 74| 参数名 | 类型 | 必填 | 说明 | 75| ------ | ----------------------------------------------------- | ---- | ---------------------------- | 76| value | [ResourceStr](ts-types.md#resourcestr) | 是 | 搜索框末尾搜索按钮文本内容。 <br>从API version 20开始，支持Resource类型。| 77| option | [SearchButtonOptions](#searchbuttonoptions10对象说明) | 否 | 配置搜索框文本样式。<br />默认值：<br />{<br />fontSize: '16fp',<br />fontColor: '#ff3f97e9'<br />} | 78 79### placeholderColor 80 81placeholderColor(value: ResourceColor) 82 83设置placeholder文本颜色，Wearable设备上默认值为'#99ffffff'。 84 85**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 86 87**系统能力：** SystemCapability.ArkUI.ArkUI.Full 88 89**参数：** 90 91| 参数名 | 类型 | 必填 | 说明 | 92| ------ | ------------------------------------------ | ---- | ------------------------------------------------ | 93| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | placeholder文本颜色。<br />默认值：'#99182431'。 | 94 95### placeholderFont 96 97placeholderFont(value?: Font) 98 99设置placeholder文本样式，包括字体大小，字体粗细，字体族，字体风格。当前支持'HarmonyOS Sans'字体和注册自定义字体[loadFontSync](../../apis-arkgraphics2d/js-apis-graphics-text.md#loadfontsync)。 100 101Wearable设备上默认字体大小为18fp。 102 103**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 104 105**系统能力：** SystemCapability.ArkUI.ArkUI.Full 106 107**参数：** 108 109| 参数名 | 类型 | 必填 | 说明 | 110| ------ | ------------------------ | ---- | --------------------- | 111| value | [Font](ts-types.md#font) | 否 | placeholder文本样式。 | 112 113### textFont 114 115textFont(value?: Font) 116 117设置搜索框内输入文本样式，包括字体大小，字体粗细，字体族，字体风格。目前仅支持默认字体族。 118 119Wearable设备上默认字体大小为18fp。 120 121**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 122 123**系统能力：** SystemCapability.ArkUI.ArkUI.Full 124 125**参数：** 126 127| 参数名 | 类型 | 必填 | 说明 | 128| ------ | ------------------------ | ---- | ---------------------- | 129| value | [Font](ts-types.md#font) | 否 | 搜索框内输入文本样式。 | 130 131### textAlign<sup>9+</sup> 132 133textAlign(value: TextAlign) 134 135设置文本在搜索框中的对齐方式。目前支持的对齐方式有：Start、Center、End。 136 137**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 138 139**系统能力：** SystemCapability.ArkUI.ArkUI.Full 140 141**参数：** 142 143| 参数名 | 类型 | 必填 | 说明 | 144| ------ | ------------------------------------------- | ---- | ------------------------------------------------------ | 145| value | [TextAlign](ts-appendix-enums.md#textalign) | 是 | 文本在搜索框中的对齐方式。<br/>默认值：TextAlign.Start | 146 147> **说明：** 148> 149> textAlign只能调整文本整体的布局，不影响字符的显示顺序。若需要调整字符的显示顺序，请参考[镜像状态字符对齐](../../../ui/arkts-internationalization.md#镜像状态字符对齐)。 150 151### copyOption<sup>9+</sup> 152 153copyOption(value: CopyOptions) 154 155设置输入的文本是否可复制。设置CopyOptions.None时，当前Search中的文字无法被复制、剪切、翻译、分享、搜索和帮写，支持粘贴和全选。 156 157设置CopyOptions.None时，不允许拖拽。 158 159**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 160 161**系统能力：** SystemCapability.ArkUI.ArkUI.Full 162 163**参数：** 164 165| 参数名 | 类型 | 必填 | 说明 | 166| ------ | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 167| value | [CopyOptions](ts-appendix-enums.md#copyoptions9) | 是 | 输入的文本是否可复制。<br />默认值：CopyOptions.LocalDevice，支持设备内复制。 | 168 169### searchIcon<sup>10+</sup> 170 171searchIcon(value: IconOptions | SymbolGlyphModifier) 172 173设置左侧搜索图标样式。 174 175Wearable设备上默认图标大小为16vp。 176 177**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 178 179**系统能力：** SystemCapability.ArkUI.ArkUI.Full 180 181**参数：** 182 183| 参数名 | 类型 | 必填 | 说明 | 184| ------ | ------------------------------------- | ---- | ------------------ | 185| value | [IconOptions](#iconoptions10对象说明) \| [SymbolGlyphModifier](ts-universal-attributes-text-style.md#symbolglyphmodifier12) | 是 | 左侧搜索图标样式。<!--RP1--><br />浅色模式默认值：<br />{<br />size: '16vp',<br />color: '#99182431',<br />src: ' '<br />}<br />深色模式默认值：<br />{<br />size: '16vp',<br />color: '#99ffffff',<br />src: ' '<br />} <!--RP1End-->| 186 187### cancelButton<sup>10+</sup> 188 189cancelButton(value: CancelButtonOptions | CancelButtonSymbolOptions) 190 191设置右侧清除按钮样式。 192 193Wearable设备上默认图标大小为18fp。 194 195**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 196 197**系统能力：** SystemCapability.ArkUI.ArkUI.Full 198 199**参数：** 200 201| 参数名 | 类型 | 必填 | 说明 | 202| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 203| 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时，默认显示清除样式。 | 204 205### fontColor<sup>10+</sup> 206 207fontColor(value: ResourceColor) 208 209设置输入文本的字体颜色。fontSize、fontStyle、fontWeight和fontFamily在[textFont](#textfont)属性中设置。 210 211**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 212 213**系统能力：** SystemCapability.ArkUI.ArkUI.Full 214 215**参数：** 216 217| 参数名 | 类型 | 必填 | 说明 | 218| ------ | ------------------------------------------ | ---- | ----------------------------------------------- | 219| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 输入文本的字体颜色。<br/>默认值：'#FF182431'<br/>Wearable设备上默认值为：'#dbffffff' | 220 221### caretStyle<sup>10+</sup> 222 223caretStyle(value: CaretStyle) 224 225设置光标样式。 226 227**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 228 229**系统能力：** SystemCapability.ArkUI.ArkUI.Full 230 231**参数：** 232 233| 参数名 | 类型 | 必填 | 说明 | 234| ------ | ----------------------------------- | ---- | ------------------------------------------------------------ | 235| value | [CaretStyle](ts-text-common.md#caretstyle10) | 是 | 光标样式。<br />默认值：<br />{<br />width: '2.0vp',<br />color: '#007DFF'<br />} | 236 237> **说明：** 238> 从API version 12开始，此接口支持设置文本手柄颜色，光标和文本手柄颜色保持一致。 239 240### enableKeyboardOnFocus<sup>10+</sup> 241 242enableKeyboardOnFocus(value: boolean) 243 244设置Search通过点击以外的方式获焦时，是否主动拉起软键盘。 245 246从API version 10开始，获焦默认绑定输入法。 247 248**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 249 250**系统能力：** SystemCapability.ArkUI.ArkUI.Full 251 252**参数：** 253 254| 参数名 | 类型 | 必填 | 说明 | 255| ------ | ------- | ---- | ----------------------------------------------- | 256| value | boolean | 是 | Search获焦时，是否主动拉起软键盘。<br/>true表示主动拉起，false表示不主动拉起。<br/>默认值：true | 257 258### selectionMenuHidden<sup>10+</sup> 259 260selectionMenuHidden(value: boolean) 261 262设置是否不弹出系统文本选择菜单。 263 264**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 265 266**系统能力：** SystemCapability.ArkUI.ArkUI.Full 267 268**参数：** 269 270| 参数名 | 类型 | 必填 | 说明 | 271| ------ | ------- | ---- | ------------------------------------------------------------ | 272| value | boolean | 是 | 是否不弹出系统文本选择菜单。<br />设置为true时，单击输入框光标、长按输入框、双击输入框、三击输入框或者右键输入框，不弹出系统文本选择菜单。<br />设置为false时，弹出系统文本选择菜单。<br />默认值：false | 273 274### customKeyboard<sup>10+</sup> 275 276customKeyboard(value: CustomBuilder, options?: KeyboardOptions) 277 278设置自定义键盘。 279 280当设置自定义键盘时，输入框激活后不会打开系统输入法，而是加载指定的自定义组件。 281 282自定义键盘的高度可以通过自定义组件根节点的height属性设置，宽度不可设置，使用系统默认值。 283 284自定义键盘采用覆盖原始界面的方式呈现，当没有开启避让模式或者输入框不需要避让的场景不会对应用原始界面产生压缩或者上提。 285 286自定义键盘无法获取焦点，但是会拦截手势事件。 287 288默认在输入控件失去焦点时，关闭自定义键盘，开发者也可以通过[stopEditing](#stopediting10)方法控制键盘关闭。 289 290如果设备支持拍摄输入，设置自定义键盘后，该输入框会不支持拍摄输入。 291 292当设置自定义键盘时，可以通过绑定[onKeyPrelme](ts-universal-events-key.md#onkeypreime12)事件规避物理键盘的输入。 293 294**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 295 296**系统能力：** SystemCapability.ArkUI.ArkUI.Full 297 298**参数：** 299 300| 参数名 | 类型 | 必填 | 说明 | 301| --------------------- | ------------------------------------------- | ---- | -------------------------------- | 302| value | [CustomBuilder](ts-types.md#custombuilder8) | 是 | 自定义键盘。 | 303| options<sup>12+</sup> | [KeyboardOptions](ts-basic-components-richeditor.md#keyboardoptions12) | 否 | 设置自定义键盘是否支持避让功能。 | 304 305### type<sup>11+</sup> 306 307type(value: SearchType) 308 309设置输入框类型。 310 311**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 312 313**系统能力：** SystemCapability.ArkUI.ArkUI.Full 314 315**参数：** 316 317| 参数名 | 类型 | 必填 | 说明 | 318| ------ | ----------------------------------- | ---- | -------------------------- | 319| value | [SearchType](#searchtype11枚举说明) | 是 | 输入框类型。<br/>默认值：SearchType.Normal | 320 321### maxLength<sup>11+</sup> 322 323maxLength(value: number) 324 325设置文本的最大输入字符数。默认不设置最大输入字符数限制。到达文本最大字符限制，将无法继续输入字符。 326 327**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 328 329**系统能力：** SystemCapability.ArkUI.ArkUI.Full 330 331**参数：** 332 333| 参数名 | 类型 | 必填 | 说明 | 334| ------ | ----------------------------------- | ---- | ---------------------- | 335| value | number | 是 | 文本的最大输入字符数。 | 336 337### enterKeyType<sup>12+</sup> 338 339enterKeyType(value: EnterKeyType) 340 341设置输入法回车键类型。 342 343**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 344 345**系统能力：** SystemCapability.ArkUI.ArkUI.Full 346 347**参数：** 348 349| 参数名 | 类型 | 必填 | 说明 | 350| ------ | ------------------------------------------------ | ---- | -------------------------------------------------- | 351| value | [EnterKeyType](ts-basic-components-textinput.md#enterkeytype枚举说明) | 是 | 输入法回车键类型。<br/>默认值：EnterKeyType.Search | 352 353### lineHeight<sup>12+</sup> 354 355lineHeight(value: number | string | Resource) 356 357设置文本的文本行高，设置值不大于0时，不限制文本行高，自适应字体大小，number类型时单位为fp。 358 359**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 360 361**系统能力：** SystemCapability.ArkUI.ArkUI.Full 362 363**参数：** 364 365| 参数名 | 类型 | 必填 | 说明 | 366| ------ | ------------------------------------------------------------ | ---- | ---------------- | 367| value | number \| string \| [Resource](ts-types.md#resource) | 是 | 文本的文本行高。 | 368 369> **说明：** 370> 371> 特殊字符字体高度远超出同行的其他字符高度时，文本框出现截断、遮挡、内容相对位置发生变化等不符合预期的显示异常，需要开发者调整组件高度、行高等属性，修改对应的页面布局。 372 373### decoration<sup>12+</sup> 374 375decoration(value: TextDecorationOptions) 376 377设置文本装饰线类型样式及其颜色。 378 379**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 380 381**系统能力：** SystemCapability.ArkUI.ArkUI.Full 382 383**参数：** 384 385| 参数名 | 类型 | 必填 | 说明 | 386| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 387| value | [TextDecorationOptions](ts-universal-attributes-text-style.md#textdecorationoptions12对象说明) | 是 | 文本装饰线对象。<br />默认值：{<br/> type: TextDecorationType.None,<br/> color: Color.Black,<br/> style: TextDecorationStyle.SOLID <br/>} | 388 389### letterSpacing<sup>12+</sup> 390 391letterSpacing(value: number | string | Resource) 392 393设置文本字符间距。设置该值为百分比时，按默认值显示。设置该值为0时，按默认值显示。string类型支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"。 394 395当取值为负值时，文字会发生压缩，负值过小时会将组件内容区大小压缩为0，导致无内容显示。 396 397对每个字符生效，包括行尾字符。 398 399**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 400 401**系统能力：** SystemCapability.ArkUI.ArkUI.Full 402 403**参数：** 404 405| 参数名 | 类型 | 必填 | 说明 | 406| ------ | -------------------------- | ---- | -------------- | 407| value | number \| string \| [Resource](ts-types.md#resource) | 是 | 文本字符间距。<br/>单位：[fp](ts-pixel-units.md) | 408 409### fontFeature<sup>12+</sup> 410 411fontFeature(value: string) 412 413设置文字特性效果，比如数字等宽的特性。 414 415格式为：normal \| \<feature-tag-value\> 416 417\<feature-tag-value\>的格式为：\<string\> \[ \<integer\> \| on \| off ] 418 419\<feature-tag-value\>的个数可以有多个，中间用','隔开。 420 421例如，使用等宽数字的输入格式为："ss01" on。 422 423**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 424 425**系统能力：** SystemCapability.ArkUI.ArkUI.Full 426 427**参数：** 428 429| 参数名 | 类型 | 必填 | 说明 | 430| ------ | ------ | ---- | -------------- | 431| value | string | 是 | 文字特性效果。 | 432 433Font Feature当前支持的属性见 [fontFeature属性列表](ts-basic-components-text.md#fontfeature12)。 434设置 Font Feature 属性，Font Feature 是 OpenType 字体的高级排版能力，如支持连字、数字等宽等特性，一般用在自定义字体中，其能力需要字体本身支持。 435更多 Font Feature 能力介绍可参考 https://www.w3.org/TR/css-fonts-3/#font-feature-settings-prop 和 https://sparanoid.com/lab/opentype-features/ 436 437### selectedBackgroundColor<sup>12+</sup> 438 439selectedBackgroundColor(value: ResourceColor) 440 441设置文本选中底板颜色。如果未设置不透明度，默认为20%不透明度。 442 443**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 444 445**系统能力：** SystemCapability.ArkUI.ArkUI.Full 446 447**参数：** 448 449| 参数名 | 类型 | 必填 | 说明 | 450| ------ | ------------------------------------------ | ---- | ------------------------------------------ | 451| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 文本选中底板颜色。 | 452 453### inputFilter<sup>12+</sup> 454 455inputFilter(value: ResourceStr, error?: Callback< string >) 456 457通过正则表达式设置输入过滤器。匹配表达式的输入允许显示，不匹配的输入将被过滤。 458 459单字符输入场景仅支持单字符匹配，多字符输入场景支持字符串匹配，例如粘贴。 460 461设置inputFilter且输入的字符不为空字符，会导致设置输入框类型(即type接口)附带的文本过滤效果失效。 462 463**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 464 465**系统能力：** SystemCapability.ArkUI.ArkUI.Full 466 467**参数：** 468 469| 参数名 | 类型 | 必填 | 说明 | 470| ------ | -------------------------------------- | ---- | ---------------------------------- | 471| value | [ResourceStr](ts-types.md#resourcestr) | 是 | 正则表达式。 | 472| error | Callback< string > | 否 | 正则匹配失败时，返回被过滤的内容。 | 473 474### textIndent<sup>12+</sup> 475 476textIndent(value: Dimension) 477 478设置首行文本缩进。 479 480**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 481 482**系统能力：** SystemCapability.ArkUI.ArkUI.Full 483 484**参数：** 485 486| 参数名 | 类型 | 必填 | 说明 | 487| ------ | ----------------------------------- | ---- | ---------------------------- | 488| value | [Dimension](ts-types.md#dimension10)| 是 | 首行文本缩进。<br/>默认值：0 | 489 490### minFontSize<sup>12+</sup> 491 492minFontSize(value: number | string | Resource) 493 494设置文本最小显示字号。string类型支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"。 495 496需配合[maxFontSize](#maxfontsize12)以及布局大小限制使用，单独设置不生效。 497 498自适应字号生效时，fontSize设置不生效。 499 500minFontSize小于或等于0时，自适应字号不生效，此时按照[textFont](#textfont)属性里面size的取值生效，未设置时按照其默认值生效。 501 502**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 503 504**系统能力：** SystemCapability.ArkUI.ArkUI.Full 505 506**参数：** 507 508| 参数名 | 类型 | 必填 | 说明 | 509| ------ | ------------------------------------------------------------ | ---- | ------------------ | 510| value | number \| string \| [Resource](ts-types.md#resource) | 是 | 文本最小显示字号。<br/>单位：[fp](ts-pixel-units.md) | 511 512### maxFontSize<sup>12+</sup> 513 514maxFontSize(value: number | string | Resource) 515 516设置文本最大显示字号。string类型支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"。 517 518需配合[minFontSize](#minfontsize12)以及布局大小限制使用，单独设置不生效。 519 520自适应字号生效时，fontSize设置不生效。 521 522maxFontSize小于等于0或者maxFontSize小于minFontSize时，自适应字号不生效，此时按照[textFont](#textfont)属性里面size的取值生效，未设置时按照其默认值生效。 523 524**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 525 526**系统能力：** SystemCapability.ArkUI.ArkUI.Full 527 528**参数：** 529 530| 参数名 | 类型 | 必填 | 说明 | 531| ------ | ------------------------------------------------------------ | ---- | ------------------ | 532| value | number \| string \| [Resource](ts-types.md#resource) | 是 | 文本最大显示字号。<br/>单位：[fp](ts-pixel-units.md) | 533 534### halfLeading<sup>18+</sup> 535 536halfLeading(halfLeading: Optional\<boolean>) 537 538设置文本是否将行间距平分至行的顶部与底部。 539 540**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 541 542**系统能力：** SystemCapability.ArkUI.ArkUI.Full 543 544**参数：** 545 546| 参数名 | 类型 | 必填 | 说明 | 547| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 548| halfLeading | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<boolean> | 是 | 文本是否将行间距平分至行的顶部与底部。<br/>true表示将行间距平分至行的顶部与底部，false则不平分。<br/>默认值：false | 549 550### minFontScale<sup>18+</sup> 551 552minFontScale(scale: Optional\<number | Resource>) 553 554设置文本最小的字体缩放倍数。 555 556**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 557 558**系统能力：** SystemCapability.ArkUI.ArkUI.Full 559 560**参数：** 561 562| 参数名 | 类型 | 必填 | 说明 | 563| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 564| scale | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<number \| [Resource](ts-types.md#resource)> | 是 | 文本最小的字体缩放倍数，支持undefined类型。<br/>取值范围：[0, 1]<br/>**说明：** <br/>设置的值小于0时，按值为0处理。设置的值大于1，按值为1处理。异常值默认不生效。<br/>使用前需在工程中配置configuration.json文件和app.json5文件，具体详见[示例19设置最小字体范围与最大字体范围](#示例19设置最小字体范围与最大字体范围)。 | 565 566### maxFontScale<sup>18+</sup> 567 568maxFontScale(scale: Optional\<number | Resource>) 569 570设置文本最大的字体缩放倍数。 571 572**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 573 574**系统能力：** SystemCapability.ArkUI.ArkUI.Full 575 576**参数：** 577 578| 参数名 | 类型 | 必填 | 说明 | 579| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 580| scale | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<number \| [Resource](ts-types.md#resource)> | 是 | 文本最大的字体缩放倍数，支持undefined类型。<br/>取值范围：[1, +∞)<br/>**说明：** <br/>设置的值小于1时，按值为1处理。异常值默认不生效。<br/>设置maxFontScale属性后，search组件内容最多放大到2倍。<br/>使用前需在工程中配置configuration.json文件和app.json5文件，具体详见[示例19设置最小字体范围与最大字体范围](#示例19设置最小字体范围与最大字体范围)。 | 581 582### editMenuOptions<sup>12+</sup> 583 584editMenuOptions(editMenu: EditMenuOptions) 585 586设置自定义菜单扩展项，允许用户设置扩展项的文本内容、图标、回调方法。 587 588调用[disableMenuItems](../arkts-apis-uicontext-textmenucontroller.md#disablemenuitems20)或[disableSystemServiceMenuItems](../arkts-apis-uicontext-textmenucontroller.md#disablesystemservicemenuitems20)接口屏蔽文本选择菜单内的系统服务菜单项时，editMenuOptions接口内回调方法[onCreateMenu](./ts-text-common.md#oncreatemenu12)的入参列表中不包含被屏蔽的菜单选项。 589 590**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 591 592**系统能力：** SystemCapability.ArkUI.ArkUI.Full 593 594**参数：** 595 596| 参数名 | 类型 | 必填 | 说明 | 597| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 598| editMenu | [EditMenuOptions](ts-text-common.md#editmenuoptions) | 是 | 扩展菜单选项。 | 599 600### enablePreviewText<sup>12+</sup> 601 602enablePreviewText(enable: boolean) 603 604设置是否开启输入预上屏。 605 606预上屏内容定义为文字暂存态，目前不支持文字拦截功能，因此不触发[onWillInsert](#onwillinsert12)、[onDidInsert](#ondidinsert12)、[onWillDelete](#onwilldelete12)、[onDidDelete](#ondiddelete12)回调。 607 608**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 609 610**系统能力：** SystemCapability.ArkUI.ArkUI.Full 611 612**参数：** 613 614| 参数名 | 类型 | 必填 | 说明 | 615| ------ | ------- | ---- | ---------------------------------- | 616| enable | boolean | 是 | 是否开启输入预上屏。<br/>true表示开启输入预上屏，false表示不开启输入预上屏。<br/>默认值：true | 617 618> **说明：** 619> 620> “预上屏”描述的是一种文字暂存状态。需要在输入法中开启预上屏功能，在输入文本过程中，未确认输入候选词时，文本框中显示标记文本。例如，通过拼音输入中文时，未确定候选词之前，在输入框中显示拼音字母，该状态称为文字预上屏。 621 622### enableHapticFeedback<sup>13+</sup> 623 624enableHapticFeedback(isEnabled: boolean) 625 626设置是否开启触控反馈。 627 628**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 629 630**系统能力：** SystemCapability.ArkUI.ArkUI.Full 631 632**参数：** 633 634| 参数名 | 类型 | 必填 | 说明 | 635| ------ | ------- | ---- | ---------------------------------- | 636| isEnabled | boolean | 是 | 是否开启触控反馈。<br/>true表示开启触控反馈，false表示不开启触控反馈。<br/>默认值：true | 637 638> **说明：** 639> 640> 开启触控反馈时，需要在工程的module.json5中配置requestPermissions字段以开启振动权限，配置如下： 641> ```json 642> "requestPermissions": [ 643> { 644> "name": "ohos.permission.VIBRATE", 645> } 646> ] 647> ``` 648 649### autoCapitalizationMode<sup>20+</sup> 650 651autoCapitalizationMode(mode: AutoCapitalizationMode) 652 653设置自动大小写模式的文本模式，只提供接口能力，具体实现以输入法应用为主。 654 655**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 656 657**系统能力：** SystemCapability.ArkUI.ArkUI.Full 658 659**参数：** 660 661| 参数名 | 类型 | 必填 | 说明 | 662| -------- | ----------------------------------------- | ---- | -------------------------- | 663| mode | [AutoCapitalizationMode](ts-text-common.md#autocapitalizationmode20枚举说明) | 是 | 自动大小写模式，默认状态无效。 | 664 665### keyboardAppearance<sup>15+</sup> 666 667keyboardAppearance(appearance: Optional\<KeyboardAppearance>) 668 669设置输入框拉起的键盘样式。 670 671**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 672 673**系统能力：** SystemCapability.ArkUI.ArkUI.Full 674 675**参数：** 676 677| 参数名 | 类型 | 必填 | 说明 | 678| ------ | ----------------------------------------- | ---- | ------------------------------------------------------ | 679| appearance | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[KeyboardAppearance](ts-text-common.md#keyboardappearance15枚举说明)> | 是 | 键盘样式。<br/>默认值：KeyboardAppearance.NONE_IMMERSIVE | 680 681### strokeWidth<sup>20+</sup> 682 683strokeWidth(width: Optional\<LengthMetrics>) 684 685设置文本描边的宽度。 686 687**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 688 689**系统能力：** SystemCapability.ArkUI.ArkUI.Full 690 691**参数：** 692 693| 参数名 | 类型 | 必填 | 说明 | 694| ------ | ------------------------------------------------------------ | ---- | ---------------- | 695| width | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12)> | 是 | 文本描边的宽度。当LengthMetrics的单位为px时，<br/>若设置值小于0，显示实心字；若大于0，显示空心字。<br/>默认值为0，不做描边处理。 | 696 697### strokeColor<sup>20+</sup> 698 699strokeColor(color: Optional\<ResourceColor>) 700 701设置文本描边的颜色。 702 703**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 704 705**系统能力：** SystemCapability.ArkUI.ArkUI.Full 706 707**参数：** 708 709| 参数名 | 类型 | 必填 | 说明 | 710| ------ | ------------------------------------------ | ---- | ---------- | 711| color | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[ResourceColor](ts-types.md#resourcecolor)> | 是 | 描边颜色。默认值为字体颜色，设置异常值时取默认值。| 712 713### stopBackPress<sup>15+</sup> 714 715stopBackPress(isStopped: Optional\<boolean>) 716 717设置是否阻止返回键向其它组件或应用侧传递。 718 719**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 720 721**系统能力：** SystemCapability.ArkUI.ArkUI.Full 722 723**参数：** 724 725| 参数名 | 类型 | 必填 | 说明 | 726| ------ | ------- | ---- | ---------------------------------- | 727| isStopped | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<boolean> | 是 | 是否阻止返回键。<br/>true表示阻止返回键向其它组件或应用侧传递，false表示不阻止。<br />默认值：true | 728 729### enableAutoSpacing<sup>20+</sup> 730 731enableAutoSpacing(enabled: Optional\<boolean>) 732 733设置是否开启中文与西文的自动间距。 734 735**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 736 737**系统能力：** SystemCapability.ArkUI.ArkUI.Full 738 739**参数：** 740 741| 参数名 | 类型 | 必填 | 说明 | 742| ------ | ------- | ---- | ---------------------------------- | 743| enabled | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<boolean> | 是 | 是否开启中文与西文的自动间距。<br/>true为开启自动间距，false为不开启。<br />默认值：false | 744 745## IconOptions<sup>10+</sup>对象说明 746 747**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 748 749**系统能力：** SystemCapability.ArkUI.ArkUI.Full 750 751| 名称 | 类型 | 只读 | 可选 | 说明 | 752| ------ | ------------------------------------------ | ---- | ---- | ----------- | 753| size | [Length](ts-types.md#length) | 否 | 是 | 图标尺寸，不支持百分比。 | 754| color | [ResourceColor](ts-types.md#resourcecolor) | 否 | 是 | 图标颜色。 | 755| src | [ResourceStr](ts-types.md#resourcestr) | 否 | 是 | 图标/图片源。 | 756 757## SearchButtonOptions<sup>10+</sup>对象说明 758 759**系统能力：** SystemCapability.ArkUI.ArkUI.Full 760 761| 名称 | 类型 | 只读 | 可选 | 说明 | 762| --------- | ------------------------------------------ | ---- | ---- | ---------------- | 763| fontSize | [Length](ts-types.md#length) | 否 | 是 | 文本按钮字体大小，不支持百分比。**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 764| fontColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 是 | 文本按钮字体颜色。**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 765| autoDisable<sup>18+</sup> | Boolean | 否 | 是 | Search无文本内容时按钮置灰且不可点击。<br/>默认值：false <br>true表示开启按钮置灰功能，false表示不开启。 <br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。| 766 767## CancelButtonStyle<sup>10+</sup>枚举说明 768 769**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 770 771**系统能力：** SystemCapability.ArkUI.ArkUI.Full 772 773| 名称 | 说明 | 774| ----------------------- | ---------------- | 775| CONSTANT | 清除按钮常显样式。 | 776| INVISIBLE | 清除按钮常隐样式。 | 777| INPUT | 清除按钮输入样式。 | 778 779## SearchType<sup>11+</sup>枚举说明 780 781**系统能力：** SystemCapability.ArkUI.ArkUI.Full 782 783| 名称 | 值 | 说明 | 784| ------------------ | ------ | ------------- | 785| NORMAL | 0 | 基本输入模式。<br/>支持输入数字、字母、下划线、空格、特殊字符。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 786| NUMBER | 2 | 纯数字输入模式。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 787| PHONE_NUMBER | 3 | 电话号码输入模式。<br/>支持输入数字、空格、+ 、-、*、#、(、)，长度不限。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 788| EMAIL | 5 | 邮箱地址输入模式。<br/>支持数字，字母，下划线、小数点、!、#、$、%、&、'、*、+、-、/、=、?、^、`、\{、\|、\}、~，以及@字符（只能存在一个@字符）。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 789| NUMBER_DECIMAL<sup>12+</sup> | 12 | 带小数点的数字输入模式。<br/>支持数字，小数点（只能存在一个小数点）。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 790| URL<sup>12+</sup> | 13 | 带URL的输入模式。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 791| ONE_TIME_CODE<sup>20+</sup> | 14 | 验证码输入模式。<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 792 793## CancelButtonOptions<sup>12+</sup>对象说明 794 795**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 796 797**系统能力：** SystemCapability.ArkUI.ArkUI.Full 798 799| 名称 | 类型 | 只读 | 可选 | 说明 | 800| --------- | ------------------------------------------ | ---- | ---- | ---------------- | 801| style | [CancelButtonStyle](#cancelbuttonstyle10枚举说明) | 否 | 是 | 右侧清除按钮显示状态。 | 802| icon | [IconOptions](#iconoptions10对象说明) | 否 | 是 | 右侧清除按钮图标。 | 803 804## CancelButtonSymbolOptions<sup>12+</sup>对象说明 805 806**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 807 808**系统能力：** SystemCapability.ArkUI.ArkUI.Full 809 810| 名称 | 类型 | 只读 | 可选 | 说明 | 811| --------- | ------------------------------------------ | ---- | ---- | ---------------- | 812| style | [CancelButtonStyle](#cancelbuttonstyle10枚举说明) | 否 | 是 | 右侧清除按钮显示状态。 | 813| icon | [SymbolGlyphModifier](ts-universal-attributes-text-style.md#symbolglyphmodifier12) | 否 | 是 | 右侧清除按钮Symbol图标。 | 814 815## 事件 816 817除支持[通用事件](ts-component-general-events.md)外，还支持以下事件： 818 819### onSubmit 820 821onSubmit(callback: Callback\<string>) 822 823点击搜索图标、搜索按钮或者按下软键盘搜索按钮时触发该回调。 824 825**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 826 827**系统能力：** SystemCapability.ArkUI.ArkUI.Full 828 829**参数：** 830 831| 参数名 | 类型 | 必填 | 说明 | 832| ------ | ------ | ---- | ---------------------------- | 833| callback | Callback\<string> | 是 | 搜索提交回调，其返回值为当前搜索框中输入的文本内容。 | 834 835### onSubmit<sup>14+</sup> 836 837onSubmit(callback: SearchSubmitCallback) 838 839点击搜索图标、搜索按钮或者按下软键盘搜索按钮时触发该回调事件，提交事件时提供保持Search编辑状态的方法。 840 841**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 842 843**系统能力：** SystemCapability.ArkUI.ArkUI.Full 844 845**参数：** 846 847| 参数名 | 类型 | 必填 | 说明 | 848| ------ | ------- | ---- | ----------------------------- | 849| callback | [SearchSubmitCallback](#searchsubmitcallback14) | 是 | 点击搜索图标、搜索按钮或者按下软键盘搜索按钮时的回调事件。 | 850 851### onChange 852 853onChange(callback: EditableTextOnChangeCallback) 854 855输入内容发生变化时，触发该回调。 856 857在本回调中，若执行了光标操作，需要开发者在预上屏场景下依据previewText参数调整光标逻辑，以适应预上屏场景。 858 859**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 860 861**系统能力：** SystemCapability.ArkUI.ArkUI.Full 862 863**参数：** 864 865| 参数名 | 类型 | 必填 | 说明 | 866| ------ | ------ | ---- | ---------------------------- | 867| callback | [EditableTextOnChangeCallback](ts-text-common.md#editabletextonchangecallback12) | 是 | 当前输入文本内容变化时的回调。 | 868 869### onCopy 870 871onCopy(callback:Callback\<string>) 872 873进行复制操作时，触发该回调。 874 875**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 876 877**系统能力：** SystemCapability.ArkUI.ArkUI.Full 878 879**参数：** 880 881| 参数名 | 类型 | 必填 | 说明 | 882| --------- | ------- | ---- | ---------------- | 883| callback | Callback\<string> | 是 | 复制回调，其返回值为复制的文本内容。 | 884 885### onCut 886 887onCut(callback:Callback\<string>) 888 889进行剪切操作时，触发该回调。 890 891**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 892 893**系统能力：** SystemCapability.ArkUI.ArkUI.Full 894 895**参数：** 896 897| 参数名 | 类型 | 必填 | 说明 | 898| --------- | ------- | ---- | ---------------- | 899| callback | Callback\<string> | 是 | 剪切回调，其返回值为剪切的文本内容。 | 900 901### onPaste 902 903onPaste(callback:OnPasteCallback ) 904 905进行粘贴操作时，触发该回调。 906 907**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 908 909**系统能力：** SystemCapability.ArkUI.ArkUI.Full 910 911**参数：** 912| 参数名 | 类型 | 必填 | 说明 | 913| ------------------- | ------------------------------------------------------------ | ---- | ---------------------- | 914| callback | [OnPasteCallback](ts-basic-components-textinput.md#onpastecallback18) | 是 | 粘贴回调。 | 915 916### onTextSelectionChange<sup>10+</sup> 917 918onTextSelectionChange(callback: OnTextSelectionChangeCallback) 919 920文本选择的位置或编辑状态下光标位置发生变化时，触发该回调。 921 922**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 923 924**系统能力：** SystemCapability.ArkUI.ArkUI.Full 925 926**参数：** 927 928| 参数名 | 类型 | 必填 | 说明 | 929| -------------- | ------ | ---- | ------------------------------------------------- | 930| callback | [OnTextSelectionChangeCallback](ts-basic-components-textinput.md#ontextselectionchangecallback18) | 是 | 文本选择变化回调或光标位置变化回调。 | 931 932### onContentScroll<sup>10+</sup> 933 934onContentScroll(callback: OnContentScrollCallback) 935 936文本内容滚动时，触发该回调。 937 938**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 939 940**系统能力：** SystemCapability.ArkUI.ArkUI.Full 941 942**参数：** 943 944| 参数名 | 类型 | 必填 | 说明 | 945| ------------ | ------ | ---- | ---------------------------------- | 946| callback | [OnContentScrollCallback](ts-basic-components-textinput.md#oncontentscrollcallback18) | 是 | 文本内容滚动回调。 | 947 948### onEditChange<sup>12+</sup> 949 950onEditChange(callback: Callback< boolean >) 951 952输入状态变化时，触发该回调。有光标时为编辑态，无光标时为非编辑态。 953 954**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 955 956**系统能力：** SystemCapability.ArkUI.ArkUI.Full 957 958**参数：** 959 960| 参数名 | 类型 | 必填 | 说明 | 961| --------- | ---------------------------------- | ---- | -------------------- | 962| callback | Callback< boolean > | 是 | 编辑状态改变回调，其返回值为true表示正在输入。 | 963 964### onWillInsert<sup>12+</sup> 965 966onWillInsert(callback: Callback\<InsertValue, boolean>) 967 968在将要输入时，触发该回调。 969 970**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 971 972**系统能力：** SystemCapability.ArkUI.ArkUI.Full 973 974**参数：** 975 976| 参数名 | 类型 | 必填 | 说明 | 977| ------ | ------------------------------------------------------------ | ---- | ------------------ | 978| callback | Callback\<[InsertValue](ts-text-common.md#insertvalue12对象说明), boolean> | 是 | 在将要输入时调用的回调。<br/>在返回true时，表示正常插入，返回false时，表示不插入。<br/>在预上屏和候选词操作时，该回调不触发。<br/>仅支持系统输入法输入的场景。 | 979 980### onDidInsert<sup>12+</sup> 981 982onDidInsert(callback: Callback\<InsertValue>) 983 984在输入完成时，触发该回调。 985 986**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 987 988**系统能力：** SystemCapability.ArkUI.ArkUI.Full 989 990**参数：** 991 992| 参数名 | 类型 | 必填 | 说明 | 993| ------ | ------------------------------------------------------------ | ---- | ------------------ | 994| callback | Callback\<[InsertValue](ts-text-common.md#insertvalue12对象说明)> | 是 | 在输入完成时调用的回调。<br/>仅支持系统输入法输入的场景。 | 995 996### onWillDelete<sup>12+</sup> 997 998onWillDelete(callback: Callback\<DeleteValue, boolean>) 999 1000在将要删除时，触发该回调。 1001 1002**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1003 1004**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1005 1006**参数：** 1007 1008| 参数名 | 类型 | 必填 | 说明 | 1009| ------ | ------------------------------------------------------------ | ---- | ------------------ | 1010| callback | Callback\<[DeleteValue](ts-text-common.md#deletevalue12对象说明), boolean> | 是 | 在将要删除时调用的回调。<br/>在返回true时，表示正常删除，返回false时，表示不删除。<br/>在预上屏删除操作时，该回调不触发。<br/>仅支持系统输入法输入的场景。 | 1011 1012### onDidDelete<sup>12+</sup> 1013 1014onDidDelete(callback: Callback\<DeleteValue>) 1015 1016在删除完成时，触发该回调。 1017 1018**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1019 1020**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1021 1022**参数：** 1023 1024| 参数名 | 类型 | 必填 | 说明 | 1025| ------ | ------------------------------------------------------------ | ---- | ------------------ | 1026| callback | Callback\<[DeleteValue](ts-text-common.md#deletevalue12对象说明)> | 是 | 在删除完成时调用的回调。<br/>仅支持系统输入法输入的场景。 | 1027 1028> **说明：** 1029> 1030> 点击清除按钮不触发onDidDelete回调。 1031 1032### onWillChange<sup>15+</sup> 1033 1034onWillChange(callback: Callback\<EditableTextChangeValue, boolean>) 1035 1036在文本内容将要发生变化时，触发该回调。 1037 1038onWillChange的回调时序晚于onWillInsert、onWillDelete，早于onDidInsert、onDidDelete。 1039 1040**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 1041 1042**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1043 1044**参数：** 1045 1046| 参数名 | 类型 | 必填 | 说明 | 1047| ------ | ------------------------------------------------------------ | ---- | ------------------ | 1048| callback | Callback\<[EditableTextChangeValue](ts-text-common.md#editabletextchangevalue15), boolean> | 是 | 在文本内容将要发生变化时的回调。<br/>返回true时，表示正常修改。返回false时，表示拦截此次触发。 | 1049 1050### onWillAttachIME<sup>20+</sup> 1051 1052onWillAttachIME(callback: Callback\<IMEClient>) 1053 1054在搜索框将要绑定输入法前触发该回调。 1055 1056<!--Del--> 1057在搜索框将要绑定输入法前，可以通过`UIContext`的系统接口[setKeyboardAppearanceConfig](../js-apis-arkui-UIContext-sys.md#setkeyboardappearanceconfig20)设置键盘的样式。<!--DelEnd--> 1058 1059**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1060 1061**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1062 1063**参数：** 1064 1065| 参数名 | 类型 | 必填 | 说明 | 1066| ------ | ------------------------------------------------------------ | ---- | ------------------ | 1067| callback | Callback\<[IMEClient](ts-text-common.md#imeclient20对象说明)> | 是 | 在搜索框将要绑定输入法前触发该回调。 | 1068 1069## SearchController 1070 1071Search组件的控制器继承自[TextContentControllerBase](ts-universal-attributes-text-style.md#textcontentcontrollerbase)，涉及的接口有[getTextContentRect](ts-universal-attributes-text-style.md#gettextcontentrect)、[getTextContentLineCount](ts-universal-attributes-text-style.md#gettextcontentlinecount)、[getCaretOffset](ts-universal-attributes-text-style.md#getcaretoffset11)、[addText](ts-universal-attributes-text-style.md#addtext15)、[deleteText](ts-universal-attributes-text-style.md#deletetext15)、[getSelection](ts-universal-attributes-text-style.md#getselection15)、[clearPreviewText](ts-universal-attributes-text-style.md#clearpreviewtext17)<!--Del-->以及系统接口[getText](ts-text-common-sys.md#gettext19)<!--DelEnd-->。 1072 1073### 导入对象 1074```ts 1075controller: SearchController = new SearchController(); 1076``` 1077 1078### constructor 1079 1080constructor() 1081 1082SearchController的构造函数。 1083 1084**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1085 1086**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1087 1088### caretPosition 1089 1090caretPosition(value: number): void 1091 1092设置输入光标的位置。 1093 1094**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1095 1096**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1097 1098**参数:** 1099 1100| 参数名 | 类型 | 必填 | 说明 | 1101| ------ | -------- | ---- | ---------------------------------- | 1102| value | number | 是 | 从字符串开始到光标所在位置的长度。 | 1103 1104### stopEditing<sup>10+</sup> 1105 1106stopEditing(): void 1107 1108退出编辑态。 1109 1110**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1111 1112**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1113 1114### setTextSelection<sup>12+</sup> 1115 1116setTextSelection(selectionStart: number, selectionEnd: number, options?: SelectionOptions): void; 1117 1118组件在获焦状态下，调用该接口设置文本选择区域并高亮显示，且只有在selectionStart小于selectionEnd时，文字才会被选取并高亮显示。 1119 1120**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1121 1122**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1123 1124**参数：** 1125 1126| 参数名 | 类型 | 必填 | 说明 | 1127| -------------- | -------- | ---- | -------- | 1128| selectionStart | number | 是 | 文本选择区域起始位置，文本框中文字的起始位置为0。<br/>当selectionStart小于0时、按照0处理；当selectionStart大于文字最大长度时、按照文字最大长度处理。<br/> | 1129| selectionEnd | number | 是 | 文本选择区域结束位置。<br/>当selectionEnd小于0时、按照0处理；当selectionEnd大于文字最大长度时、按照文字最大长度处理。<br/> | 1130| options | [SelectionOptions](ts-universal-attributes-text-style.md#selectionoptions12对象说明) | 否 | 选中文字时的配置。<br />默认值：MenuPolicy.DEFAULT。 | 1131 1132> **说明：** 1133> 1134> 如果selectionStart或selectionEnd被赋值为undefined时，当作0处理。 1135> 1136> 如果selectionMenuHidden被赋值为true或设备为2in1时，即使options被赋值为MenuPolicy.SHOW，调用setTextSelection也不弹出菜单。 1137> 1138> 如果选中的文本含有emoji表情时，表情的起始位置包含在设置的文本选中区域内就会被选中。 1139 1140## SearchSubmitCallback<sup>14+</sup> 1141 1142type SearchSubmitCallback = (searchContent: string, event?: SubmitEvent) => void 1143 1144点击搜索图标、搜索按钮或者按下软键盘搜索按钮时的回调事件。 1145 1146**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 1147 1148**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1149 1150**参数：** 1151 1152| 参数名 | 类型 | 必填 | 说明 | 1153| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- | 1154| searchContent | string | 是 | 当前搜索框中输入的文本内容。 | 1155| event | [SubmitEvent](ts-basic-components-textinput.md#submitevent11) | 否 | 提交事件。 | 1156 1157## 示例 1158 1159### 示例1（设置与获取光标位置） 1160 1161从API version 8开始，该示例通过[controller](#searchcontroller)实现了光标位置的设置与获取的功能。 1162 1163```ts 1164// xxx.ets 1165@Entry 1166@Component 1167struct SearchExample { 1168 @State changeValue: string = ''; 1169 @State submitValue: string = ''; 1170 @State positionInfo: CaretOffset = { index: 0, x: 0, y: 0 }; 1171 controller: SearchController = new SearchController(); 1172 1173 build() { 1174 Column({space: 10}) { 1175 Text('onSubmit:' + this.submitValue).fontSize(18).margin(15) 1176 Text('onChange:' + this.changeValue).fontSize(18).margin(15) 1177 Search({ value: this.changeValue, placeholder: 'Type to search...', controller: this.controller }) 1178 .searchButton('SEARCH') 1179 .width('95%') 1180 .height(40) 1181 .backgroundColor('#F5F5F5') 1182 .placeholderColor(Color.Grey) 1183 .placeholderFont({ size: 14, weight: 400 }) 1184 .textFont({ size: 14, weight: 400 }) 1185 .onSubmit((value: string) => { 1186 this.submitValue = value; 1187 }) 1188 .onChange((value: string) => { 1189 this.changeValue = value; 1190 }) 1191 .margin(20) 1192 Button('Set caretPosition 1') 1193 .onClick(() => { 1194 // 设置光标位置到输入的第一个字符后 1195 this.controller.caretPosition(1); 1196 }) 1197 Button('Get CaretOffset') 1198 .onClick(() => { 1199 this.positionInfo = this.controller.getCaretOffset(); 1200 }) 1201 }.width('100%') 1202 } 1203} 1204``` 1205 1206 1207 1208### 示例2（设置搜索和删除图标） 1209 1210该示例通过[searchButton](#searchbutton)（从API version 8开始）、[searchIcon](#searchicon10)（从API version 10开始）、[cancelButton](#cancelbutton10)（从API version 10开始）属性展示了设置搜索和删除图标的效果。 1211 1212```ts 1213// xxx.ets 1214@Entry 1215@Component 1216struct SearchExample { 1217 @State changeValue: string = ''; 1218 @State submitValue: string = ''; 1219 1220 build() { 1221 Column() { 1222 Text('onSubmit:' + this.submitValue).fontSize(18).margin(15) 1223 Search({ value: this.changeValue, placeholder: 'Type to search...' }) 1224 .searchButton('SEARCH') 1225 .searchIcon({ 1226 src: $r('sys.media.ohos_ic_public_search_filled') 1227 }) 1228 .cancelButton({ 1229 style: CancelButtonStyle.CONSTANT, 1230 icon: { 1231 src: $r('sys.media.ohos_ic_public_cancel_filled') 1232 } 1233 }) 1234 .width('90%') 1235 .height(40) 1236 .maxLength(20) 1237 .backgroundColor('#F5F5F5') 1238 .placeholderColor(Color.Grey) 1239 .placeholderFont({ size: 14, weight: 400 }) 1240 .textFont({ size: 14, weight: 400 }) 1241 .onSubmit((value: string) => { 1242 this.submitValue = value; 1243 }) 1244 .onChange((value: string) => { 1245 this.changeValue = value; 1246 }) 1247 .margin(20) 1248 }.width('100%') 1249 } 1250} 1251``` 1252 1253 1254 1255 1256### 示例3（设置自定义键盘） 1257 1258该示例通过[customKeyboard](#customkeyboard10)（从API version 10开始）属性实现了自定义键盘的功能。 1259 1260```ts 1261// xxx.ets 1262@Entry 1263@Component 1264struct SearchExample { 1265 controller: SearchController = new SearchController(); 1266 @State inputValue: string = ""; 1267 1268 // 自定义键盘组件 1269 @Builder CustomKeyboardBuilder() { 1270 Column() { 1271 Button('x').onClick(() => { 1272 // 关闭自定义键盘 1273 this.controller.stopEditing(); 1274 }) 1275 Grid() { 1276 ForEach([1, 2, 3, 4, 5, 6, 7, 8, 9, '*', 0, '#'], (item: number | string) => { 1277 GridItem() { 1278 Button(item + "") 1279 .width(110).onClick(() => { 1280 this.inputValue += item; 1281 }) 1282 } 1283 }) 1284 }.maxCount(3).columnsGap(10).rowsGap(10).padding(5) 1285 }.backgroundColor(Color.Gray) 1286 } 1287 1288 build() { 1289 Column() { 1290 Search({ controller: this.controller, value: this.inputValue}) 1291 // 绑定自定义键盘 1292 .customKeyboard(this.CustomKeyboardBuilder()).margin(10).border({ width: 1 }) 1293 } 1294 } 1295} 1296``` 1297 1298 1299 1300### 示例4（设置输入法回车键类型） 1301 1302该示例通过[enterKeyType](#enterkeytype12)（从API version 12开始）属性实现了动态切换输入法回车键的效果。 1303 1304```ts 1305// xxx.ets 1306@Entry 1307@Component 1308struct SearchExample { 1309 @State text: string = ''; 1310 @State enterTypes: Array<EnterKeyType> = [EnterKeyType.Go, EnterKeyType.Search, EnterKeyType.Send, EnterKeyType.Done, EnterKeyType.Next, EnterKeyType.PREVIOUS, EnterKeyType.NEW_LINE]; 1311 @State index: number = 0; 1312 build() { 1313 Column({ space: 20 }) { 1314 Search({ placeholder: '请输入文本', value: this.text }) 1315 .width(380) 1316 .enterKeyType(this.enterTypes[this.index]) 1317 .onChange((value: string) => { 1318 this.text = value; 1319 }) 1320 .onSubmit((value: string) => { 1321 console.info("trigger search onsubmit" + value); 1322 }) 1323 1324 Button('改变EnterKeyType').onClick(() => { 1325 this.index = (this.index + 1) % this.enterTypes.length; 1326 }) 1327 }.width('100%') 1328 } 1329} 1330``` 1331 1332 1333 1334### 示例5（设置文本样式） 1335 1336从API version 12开始，该示例通过[lineHeight](#lineheight12)、[letterSpacing](#letterspacing12)、[decoration](#decoration12)属性展示了不同样式的文本效果。 1337 1338```ts 1339// xxx.ets 1340@Entry 1341@Component 1342struct SearchExample { 1343 build() { 1344 Row() { 1345 Column() { 1346 Text('lineHeight').fontSize(9).fontColor(0xCCCCCC) 1347 Search({value: 'lineHeight unset'}) 1348 .border({ width: 1 }).padding(10) 1349 Search({value: 'lineHeight 15'}) 1350 .border({ width: 1 }).padding(10).lineHeight(15) 1351 Search({value: 'lineHeight 30'}) 1352 .border({ width: 1 }).padding(10).lineHeight(30) 1353 1354 Text('letterSpacing').fontSize(9).fontColor(0xCCCCCC) 1355 Search({value: 'letterSpacing 0'}) 1356 .border({ width: 1 }).padding(5).letterSpacing(0) 1357 Search({value: 'letterSpacing 3'}) 1358 .border({ width: 1 }).padding(5).letterSpacing(3) 1359 Search({value: 'letterSpacing -1'}) 1360 .border({ width: 1 }).padding(5).letterSpacing(-1) 1361 1362 Text('decoration').fontSize(9).fontColor(0xCCCCCC) 1363 Search({value: 'LineThrough, Red'}) 1364 .border({ width: 1 }).padding(5) 1365 .decoration({type: TextDecorationType.LineThrough, color: Color.Red}) 1366 Search({value: 'Overline, Red, DOTTED'}) 1367 .border({ width: 1 }).padding(5) 1368 .decoration({type: TextDecorationType.Overline, color: Color.Red, style: TextDecorationStyle.DOTTED}) 1369 Search({value: 'Underline, Red, WAVY'}) 1370 .border({ width: 1 }).padding(5) 1371 .decoration({type: TextDecorationType.Underline, color: Color.Red, style: TextDecorationStyle.WAVY}) 1372 }.height('90%') 1373 } 1374 .width('90%') 1375 .margin(10) 1376 } 1377} 1378 1379``` 1380 1381 1382 1383### 示例6（设置文字特性效果） 1384 1385该示例通过[fontFeature](#fontfeature12)（从API version 12开始）属性实现了文本在不同文字特性下的展示效果。 1386 1387```ts 1388// xxx.ets 1389@Entry 1390@Component 1391struct SearchExample { 1392 @State text1: string = 'This is ss01 on : 0123456789'; 1393 @State text2: string = 'This is ss01 off: 0123456789'; 1394 1395 build() { 1396 Column(){ 1397 Search({value: this.text1}) 1398 .margin({top:200}) 1399 .fontFeature("\"ss01\" on") 1400 Search({value: this.text2}) 1401 .margin({top:10}) 1402 .fontFeature("\"ss01\" off") 1403 } 1404 .width("90%") 1405 .margin("5%") 1406 } 1407} 1408``` 1409 1410 1411### 示例7（自定义键盘避让） 1412 1413该示例通过[customKeyboard](#customkeyboard10)（从API version 10开始）属性配置[KeyboardOptions](ts-basic-components-richeditor.md#keyboardoptions12)（从API version 12开始）接口实现了自定义键盘避让的效果。 1414 1415```ts 1416// xxx.ets 1417@Entry 1418@Component 1419struct SearchExample { 1420 controller: SearchController = new SearchController(); 1421 @State inputValue: string = ""; 1422 @State height1: string | number = '80%'; 1423 @State supportAvoidance: boolean = true; 1424 1425 // 自定义键盘组件 1426 @Builder 1427 CustomKeyboardBuilder() { 1428 Column() { 1429 Row() { 1430 Button('x').onClick(() => { 1431 // 关闭自定义键盘 1432 this.controller.stopEditing(); 1433 }).margin(10) 1434 } 1435 1436 Grid() { 1437 ForEach([1, 2, 3, 4, 5, 6, 7, 8, 9, '*', 0, '#'], (item: number | string) => { 1438 GridItem() { 1439 Button(item + "") 1440 .width(110).onClick(() => { 1441 this.inputValue += item; 1442 }) 1443 } 1444 }) 1445 }.maxCount(3).columnsGap(10).rowsGap(10).padding(5) 1446 } 1447 .backgroundColor(Color.Gray) 1448 } 1449 1450 build() { 1451 Column() { 1452 Row() { 1453 Button("20%") 1454 .fontSize(24) 1455 .onClick(() => { 1456 this.height1 = "20%"; 1457 }) 1458 Button("80%") 1459 .fontSize(24) 1460 .margin({ left: 20 }) 1461 .onClick(() => { 1462 this.height1 = "80%"; 1463 }) 1464 } 1465 .justifyContent(FlexAlign.Center) 1466 .alignItems(VerticalAlign.Bottom) 1467 .height(this.height1) 1468 .width("100%") 1469 .padding({ bottom: 50 }) 1470 1471 Search({ controller: this.controller, value: this.inputValue })// 绑定自定义键盘 1472 .customKeyboard(this.CustomKeyboardBuilder(), { supportAvoidance: this.supportAvoidance }) 1473 .margin(10) 1474 .border({ width: 1 }) 1475 .onChange((value: string) => { 1476 this.inputValue = value; 1477 }) 1478 } 1479 } 1480} 1481``` 1482 1483 1484 1485### 示例8（设置文本自适应） 1486 1487从API version 12开始，该示例通过[minFontSize](#minfontsize12)、[maxFontSize](#maxfontsize12)属性展示了文本自适应字号的效果。 1488 1489```ts 1490// xxx.ets 1491@Entry 1492@Component 1493struct SearchExample { 1494 build() { 1495 Row() { 1496 Column() { 1497 Text('adaptive font').fontSize(9).fontColor(0xCCCCCC) 1498 1499 Search({value: 'This is the text without the adaptive font'}) 1500 .width('80%').height(90).borderWidth(1) 1501 Search({value: 'This is the text without the adaptive font'}) 1502 .width('80%').height(90).borderWidth(1) 1503 .minFontSize(4) 1504 .maxFontSize(40) 1505 }.height('90%') 1506 } 1507 .width('90%') 1508 .margin(10) 1509 } 1510} 1511``` 1512 1513 1514 1515### 示例9（支持插入和删除回调） 1516 1517从API version 12开始，该示例通过[onWillInsert](#onwillinsert12)、[onDidInsert](#ondidinsert12)、[onWillDelete](#onwilldelete12)、[onDidDelete](#ondiddelete12)接口实现了插入和删除的效果。 1518 1519```ts 1520// xxx.ets 1521@Entry 1522@Component 1523struct SearchExample { 1524 @State insertValue: string = ""; 1525 @State deleteValue: string = ""; 1526 @State insertOffset: number = 0; 1527 @State deleteOffset: number = 0; 1528 @State deleteDirection: number = 0; 1529 1530 build() { 1531 Row() { 1532 Column() { 1533 Search({ value: "Search支持插入回调文本" }) 1534 .height(60) 1535 .onWillInsert((info: InsertValue) => { 1536 this.insertValue = info.insertValue; 1537 return true; 1538 }) 1539 .onDidInsert((info: InsertValue) => { 1540 this.insertOffset = info.insertOffset; 1541 }) 1542 1543 Text("insertValue:" + this.insertValue + " insertOffset:" + this.insertOffset).height(30) 1544 1545 Search({ value: "Search支持删除回调文本b" }) 1546 .height(60) 1547 .onWillDelete((info: DeleteValue) => { 1548 this.deleteValue = info.deleteValue; 1549 this.deleteDirection = info.direction; 1550 return true; 1551 }) 1552 .onDidDelete((info: DeleteValue) => { 1553 this.deleteOffset = info.deleteOffset; 1554 this.deleteDirection = info.direction; 1555 }) 1556 1557 Text("deleteValue:" + this.deleteValue + " deleteOffset:" + this.deleteOffset).height(30) 1558 Text("deleteDirection:" + (this.deleteDirection == 0 ? "BACKWARD" : "FORWARD")).height(30) 1559 1560 }.width('100%') 1561 } 1562 .height('100%') 1563 } 1564} 1565``` 1566 1567 1568 1569### 示例10（文本扩展自定义菜单） 1570 1571从API version 12开始，该示例通过[editMenuOptions](#editmenuoptions12)接口实现了文本设置自定义菜单扩展项的文本内容、图标以及回调的功能，同时，可以在[onPrepareMenu](ts-text-common.md#onpreparemenu20)（从API version 20开始）回调中，进行菜单数据的设置。 1572 1573```ts 1574// xxx.ets 1575@Entry 1576@Component 1577struct SearchExample { 1578 @State text: string = 'Search editMenuOptions'; 1579 @State endIndex: number = 0; 1580 onCreateMenu = (menuItems: Array<TextMenuItem>) => { 1581 // $r('app.media.startIcon')需要替换为开发者所需的图像资源文件。 1582 let item1: TextMenuItem = { 1583 content: 'create1', 1584 icon: $r('app.media.startIcon'), 1585 id: TextMenuItemId.of('create1'), 1586 }; 1587 let item2: TextMenuItem = { 1588 content: 'create2', 1589 id: TextMenuItemId.of('create2'), 1590 icon: $r('app.media.startIcon'), 1591 }; 1592 menuItems.push(item1); 1593 menuItems.unshift(item2); 1594 return menuItems; 1595 } 1596 onMenuItemClick = (menuItem: TextMenuItem, textRange: TextRange) => { 1597 if (menuItem.id.equals(TextMenuItemId.of("create2"))) { 1598 console.info("拦截 id: create2 start:" + textRange.start + "; end:" + textRange.end); 1599 return true; 1600 } 1601 if (menuItem.id.equals(TextMenuItemId.of("prepare1"))) { 1602 console.info("拦截 id: prepare1 start:" + textRange.start + "; end:" + textRange.end); 1603 return true; 1604 } 1605 if (menuItem.id.equals(TextMenuItemId.COPY)) { 1606 console.info("拦截 COPY start:" + textRange.start + "; end:" + textRange.end); 1607 return true; 1608 } 1609 if (menuItem.id.equals(TextMenuItemId.SELECT_ALL)) { 1610 console.info("不拦截 SELECT_ALL start:" + textRange.start + "; end:" + textRange.end); 1611 return false; 1612 } 1613 return false; 1614 } 1615 // $r('app.media.startIcon')需要替换为开发者所需的图像资源文件。 1616 onPrepareMenu = (menuItems: Array<TextMenuItem>) => { 1617 let item1: TextMenuItem = { 1618 content: 'prepare1_' + this.endIndex, 1619 icon: $r('app.media.startIcon'), 1620 id: TextMenuItemId.of('prepare1'), 1621 }; 1622 menuItems.unshift(item1); 1623 return menuItems; 1624 } 1625 @State editMenuOptions: EditMenuOptions = { 1626 onCreateMenu: this.onCreateMenu, 1627 onMenuItemClick: this.onMenuItemClick, 1628 onPrepareMenu: this.onPrepareMenu 1629 }; 1630 1631 build() { 1632 Column() { 1633 Search({ value: this.text }) 1634 .width('95%') 1635 .editMenuOptions(this.editMenuOptions) 1636 .margin({ top: 100 }) 1637 .onTextSelectionChange((selectionStart: number, selectionEnd: number) => { 1638 this.endIndex = selectionEnd; 1639 }) 1640 } 1641 .width("90%") 1642 .margin("5%") 1643 } 1644} 1645``` 1646 1647 1648 1649### 示例11（设置symbol类型清除按钮） 1650 1651从API version 10开始，该示例通过[searchIcon](#searchicon10)、[cancelButton](#cancelbutton10)属性展示了自定义右侧symbol类型清除按钮样式的效果。 1652 1653```ts 1654// xxx.ets 1655import { SymbolGlyphModifier } from '@kit.ArkUI'; 1656 1657@Entry 1658@Component 1659struct SearchExample { 1660 controller: SearchController = new SearchController(); 1661 @State changeValue: string = ''; 1662 @State submitValue: string = ''; 1663 1664 build() { 1665 Column() { 1666 Search({ value: this.changeValue, placeholder: 'Type to search...', controller: this.controller }) 1667 .searchIcon(new SymbolGlyphModifier($r('sys.symbol.magnifyingglass')).fontColor([Color.Red])) 1668 .cancelButton({ 1669 style: CancelButtonStyle.CONSTANT, 1670 icon: new SymbolGlyphModifier($r('sys.symbol.xmark')).fontColor([Color.Green]) 1671 }) 1672 .searchButton('SEARCH') 1673 .width('95%') 1674 .height(40) 1675 .backgroundColor('#F5F5F5') 1676 .placeholderColor(Color.Grey) 1677 .placeholderFont({ size: 14, weight: 400 }) 1678 .textFont({ size: 14, weight: 400 }) 1679 .margin(10) 1680 } 1681 .width('100%') 1682 .height('100%') 1683 } 1684} 1685``` 1686 1687 1688 1689### 示例12（设置文本是否可复制） 1690 1691从API version 9开始，该示例通过[copyOption](#copyoption9)属性展示如何设置文本是否可复制。 1692 1693```ts 1694// xxx.ets 1695 1696@Entry 1697@Component 1698struct SearchExample { 1699 controller: SearchController = new SearchController(); 1700 @State copyValue: string = ''; 1701 @State cutValue: string = ''; 1702 1703 build() { 1704 Column({ space: 3 }) { 1705 Text("copy: " + this.copyValue) 1706 Text("cut:" + this.cutValue) 1707 Search({ value: 'Search CopyOption:None', controller: this.controller }) 1708 .width('95%') 1709 .height(40) 1710 .copyOption(CopyOptions.None) 1711 .onCopy((value: string) => { 1712 this.copyValue = value; 1713 }) 1714 .onCut((value: string) => { 1715 this.cutValue = value; 1716 }) 1717 Search({ value: 'Search CopyOption:InApp', controller: this.controller }) 1718 .width('95%') 1719 .height(40) 1720 .copyOption(CopyOptions.InApp) 1721 .onCopy((value: string) => { 1722 this.copyValue = value; 1723 }) 1724 .onCut((value: string) => { 1725 this.cutValue = value; 1726 }) 1727 Search({ value: 'Search CopyOption:LocalDevice', controller: this.controller }) 1728 .width('95%') 1729 .height(40) 1730 .copyOption(CopyOptions.LocalDevice) 1731 .onCopy((value: string) => { 1732 this.copyValue = value; 1733 }) 1734 .onCut((value: string) => { 1735 this.cutValue = value; 1736 }) 1737 } 1738 .width('100%') 1739 .height('100%') 1740 } 1741} 1742``` 1743 1744 1745 1746### 示例13（设置文本水平对齐/光标样式/选中背景色） 1747 1748该示例通过[textAlign](#textalign9)（从API version 9开始）、[caretStyle](#caretstyle10)（从API version 10开始）、[selectedBackgroundColor](#selectedbackgroundcolor12)（从API version 12开始）属性展示如何设置文本的水平对齐、光标样式和选中背景色。 1749 1750```ts 1751// xxx.ets 1752 1753@Entry 1754@Component 1755struct SearchExample { 1756 controller: SearchController = new SearchController(); 1757 1758 build() { 1759 Column({ space: 3 }) { 1760 Search({ value: 'Search textAlign sample', controller: this.controller }) 1761 .width('95%') 1762 .height(40) 1763 .stopBackPress(true) 1764 .textAlign(TextAlign.Center) 1765 .caretStyle({ width: 3, color: Color.Green }) 1766 .selectedBackgroundColor(Color.Gray) 1767 } 1768 .width('100%') 1769 .height('100%') 1770 } 1771} 1772``` 1773 1774 1775 1776### 示例14（设置默认获焦并拉起软键盘） 1777 1778该示例通过[defaultFocus](ts-universal-attributes-focus.md#defaultfocus9)（从API version 9开始）、[enableKeyboardOnFocus](#enablekeyboardonfocus10)（从API version 10开始）属性展示如何设置默认获焦并拉起软键盘。 1779 1780```ts 1781// xxx.ets 1782 1783@Entry 1784@Component 1785struct SearchExample { 1786 controller: SearchController = new SearchController(); 1787 @State value: string = 'false'; 1788 1789 build() { 1790 Column({ space: 3 }) { 1791 Text('editing: ' + this.value) 1792 Search({ placeholder: 'please enter...', controller: this.controller }) 1793 .width('95%') 1794 .height(40) 1795 .defaultFocus(true) 1796 .enableKeyboardOnFocus(true) 1797 .enablePreviewText(true) 1798 .enableHapticFeedback(true) 1799 .onEditChange((data: boolean) => { 1800 this.value = data ? 'true' : 'false'; 1801 }) 1802 } 1803 .width('100%') 1804 .height('100%') 1805 } 1806} 1807``` 1808 1809 1810 1811### 示例15（关闭系统文本选择菜单） 1812 1813该示例通过[selectionMenuHidden](#selectionmenuhidden10)（从API version 10开始）属性展示如何关闭系统文本选择菜单。 1814 1815```ts 1816// xxx.ets 1817 1818@Entry 1819@Component 1820struct SearchExample { 1821 controller: SearchController = new SearchController(); 1822 1823 build() { 1824 Column({ space: 3 }) { 1825 Search({ value: '123456', controller: this.controller }) 1826 .width('95%') 1827 .height(40) 1828 .type(SearchType.NUMBER) 1829 .selectionMenuHidden(true) 1830 } 1831 .width('100%') 1832 .height('100%') 1833 } 1834} 1835``` 1836 1837 1838 1839### 示例16（对输入的文本进行过滤） 1840 1841从API version 12开始，该示例通过[inputFilter](#inputfilter12)属性展示如何对输入的文本进行内容的过滤，以限制输入内容。 1842 1843```ts 1844// xxx.ets 1845 1846@Entry 1847@Component 1848struct SearchExample { 1849 controller: SearchController = new SearchController(); 1850 @State filterValue: string = ''; 1851 1852 build() { 1853 Column({ space: 3 }) { 1854 Text('Filter:' + this.filterValue) 1855 Search({ placeholder: 'please enter...', controller: this.controller }) 1856 .width('95%') 1857 .height(40) 1858 .textIndent(5) 1859 .halfLeading(true) 1860 .inputFilter('[a-z]', (filterValue: string) => { 1861 this.filterValue = filterValue; 1862 }) 1863 } 1864 .width('100%') 1865 .height('100%') 1866 } 1867} 1868``` 1869 1870 1871 1872### 示例17（设置选中指定区域的文本内容） 1873 1874该示例通过[setTextSelection](#settextselection12)（从API version 12开始）方法展示如何设置选中指定区域的文本内容以及菜单的显隐策略。 1875 1876```ts 1877// xxx.ets 1878 1879@Entry 1880@Component 1881struct SearchExample { 1882 controller: SearchController = new SearchController(); 1883 @State startIndex: number = 0; 1884 @State endIndex: number = 0; 1885 1886 build() { 1887 Column({ space: 3 }) { 1888 Text('Selection start:' + this.startIndex + ' end:' + this.endIndex) 1889 Search({ value: 'Hello World', controller: this.controller }) 1890 .width('95%') 1891 .height(40) 1892 .minFontScale(1) 1893 .maxFontScale(1.5) 1894 .defaultFocus(true) 1895 .onTextSelectionChange((selectionStart: number, selectionEnd: number) => { 1896 this.startIndex = selectionStart; 1897 this.endIndex = selectionEnd; 1898 }) 1899 1900 Button('Selection [0,3]') 1901 .onClick(() => { 1902 this.controller.setTextSelection(0, 3, { menuPolicy: MenuPolicy.SHOW }); 1903 }) 1904 } 1905 .width('100%') 1906 .height('100%') 1907 } 1908} 1909``` 1910 1911 1912 1913### 示例18（设置文本滚动事件） 1914 1915从API version 10开始，该示例通过[onContentScroll](#oncontentscroll10)事件展示如何设置文本滚动事件的回调。 1916 1917```ts 1918// xxx.ets 1919 1920@Entry 1921@Component 1922struct SearchExample { 1923 controller: SearchController = new SearchController(); 1924 @State offsetX: number = 0; 1925 @State offsetY: number = 0; 1926 1927 build() { 1928 Column({ space: 3 }) { 1929 Text('offset x:' + this.offsetX + ' y:' + this.offsetY) 1930 Search({ value: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', controller: this.controller }) 1931 .width(200) 1932 .height(40) 1933 .onContentScroll((totalOffsetX: number, totalOffsetY: number) => { 1934 this.offsetX = totalOffsetX; 1935 this.offsetY = totalOffsetY; 1936 }) 1937 } 1938 .width('100%') 1939 .height('100%') 1940 } 1941} 1942``` 1943 1944 1945 1946### 示例19（设置最小字体范围与最大字体范围） 1947 1948从API version 18开始，该示例通过[minFontScale](#minfontscale18)、[maxFontScale](#maxfontscale18)设置字体显示最小与最大范围。 1949 1950```json 1951// 开启应用缩放跟随系统 1952// AppScope/resources/base，新建文件夹profile。 1953// AppScope/resources/base/profile，新建文件configuration.json。 1954// AppScope/resources/base/profile/configuration.json，增加如下代码。 1955{ 1956 "configuration": { 1957 "fontSizeScale": "followSystem", 1958 "fontSizeMaxScale": "3.2" 1959 } 1960} 1961``` 1962 1963```json 1964// AppScope/app.json5，修改如下代码。 1965{ 1966 "app": { 1967 "bundleName": "com.example.myapplication", 1968 "vendor": "example", 1969 "versionCode": 1000000, 1970 "versionName": "1.0.0", 1971 "icon": "$media:app_icon", 1972 "label": "$string:app_name", 1973 "configuration": "$profile:configuration" 1974 } 1975} 1976``` 1977 1978```ts 1979// xxx.ets 1980@Entry 1981@Component 1982struct SearchExample { 1983 @State minFontScale: number = 0.85; 1984 @State maxFontScale: number = 2; 1985 1986 build() { 1987 Column() { 1988 Column({ space: 30 }) { 1989 Text("系统字体变大变小，变大变小aaaaaaaAAAAAA") 1990 Search({ 1991 placeholder: 'The text area can hold an unlimited amount of text. input your word...', 1992 }) 1993 .minFontScale(this.minFontScale)// 设置最小字体缩放倍数，参数为undefined则跟随系统默认倍数缩放 1994 .maxFontScale(this.maxFontScale)// 设置最大字体缩放倍数，参数为undefined则跟随系统默认倍数缩放 1995 }.width('100%') 1996 } 1997 } 1998} 1999``` 2000 2001### 示例20（设置文本描边） 2002 2003从API version 20开始，该示例通过[strokeWidth](#strokewidth20)和[strokeColor](#strokecolor20)属性设置文本的描边宽度及颜色。 2004 2005```ts 2006// xxx.ets 2007import { LengthMetrics } from '@kit.ArkUI'; 2008 2009@Entry 2010@Component 2011struct SearchExample { 2012 build() { 2013 Row() { 2014 Column() { 2015 Text('stroke feature').fontSize(9).fontColor(0xCCCCCC) 2016 2017 Search({ value: 'Text without stroke' }) 2018 .width('100%') 2019 .height(60) 2020 .borderWidth(1) 2021 .minFontSize(40) 2022 .maxFontSize(40) 2023 Search({ value: 'Text with stroke' }) 2024 .width('100%') 2025 .height(60) 2026 .borderWidth(1) 2027 .minFontSize(40) 2028 .maxFontSize(40) 2029 .strokeWidth(LengthMetrics.px(-3.0)) 2030 .strokeColor(Color.Red) 2031 Search({ value: 'Text with stroke' }) 2032 .width('100%') 2033 .height(60) 2034 .borderWidth(1) 2035 .minFontSize(40) 2036 .maxFontSize(40) 2037 .strokeWidth(LengthMetrics.px(3.0)) 2038 .strokeColor(Color.Red) 2039 }.height('90%') 2040 } 2041 .width('90%') 2042 .margin(10) 2043 } 2044} 2045``` 2046 2047 2048 2049### 示例21（设置中西文自动间距） 2050 2051从API version 20开始，该示例通过[enableAutoSpacing](#enableautospacing20)属性设置中西文自动间距。 2052 2053```ts 2054// xxx.ets 2055@Entry 2056@Component 2057struct SearchExample { 2058 build() { 2059 Row() { 2060 Column() { 2061 Text('开启中西文自动间距').margin(5) 2062 Search({value: '中西文Auto Spacing自动间距'}) 2063 .enableAutoSpacing(true) 2064 Text('关闭中西文自动间距').margin(5) 2065 Search({value: '中西文Auto Spacing自动间距'}) 2066 .enableAutoSpacing(false) 2067 }.height('100%') 2068 } 2069 .width('60%') 2070 } 2071} 2072``` 2073 2074
