SearchField QML Type

검색 기능에 사용하도록 설계된 특수 입력 필드입니다. 더 보기...

• 상속된 멤버를 포함한 모든 멤버 목록

속성

• clearIndicator
  • clearIndicator.hovered : bool
  • clearIndicator.implicitIndicatorHeight : real
  • clearIndicator.implicitIndicatorWidth : real
  • clearIndicator.indicator : Item
  • clearIndicator.pressed : bool
• currentIndex : int
• delegate : Component
• delegateModel : model
• highlightedIndex : int
• live : bool
• popup : Popup
• searchIndicator
  • searchIndicator.hovered : bool
  • searchIndicator.implicitIndicatorHeight : real
  • searchIndicator.implicitIndicatorWidth : real
  • searchIndicator.indicator : Item
  • searchIndicator.pressed : bool
• suggestionCount : int
• suggestionModel : model
• text : string
• textRole : string

신호

• void accepted()
• void activated(int index)
• void clearButtonPressed()
• void highlighted(int index)
• void searchButtonPressed()
• void searchTriggered()
• void textEdited()

상세 설명

SearchField는 검색 기능에 사용하도록 설계된 특수 입력 필드입니다. 이 컨트롤에는 텍스트 필드, 검색 및 지우기 아이콘, 제안 또는 검색 결과를 표시하는 팝업이 포함되어 있습니다.

SearchField의 표시기

SearchField는 searchIndicator 및 clearIndicator 이라는 두 가지 임베디드 표시기 버튼을 제공합니다.

이는 BusyIndicator 또는 ProgressBar 과 같은 의미의 표시기가 아니라 필드에 임베드된 대화형 컨트롤입니다( SpinBox 의 위/아래 버튼과 유사). searchIndicator 을 누르면 searchButtonPressed()이 트리거되고 clearIndicator 을 누르면 clearButtonPressed()이 트리거됩니다.

표시기 버튼은 동작을 노출하는 것 외에도 스타일에서 사용할 수 있는 상호 작용 상태(눌림/회전/집중 등)를 제공합니다.

표시기 콘텐츠 사용자 지정하기

searchIndicator 및 clearIndicator 속성은 읽기 전용입니다. 내부 속성을 통해 사용자 정의가 지원됩니다.

특히 버튼의 시각적 콘텐츠는 쓰기 가능한 indicator 항목에서 제공됩니다. 이를 통해 기본 콘텐츠를 완전히 바꾸거나 제거할 수 있습니다.

예를 들어 두 표시기 아이콘을 모두 제거할 수 있습니다:

SearchField {
    searchIndicator.indicator: null
    clearIndicator.indicator: null
}

이는 지원되는 사용자 지정 시나리오입니다. 검색 필드 변형에 따라 버튼 중 하나를 생략하거나(예: 검색 버튼만 제공) 표시기 콘텐츠를 다른 항목(예: 음성 입력을 트리거하는 마이크 아이콘)으로 대체할 수 있습니다.

검색 필드 모델 역할

SearchField는 modelData 역할을 제공하는 표준 데이터 모델을 시각화할 수 있습니다:

• 역할이 하나만 있는 모델
• 명명된 역할이 없는 모델(JavaScript 배열, 정수)

명명된 역할이 여러 개 있는 모델을 사용하는 경우 text 및 delegate 인스턴스에 특정 text role 을 사용하도록 SearchField를 구성해야 합니다.

ListModel {
    id : fruitModel
    ListElement { name: "Apple"; color: "green" }
    ListElement { name: "Cherry"; color: "red" }
    ListElement { name: "Banana"; color: "yellow" }
    ListElement { name: "Orange"; color: "orange" }
    ListElement { name: "WaterMelon"; color: "pink" }
}

SortFilterProxyModel {
    id: fruitFilter
    model: fruitModel
    sorters: [
        RoleSorter {
            roleName: "name"
        }
    ]
    filters: [
        FunctionFilter {
            component CustomData: QtObject { property string name }
            property var regExp: new RegExp(fruitSearch.text, "i")
            onRegExpChanged: invalidate()
            function filter(data: CustomData): bool {
                return regExp.test(data.name);
            }
        }
    ]
}

