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 という 2 つのオプションの組み込みインジケーターボタンが用意されています。

これらは、BusyIndicator やProgressBar のような意味でのインジケーターではありません。代わりに、フィールドに埋め込まれたインタラクティブなコントロールです（SpinBox の上下ボタンと同様です）。searchIndicator を押すとsearchButtonPressed がトリガーされ、clearIndicator を押すとclearButtonPressed がトリガーされます。

アクションを公開することに加え、インジケーターボタンは、スタイルで利用できるインタラクション状態（押下中／ホバー中／フォーカス中など）を提供します。

インジケータの内容のカスタマイズ

searchIndicator およびclearIndicator プロパティは読み取り専用です。カスタマイズは、これらの内部プロパティを通じて行えます。

特に、ボタンの視覚的なコンテンツは、書き込み可能なindicator 項目によって提供されます。これにより、デフォルトのコンテンツを置き換えたり、完全に削除したりすることが可能です。

たとえば、両方のインジケーターアイコンを削除するには：

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

これはサポートされているカスタマイズシナリオです。SearchField のバリエーションによっては、ボタンの一方を省略したり（たとえば、検索ボタンのみを表示したり）、インジケーターのコンテンツを別の項目（たとえば、音声入力を起動するマイクアイコンなど）に置き換えたりする場合があります。

SearchField モデルの役割

SearchFieldは、「modelData 」ロールを提供する標準データモデルを可視化できます：

• ロールが 1 つしかないモデル
• 名前付きロールを持たないモデル（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 に設定すると、searchTriggered()はユーザーがEnterキーまたはReturnキーを押したときにのみ発信されます。

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()

このシグナルは、検索アクションが開始されたときに発生します。

このシグナルは、次の 2 つの場合に発生します。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も参照してください 。