SearchField QML Type

検索機能に特化した入力フィールド。詳細...

Import Statement: import QtQuick.Controls
Since: Qt 6.10
Inherits:

Control

プロパティ

信号

詳細説明

SearchField は、検索機能に特化した入力フィールドです。このコントロールには、テキストフィールド、検索アイコン、クリアアイコン、候補や検索結果を表示するポップアップが含まれます。

SearchField モデルの役割

SearchField は、modelData ロールを提供する標準的なデータモデルを視覚化することができます:

  • ロールが1つしかないモデル
  • 名前付きロールを持たないモデル (JavaScript 配列、整数)

複数の名前付きロールを持つモデルを使用する場合、SearchField はtextdelegate インスタンスに特定の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" }
}

QSortFilterProxyModel {
    id: fruitFilter
    sourceModel: fruitModel
    filterRegularExpression: RegExp(fruitSearch.text, "i")
    filterRole: 0 // needs to be set explicitly
}

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

プロパティ Documentation

clearIndicator : real [read-only]

このプロパティは、クリアインジケータを保持します。


currentIndex : int

このプロパティは、ポップアップ・リストで現在選択されている候補のインデックスを保持します。

デフォルト値は、count が0 の場合は-1 で、それ以外の場合は0 です。

activated()、text 、およびhighlightedIndexも参照してください


delegate : Component

このプロパティは、検索フィールドポップアップに項目を提示するデリゲートを保持します。

デリゲートとしてItemDelegate (または他のAbstractButton 派生物)を使用することを推奨します。これにより、インタラクションが期待通りに動作し、適切なときにポップアップが自動的に閉じます。他の型をデリゲートとして使用する場合、ポップアップは手動で閉じなければなりません。例えば、MouseArea

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

delegateModel : model [read-only]

このプロパティは、検索フィールドのデリゲート・インスタンスを提供するモデルを保持します。

これは通常、popupcontentItemListView に割り当てられます。


highlightedIndex : int [read-only]

このプロパティは、ポップアップ・リストで現在ハイライトされている項目のインデックスを保持します。

ハイライトされた項目がアクティブになると、ポップアップが閉じ、currentIndexhighlightedIndex と一致するように更新され、このプロパティは-1 にリセットされ、現在ハイライトされている項目がないことを示します。

highlighted() およびcurrentIndexも参照のこと


live : bool

このプロパティは、テキスト編集のたびに検索がトリガされるかどうかを決定するブーリアン値を保持します。

true に設定すると、テキストが変更されるたびにsearchTriggered() シグナルが発せられ、すべてのキー入力に応答できるようになります。false に設定すると、ユーザーが Enter キーまたは Return キーを押したときにのみsearchTriggered() が出力されます。

searchTriggered()も参照してください


このプロパティはポップアップを保持します。

ポップアップは、必要に応じて手動で開いたり閉じたりできます:

onSpecialEvent: searchField.popup.close()

searchIndicator : real [read-only]

このプロパティは、検索インジケータを保持します。


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

このシグナルは、ユーザがEnterキーまたはReturnキーを押して入力を確定した時に発行されます。

このシグナルは通常、最終的なテキスト入力に基づいて検索やアクションをトリガするために使用され、ユーザがクエリを完了または送信する意思を示します。

注: 対応するハンドラはonAccepted

searchTriggered()も参照してください


void activated(int index)

このシグナルは、index の項目がユーザーによってアクティブにされたときに発せられます。

アイテムがアクティブになるのは、ポップアップが開いている間にそのアイテムが選択され、ポップアップが閉じる(そしてcurrentIndex が変更される)ときです。currentIndex プロパティはindex に設定されます。

注: 対応するハンドラはonActivated です。

currentIndexも参照してください


void highlighted(int index)

このシグナルは、ポップアップ・リストのindex にあるアイテムがユーザによってハイライトされたときに発せられます。

highlighted シグナルは、ポップアップが開いていて、アイテムがハイライトされているときにのみ発せられますが、必ずしもactivated である必要はありません。

注意: 対応するハンドラはonHighlighted です。

highlightedIndexも参照してください


void searchTriggered()

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

次の2つの場合に発生します:1.1. EnterキーまたはReturnキーが押されたとき、accepted() シグナルとともに発せられる 2.テキストが編集され、live プロパティがtrue に設定されると、このシグナルが発信されます。

このシグナルは、希望するインタラクション・モデルに応じて、オンデマンドでもリアルタイムでも、ユーザーの入力に合わせて検索を開始するのに理想的です。

注: 対応するハンドラはonSearchTriggered です。

accepted() とtextEdited()も参照のこと


void textEdited()

このシグナルは、ユーザーが検索フィールドのテキストを変更するたびに発行される。

注: 対応するハンドラはonTextEdited

searchTriggered()も参照


© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.