SearchField {
    id: fruitSearch
    suggestionModel: fruitFilter
    textRole: "name"
    anchors.horizontalCenter: parent.horizontalCenter
}

searchIndicator, clearIndicator, searchButtonPressed() 및 clearButtonPressed()도 참조하세요 .

속성 문서

clearIndicator group

이 그룹화된 속성은 clearIndicator 표시기 항목과 관련 속성을 보유합니다.

이 속성은 지우기 표시기를 보유합니다. 이 속성을 누르면 clearButtonPressed()가 트리거됩니다.

스타일과 애플리케이션이 내부 속성을 통해 사용자 정의할 수 있도록 노출되어 있습니다(예: clearIndicator.indicator 을 통해 clearIndicator 을 대체 또는 제거하거나 누름 및 마우스오버와 같은 상호 작용 상태에 반응하는 등).

SearchField's Indicators 를참조하세요 .

currentIndex : int

이 속성은 팝업 목록에서 현재 선택된 제안의 색인을 저장합니다.

선택된 제안이 없는 경우 이 값은 -1 입니다.

currentIndex는 모델이 변경되거나 사용자가 텍스트를 입력하거나 편집할 때 자동으로 수정되지 않습니다. 사용자가 팝업에서 항목을 클릭하거나 강조 표시된 항목에서 Enter 키를 눌러 제안을 명시적으로 선택한 경우에만 업데이트됩니다.

예를 들어 시작할 때 모델의 첫 번째 항목을 표시하도록 currentIndex를 설정할 수 있습니다. 이렇게 하기 전에 모델이 비어 있지 않은지 확인하세요:

SearchField {
    id: searchField
    suggestionModel: ListModel {
        ListElement { value: "123,456" }
    }
    textRole: "value"

    Component.onCompleted: {
        if (suggestionModel.count > 0) {
           text = suggestionModel.get(0).value
           currentIndex = 0
       }
    }
}

activated(), text, highlightedIndex 를참조하세요 .

delegate : Component

이 속성은 검색 필드 팝업에 항목을 표시하는 델리게이트를 보유합니다.

델리게이트로 ItemDelegate (또는 다른 AbstractButton 파생)를 사용하는 것이 좋습니다. 이렇게 하면 상호 작용이 예상대로 작동하고 적절한 경우 팝업이 자동으로 닫힙니다. 다른 유형을 델리게이트로 사용하는 경우 팝업을 수동으로 닫아야 합니다. 예를 들어 MouseArea 을 사용하는 경우입니다:

delegate: Rectangle {
    // ...
    MouseArea {
        // ...
        onClicked: searchField.popup.close()
    }
}

Qt 6.11부터 SearchField 는 델리게이트의 소유권을 갖지 않습니다.

delegateModel : model [read-only]

이 속성은 검색 필드에 델리게이트 인스턴스를 제공하는 모델을 보유합니다.

일반적으로 popup 의 contentItem 에 ListView 에 할당됩니다.

highlightedIndex : int [read-only]

이 속성은 팝업 목록에서 현재 강조 표시된 항목의 색인을 보유합니다.

강조 표시된 항목이 활성화되면 팝업이 닫히고 currentIndex 이 highlightedIndex 과 일치하도록 업데이트되며 이 속성은 -1 으로 재설정되어 현재 강조 표시된 항목이 없음을 나타냅니다.

highlighted() 및 currentIndex 을참조하세요 .

live : bool

이 속성은 모든 텍스트 편집 시 검색이 트리거될지 여부를 결정하는 부울 값을 보유합니다.

true 로 설정하면 텍스트가 변경될 때마다 searchTriggered() 신호가 발생하여 모든 키 입력에 응답할 수 있습니다. false 로 설정하면 searchTriggered() 신호는 사용자가 Enter 또는 Return 키를 누를 때만 발생합니다.

searchTriggered()도 참조하세요 .

popup : Popup

