# HarmonyOS next之Search 的简易使用
### 1. 基本使用
- **引入和创建**：在 ets 文件中，首先通过`import { Search } from '@ohos.arkui.advanced.Search'`引入 Search 组件。然后可以在组件的`build`方法中创建 Search 实例，例如：
```typescript
Search({ value: this.searchText, placeholder: 'Search...' })
.width('90%')
.height(40)
.onSubmit((value: string) => {
// 处理搜索提交逻辑
})
.onChange((value: string) => {
// 处理输入内容变化逻辑
});
```
这里设置了初始显示的搜索文本`value`、提示文本`placeholder`，并指定了组件的宽度、高度，同时监听了`onSubmit`（提交搜索时）和`onChange`（输入内容变化时）事件。
### 2. 属性配置
- **搜索按钮样式**：使用`searchButton`属性可以设置搜索框末尾搜索按钮的文本内容和样式，如：
```typescript
Search({...})
.searchButton('SEARCH', { fontSize: '16fp', fontColor: '#ff3f97e9' });
```
- **提示文本样式**：`placeholderColor`用于设置提示文本颜色，`placeholderFont`用于设置提示文本的字体样式，例如：
```typescript
Search({...})
.placeholderColor(Color.Grey)
.placeholderFont({ size: 14, weight: 400 });
```
- **输入文本样式**：`textFont`可以设置搜索框内输入文本的样式，如字体大小、粗细等。
- **对齐方式**：`textAlign`属性（从 API version 9 开始支持）可设置文本在搜索框中的对齐方式，如`TextAlign.Start`（默认）、`TextAlign.Center`或`TextAlign.End`。
- **图标样式**：`searchIcon`（从 API version 10 开始支持）可设置左侧搜索图标的样式，包括尺寸、颜色和图片源；`cancelButton`可设置右侧清除按钮的样式。
- **文本可复制性**：`copyOption`（从 API version 9 开始支持）用于设置输入文本是否可复制，默认`CopyOptions.LocalDevice`支持设备内复制。
- **其他属性**：还可以设置如`fontColor`（输入文本字体颜色）、`caretStyle`（光标样式）、`enableKeyboardOnFocus`（获焦时是否主动拉起软键盘）等属性来定制搜索框的行为和外观。
### 3. 事件监听
- **提交搜索**：`onSubmit`事件在点击搜索图标、搜索按钮或按下软键盘搜索按钮时触发，回调函数中可获取当前搜索框中的输入文本内容并进行相应处理。
- **内容变化**：`onChange`事件在输入内容发生变化时触发，开发者可在回调中根据输入内容进行实时处理或验证。
- **复制、剪切、粘贴等事件**：`onCopy`、`onCut`、`onPaste`等事件分别在进行复制、剪切、粘贴操作时触发，可用于记录操作信息或进行相关逻辑处理。同时，还有`onTextSelectionChange`（文本选择位置变化）、`onContentScroll`（文本内容滚动）等事件提供更多交互反馈。
### 4. 控制器使用
- **创建控制器**：通过`controller: SearchController = new SearchController()`创建 Search 组件的控制器实例。
- **控制光标位置**：使用`caretPosition`方法可以设置输入光标的位置，例如`this.controller.caretPosition(1)`将光标位置设置到输入的第一个字符后。
- **退出编辑态**：`stopEditing`方法用于退出编辑态，可用于自定义键盘等场景，如在自定义键盘中点击关闭按钮时调用`this.controller.stopEditing()`。
### 5. 自定义键盘
- **创建自定义键盘组件**：首先创建一个自定义的组件作为键盘，例如：
```typescript
@Builder CustomKeyboardBuilder() {
Column() {
// 自定义键盘布局和按钮点击逻辑
}
}
```
- **绑定自定义键盘**：在 Search 组件中使用`customKeyboard`属性绑定自定义键盘组件，如：
```typescript
Search({ controller: this.controller, value: this.inputValue})
.customKeyboard(this.CustomKeyboardBuilder());
```
当设置自定义键盘后，输入框激活时将加载指定的自定义组件作为键盘，开发者可以根据需求设计个性化的键盘布局和功能。
### 6. 输入框类型和限制
- **输入框类型**：`type`属性（从 API version 11 开始支持）可设置输入框类型，如`SearchType.Normal`（基本输入模式）、`SearchType.NUMBER`（纯数字输入模式）、`SearchType.PHONE_NUMBER`（电话号码输入模式）、`SearchType.EMAIL`（邮箱地址输入模式）等，用于限制用户输入的内容格式。
- **最大长度限制**：`maxLength`属性（从 API version 11 开始支持）可设置文本的最大输入字符数，到达限制后将无法继续输入字符。
### 7. 其他功能
- **文本装饰和缩进**：从 API version 12 开始，可以使用`decoration`设置文本装饰线类型样式及其颜色，`textIndent`设置首行文本缩进，`letterSpacing`设置文本字符间距，`lineHeight`设置文本行高，`selectedBackgroundColor`设置文本选中底板颜色等，进一步美化和定制搜索框内文本的显示效果。
- **输入预上屏**：`enablePreviewText`属性（从 API version 12 开始支持）可设置是否开启输入预上屏功能，默认开启。在 CAPI 场景使用时默认关闭，可通过工程的`module.json5`中配置`metadata`字段来控制是否启用预上屏。
- **输入过滤器**：`inputFilter`属性（从 API version 12 开始支持）可通过正则表达式设置输入过滤器，仅允许匹配表达式的输入显示，不匹配的输入将被过滤。但需注意设置输入过滤器可能会导致设置输入框类型附带的文本过滤效果失效。
通过以上功能的组合使用，可以创建出功能丰富、用户体验良好的搜索框组件，满足各种应用场景中的搜索需求。在实际开发中，根据具体需求灵活配置 Search 组件的属性、监听事件并结合控制器和自定义键盘等功能，能够打造出符合应用风格和用户操作习惯的搜索界面。同时，注意不同 API 版本对功能的支持情况，合理利用新特性来优化搜索功能的实现。
