SearchField QML Type

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

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

속성

• clearIndicator
  • clearIndicator.hovered : bool
  • clearIndicator.implicitIndicatorHeight : real
  • clearIndicator.implicitIndicatorWidth : real
  • clearIndicator.indicator : Item
  • clearIndicator.pressed : bool
• currentIndex : int
• cursorPosition : int (since 6.12)
• delegate : Component
• delegateModel : model
• highlightedIndex : int
• live : bool
• placeholderText : string (since 6.12)
• popup : Popup
• searchIndicator
  • searchIndicator.hovered : bool
  • searchIndicator.implicitIndicatorHeight : real
  • searchIndicator.implicitIndicatorWidth : real
  • searchIndicator.indicator : Item
  • searchIndicator.pressed : bool
• selectTextByMouse : bool (since 6.12)
• selectedText : string (since 6.12)
• selectionEnd : int (since 6.12)
• selectionStart : int (since 6.12)
• 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()

방법

• void deselect() (since 6.12)
• void select(int start, int end) (since 6.12)
• void selectAll() (since 6.12)
• void selectWord() (since 6.12)

상세 설명

SearchField는 검색 기능에 사용하도록 설계된 전용 입력 필드입니다. 이 컨트롤에는 텍스트 필드, 검색 및 취소 아이콘, 그리고 제안 사항이나 검색 결과를 표시하는 팝업이 포함되어 있습니다.

SearchField의 표시기

SearchField는 두 가지 선택적 내장 인디케이터 버튼, 즉 ‘ searchIndicator ’와 ‘ clearIndicator ’를 제공합니다.

이 버튼들은 BusyIndicator 이나 ProgressBar 에서 말하는 인디케이터와는 다릅니다. 대신, 필드 내에 내장된 상호작용 가능한 컨트롤입니다( SpinBox 의 위/아래 버튼과 유사). searchIndicator 를 누르면 searchButtonPressed 가 트리거되고, clearIndicator 를 누르면 clearButtonPressed 가 트리거됩니다.

이 인디케이터 버튼은 액션을 노출할 뿐만 아니라, 스타일에서 활용할 수 있는 상호작용 상태(누름/마우스 오버/포커스 등)도 제공합니다.

표시기 내용 사용자 정의

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

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

예를 들어, 두 표시기 아이콘을 모두 제거하려면:

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

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