이 속성은 팝업을 보관합니다.

필요한 경우 팝업을 수동으로 열거나 닫을 수 있습니다:

onSpecialEvent: searchField.popup.close()

searchIndicator group

이 그룹화된 속성은 searchIndicator 표시기 항목과 관련 속성을 보유합니다.

이 속성은 검색 표시기를 보유합니다. 이 속성을 누르면 searchButtonPressed()가 트리거됩니다.

스타일과 애플리케이션이 내부 속성을 통해 사용자 정의할 수 있도록 노출되어 있습니다(예: searchIndicator.indicator 을 통해 searchIndicator 을 대체 또는 제거하거나 눌렀을 때 및 마우스오버했을 때와 같은 상호 작용 상태에 반응하는 등).

SearchField's Indicators 를참조하세요 .

suggestionCount : int [read-only]

이 속성에는 제안 모델에서 표시할 제안의 수가 저장됩니다.

suggestionModel : model

이 속성에는 팝업 메뉴에 검색 제안을 표시하는 데 사용되는 데이터 모델이 저장됩니다.

SearchField {
    textRole: "age"
    suggestionModel: ListModel {
        ListElement { name: "Karen"; age: "66" }
        ListElement { name: "Jim"; age: "32" }
        ListElement { name: "Pamela"; age: "28" }
    }
}

textRole도 참조하세요 .

text : string

이 속성은 검색 필드에 현재 입력 텍스트를 보관합니다.

텍스트는 사용자 입력에 바인딩되어 추천 업데이트 또는 검색 로직을 트리거합니다.

searchTriggered() 및 textEdited()도 참조하세요 .

textRole : string

이 속성에는 팝업 목록에 표시되는 제안 모델에 항목을 표시하는 데 사용되는 모델 역할이 저장됩니다.

모델에 여러 역할이 있는 경우 textRole 을 설정하여 표시할 역할을 결정할 수 있습니다.

신호 문서

void accepted()

이 신호는 사용자가 엔터 키 또는 리턴 키를 눌러 입력을 확인하면 발신됩니다.

이 신호는 일반적으로 최종 텍스트 입력을 기반으로 검색 또는 작업을 트리거하는 데 사용되며, 사용자가 쿼리를 완료하거나 제출하려는 의도를 나타냅니다.

searchTriggered()도 참조하세요 .

void activated(int index)

이 신호는 사용자가 index 의 항목을 활성화할 때 발생합니다.

팝업이 열려 있는 동안 항목을 선택하면 항목이 활성화되어 팝업이 닫히고 currentIndex 이 변경됩니다. currentIndex 속성은 index 으로 설정됩니다.

currentIndex 를참조하세요 .

void clearButtonPressed()

이 신호는 지우기 버튼을 눌렀을 때 방출됩니다.

searchButtonPressed()도 참조하세요 .

void highlighted(int index)

이 신호는 사용자가 팝업 목록의 index 에 있는 항목을 강조 표시할 때 발생합니다.

강조 표시된 신호는 팝업이 열려 있고 항목이 강조 표시된 경우에만 발생하지만 반드시 activated 일 필요는 없습니다.

highlightedIndex 를참조하세요 .

void searchButtonPressed()

이 신호는 검색 버튼을 눌렀을 때 방출됩니다.

clearButtonPressed()도 참조하세요 .

void searchTriggered()

이 신호는 검색 작업이 시작될 때 발생합니다.

두 가지 경우에 발생합니다: 1. Enter 또는 Return 키를 누르면 accepted() 신호와 함께 발신됩니다. 텍스트가 편집되고 live 속성이 true 으로 설정된 경우 이 신호가 발생합니다.

이 신호는 원하는 상호 작용 모델에 따라 사용자가 입력하는 대로 주문형 및 실시간 검색을 시작하는 데 이상적입니다.

accepted() 및 textEdited()도 참조하세요 .

void textEdited()

이 신호는 사용자가 검색창의 텍스트를 수정할 때마다, 일반적으로 각 키 입력 시마다 발생합니다.

searchTriggered()도 참조하세요 .