SearchField 모델 역할

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

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

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

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
    sourceModel: fruitModel
    sorters: [
        RoleSorter {
            roleName: "name"
        }
    ]
    filters: [
        FunctionFilter {
            property var regExp: new RegExp(fruitSearch.text, "i")
            onRegExpChanged: invalidate()
            function filter(name: string): bool {
                return regExp.test(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도 참조하십시오 .

cursorPosition : int [since 6.12]

텍스트 필드 내 커서의 위치입니다. 커서는 문자 사이에 위치합니다.

이 속성은 Qt 6.12에서 도입되었습니다.

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 로 설정하면 사용자가 Enter 또는 Return 키를 누를 때만 searchTriggered() 신호가 발생합니다.

searchTriggered()도 참조하십시오 .

placeholderText : string [since 6.12]

이 속성은 사용자가 텍스트를 입력하기 전에 ‘ SearchField ’에 표시되는 힌트를 저장합니다.

이 속성은 Qt 6.12에서 도입되었습니다.

popup : Popup

이 속성은 팝업을 포함합니다.

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

onSpecialEvent: searchField.popup.close()

searchIndicator group

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

이 속성은 검색 인디케이터를 포함합니다. 이 버튼을 누르면 ` searchButtonPressed`가 트리거됩니다.

이 속성은 스타일 및 애플리케이션이 내부 속성을 통해 이를 사용자 정의할 수 있도록 노출됩니다(예: ` searchIndicator.indicator`을 통해 ` searchIndicator `를 교체하거나 제거하거나, '누름' 및 '호버'와 같은 상호작용 상태에 반응하는 등).

SearchField's Indicators도 참조하십시오 .

selectTextByMouse : bool [since 6.12]

이 속성은 텍스트를 마우스로 선택할 수 있는지 여부를 나타냅니다.

기본값은 ` true`입니다.

이 속성은 Qt 6.12에서 도입되었습니다.

selectedText : string [read-only, since 6.12]

이 읽기 전용 속성은 현재 선택된 텍스트를 저장합니다.

이 속성은 Qt 6.12에서 도입되었습니다.

selectionEnd : int [read-only, since 6.12]

현재 선택 영역의 마지막 문자 뒤의 커서 위치.

이 속성은 읽기 전용입니다. 선택 영역을 변경하려면 select(start, end), selectAll() 또는 selectWord()을 사용하십시오.

이 속성은 Qt 6.12에서 도입되었습니다.

selectionStart, cursorPosition 및 selectedText도 참조하십시오 .

selectionStart : int [read-only, since 6.12]

현재 선택 영역의 첫 번째 문자 바로 앞의 커서 위치.

이 속성은 읽기 전용입니다. 선택 영역을 변경하려면 select(start, end), selectAll() 또는 selectWord()를 사용하십시오.

이 속성은 Qt 6.12에서 도입되었습니다.

selectionEnd, cursorPosition 및 selectedText도 참조하십시오 .

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 `을 설정하여 표시할 역할을 지정할 수 있습니다.

Signal 문서

void accepted()

이 신호는 사용자가 Enter 또는 Return 키를 눌러 입력을 확인했을 때 발생합니다.

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

searchTriggered()도 참조하십시오 .

void activated(int index)

이 신호는 index 에 있는 항목이 사용자에 의해 활성화될 때 발생합니다.

팝업이 열려 있는 상태에서 항목이 선택되면 해당 항목이 활성화된 것으로 간주되며, 이로 인해 팝업이 닫히고( currentIndex 의 값이 변경됩니다). currentIndex 속성은 index 로 설정됩니다.

currentIndex도 참조하십시오 .

void clearButtonPressed()

이 신호는 지우기 버튼을 누르면 발생합니다.

searchButtonPressed()도 참조하십시오 .

void highlighted(int index)

이 신호는 팝업 목록의 index 위치에 있는 항목이 사용자에 의해 강조 표시될 때 발생합니다.

highlighted 신호는 팝업이 열려 있고 항목이 선택되었을 때만 발생하지만, 반드시 activated 항목을 선택했을 때만 발생하는 것은 아닙니다.

highlightedIndex도 참조하십시오 .

void searchButtonPressed()

이 신호는 검색 버튼을 누르면 발생합니다.

clearButtonPressed()도 참조하십시오 .

void searchTriggered()

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

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

이 신호는 원하는 상호작용 모델에 따라 사용자가 입력하는 동안 필요에 따라 또는 실시간으로 검색을 시작하는 데 이상적입니다.

accepted() 및 textEdited()도 참조하십시오 .

void textEdited()

이 신호는 사용자가 검색 필드의 텍스트를 수정할 때마다, 대개 키를 누를 때마다 발생합니다.

searchTriggered()도 참조하십시오 .

메서드 문서

[since 6.12] void deselect()

현재 선택된 텍스트를 해제합니다.

이 메서드는 Qt 6.12에서 도입되었습니다.

selectedText, selectionStart 및 selectionEnd도 참조하십시오 .

[since 6.12] void select(int start, int end)

start 부터 end 까지의 텍스트를 선택합니다.

start 또는 end 중 하나라도 지정된 범위 밖인 경우, 선택 범위는 변경되지 않습니다.

이 메서드를 호출한 후, selectionStart 은 더 작은 값이 되고 selectionEnd 은 더 큰 값이 됩니다(이 메서드에 전달된 순서와 무관하게).

이 메서드는 Qt 6.12에서 도입되었습니다.

selectionStart 및 selectionEnd도 참조하십시오 .

[since 6.12] void selectAll()

컨트롤의 텍스트 필드에 있는 모든 텍스트를 선택합니다.

이 메서드는 Qt 6.12에서 도입되었습니다.

[since 6.12] void selectWord()

현재 커서 위치에서 가장 가까운 단어를 선택합니다.

이 메서드는 Qt 6.12에서 도입되었습니다.

cursorPosition 및 selectedText도 참조하십시오 .