Cấu hình tìm kiếm

Thử cách Compose

Jetpack Compose là bộ công cụ giao diện người dùng được đề xuất cho Android. Tìm hiểu cách thêm chức năng tìm kiếm trong Compose.

Thanh tìm kiếm →

Để triển khai tính năng tìm kiếm với sự trợ giúp của hệ thống Android (tức là để gửi cụm từ tìm kiếm đến một hoạt động và cung cấp đề xuất tìm kiếm), ứng dụng của bạn phải cung cấp cấu hình tìm kiếm dưới dạng tệp XML.

Trang này mô tả tệp cấu hình tìm kiếm về cú pháp và cách sử dụng. Để biết thêm thông tin về cách triển khai các tính năng tìm kiếm cho ứng dụng của bạn, hãy xem phần Tạo giao diện tìm kiếm.

vị trí tệp:

res/xml/filename.xml
Android dùng tên tệp làm mã nhận dạng tài nguyên.

cú pháp:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="string resource"
    android:hint="string resource"
    android:searchMode=["queryRewriteFromData" | "queryRewriteFromText"]
    android:searchButtonText="string resource"
    android:inputType="inputType"
    android:imeOptions="imeOptions"
    android:searchSuggestAuthority="string"
    android:searchSuggestPath="string"
    android:searchSuggestSelection="string"
    android:searchSuggestIntentAction="string"
    android:searchSuggestIntentData="string"
    android:searchSuggestThreshold="int"
    android:includeInGlobalSearch=["true" | "false"]
    android:searchSettingsDescription="string resource"
    android:queryAfterZeroResults=["true" | "false"]
    android:voiceSearchMode=["showVoiceSearchButton" | "launchWebSearch" | "launchRecognizer"]
    android:voiceLanguageModel=["free-form" | "web_search"]
    android:voicePromptText="string resource"
    android:voiceLanguage="string"
    android:voiceMaxResults="int"
    >
    <actionkey
        android:keycode="KEYCODE"
        android:queryActionMsg="string"
        android:suggestActionMsg="string"
        android:suggestActionMsgColumn="string" />
</searchable>

phần tử:

<searchable>

Xác định tất cả các cấu hình tìm kiếm mà hệ thống Android dùng để cung cấp tính năng tìm kiếm có hỗ trợ.

Thuộc tính:

android:label

Tài nguyên chuỗi. (Bắt buộc.) Tên ứng dụng của bạn. Tên này phải giống với tên được áp dụng cho thuộc tính android:label của phần tử tệp kê khai <activity> hoặc <application>. Người dùng chỉ thấy nhãn này khi bạn đặt android:includeInGlobalSearch thành "true". Trong trường hợp đó, nhãn này được dùng để xác định ứng dụng của bạn là một mục có thể tìm kiếm trong phần cài đặt tìm kiếm của hệ thống.

android:hint

Tài nguyên chuỗi. (Nên dùng.) Văn bản sẽ xuất hiện trong trường văn bản tìm kiếm khi không có văn bản nào được nhập. Thao tác này cung cấp cho người dùng gợi ý về nội dung có thể tìm kiếm. Để nhất quán với các ứng dụng Android khác, hãy định dạng chuỗi cho android:hint là "Tìm kiếm <content-or-product>". Ví dụ: "Tìm kiếm bài hát và nghệ sĩ" hoặc "Tìm kiếm trên YouTube".

android:searchMode

Từ khoá. Đặt các chế độ bổ sung để kiểm soát cách trình bày kết quả tìm kiếm. Các chế độ có sẵn xác định cách viết lại văn bản truy vấn khi một đề xuất tuỳ chỉnh nhận được tiêu điểm. Các giá trị chế độ sau đây được chấp nhận:

Giá trị	Mô tả
"queryRewriteFromData"	Sử dụng giá trị trong cột SUGGEST_COLUMN_INTENT_DATA để viết lại văn bản truy vấn. Bạn chỉ được dùng tham số này khi các giá trị trong SUGGEST_COLUMN_INTENT_DATA phù hợp với việc người dùng kiểm tra và chỉnh sửa, chẳng hạn như URI HTTP.
"queryRewriteFromText"	Sử dụng giá trị trong cột SUGGEST_COLUMN_TEXT_1 để viết lại văn bản truy vấn.

Để biết thêm thông tin, hãy xem tài liệu về cách viết lại văn bản truy vấn trong phần Thêm đề xuất tìm kiếm tuỳ chỉnh.

android:searchButtonText

Tài nguyên chuỗi. Văn bản sẽ xuất hiện trong nút thực hiện tìm kiếm. Theo mặc định, nút này sẽ cho thấy biểu tượng tìm kiếm (kính lúp), rất phù hợp cho việc quốc tế hoá. Vì vậy, đừng dùng thuộc tính này để thay đổi nút, trừ phi hành vi đó không phải là một lượt tìm kiếm, chẳng hạn như một yêu cầu URL trong trình duyệt web.

android:inputType

Từ khoá. Xác định loại phương thức nhập cần dùng, chẳng hạn như loại bàn phím ảo. Đối với hầu hết các lượt tìm kiếm mà bạn dự kiến sẽ có văn bản dạng tự do, bạn không cần thuộc tính này. Hãy xem inputType để biết danh sách các giá trị phù hợp cho thuộc tính này.

android:imeOptions

Từ khoá. Cung cấp các lựa chọn bổ sung cho phương thức nhập. Đối với hầu hết các lượt tìm kiếm mà bạn dự kiến sẽ có văn bản dạng tự do, bạn không cần thuộc tính này. IME mặc định là actionSearch, cung cấp nút "tìm kiếm" thay vì ký tự trả về trong bàn phím ảo. Hãy xem imeOptions để biết danh sách các giá trị phù hợp cho thuộc tính này.

Thuộc tính của cụm từ tìm kiếm được đề xuất

Nếu xác định một trình cung cấp nội dung để tạo đề xuất tìm kiếm, bạn cần xác định các thuộc tính bổ sung để thiết lập thông tin liên lạc với trình cung cấp nội dung. Khi cung cấp đề xuất tìm kiếm, bạn cần một số thuộc tính <searchable> sau:

android:searchSuggestAuthority

Chuỗi. (Bạn phải cung cấp cụm từ tìm kiếm được đề xuất.) Giá trị này phải khớp với chuỗi uỷ quyền được cung cấp trong thuộc tính android:authorities của phần tử <provider> trong tệp kê khai Android.

android:searchSuggestPath

Chuỗi. Đường dẫn này được dùng làm một phần của truy vấn đề xuất Uri, sau tiền tố và quyền hạn, đồng thời trước đường dẫn đề xuất tiêu chuẩn. Bạn chỉ cần làm việc này nếu có một trình cung cấp nội dung duy nhất đưa ra nhiều loại đề xuất (chẳng hạn như cho nhiều loại dữ liệu) và bạn cần một cách để phân biệt các truy vấn đề xuất khi nhận được chúng.

android:searchSuggestSelection

Chuỗi. Giá trị này được truyền vào hàm truy vấn của bạn dưới dạng tham số selection. Thông thường, đây là một mệnh đề WHERE cho cơ sở dữ liệu của bạn và phải chứa một dấu chấm hỏi duy nhất làm phần giữ chỗ cho chuỗi truy vấn thực tế do người dùng nhập – ví dụ: "query=?". Tuy nhiên, bạn cũng có thể sử dụng bất kỳ giá trị nào khác rỗng để kích hoạt việc phân phối văn bản truy vấn bằng cách sử dụng tham số selectionArgs, sau đó bỏ qua tham số selection).

android:searchSuggestIntentAction

Chuỗi. Hành động mặc định của ý định sẽ được dùng khi người dùng nhấn vào một đề xuất tìm kiếm tuỳ chỉnh, chẳng hạn như "android.intent.action.VIEW". Nếu giá trị này không bị đề xuất đã chọn ghi đè bằng cột SUGGEST_COLUMN_INTENT_ACTION, thì giá trị đó sẽ được đặt trong trường thao tác của Intent khi người dùng nhấn vào một đề xuất.

android:searchSuggestIntentData

Chuỗi. Dữ liệu ý định mặc định sẽ được dùng khi người dùng nhấn vào một đề xuất tìm kiếm tuỳ chỉnh. Nếu không bị đề xuất đã chọn ghi đè (thông qua cột SUGGEST_COLUMN_INTENT_DATA), giá trị này sẽ được đặt trong trường dữ liệu của Intent khi người dùng nhấn vào một đề xuất.

android:searchSuggestThreshold

Số nguyên. Số ký tự tối thiểu cần thiết để kích hoạt một lượt tìm kiếm đề xuất. Điều này chỉ đảm bảo rằng hệ thống không truy vấn nhà cung cấp nội dung của bạn về bất kỳ nội dung nào ngắn hơn ngưỡng. Giá trị mặc định là "0".

Để biết thêm thông tin về các thuộc tính nêu trên cho đề xuất tìm kiếm, hãy xem tài liệu về cách thêm đề xuất tìm kiếm tuỳ chỉnh và cách thêm đề xuất tuỳ chỉnh.

Thuộc tính của Hộp tìm kiếm nhanh

Để cung cấp các đề xuất tìm kiếm tuỳ chỉnh cho Hộp tìm kiếm nhanh, bạn cần có một số thuộc tính <searchable> sau:

android:includeInGlobalSearch

Boolean. (Bạn phải cung cấp đề xuất tìm kiếm trong Hộp tìm kiếm nhanh.) Đặt thành "true" nếu bạn muốn các đề xuất của mình xuất hiện trong Hộp tìm kiếm nhanh có thể truy cập trên toàn cầu. Người dùng vẫn phải bật ứng dụng của bạn làm mục có thể tìm kiếm trong phần cài đặt tìm kiếm của hệ thống thì các đề xuất của bạn mới xuất hiện trong Hộp tìm kiếm nhanh.

android:searchSettingsDescription

Tài nguyên chuỗi. Cung cấp nội dung mô tả ngắn gọn về các đề xuất tìm kiếm mà bạn cung cấp cho Hộp tìm kiếm nhanh. Nội dung này sẽ xuất hiện trong mục các mục có thể tìm kiếm cho ứng dụng của bạn. Nội dung mô tả phải mô tả ngắn gọn nội dung có thể tìm kiếm. Ví dụ: "Nghệ sĩ, đĩa nhạc và bài hát" cho một ứng dụng âm nhạc hoặc "Ghi chú đã lưu" cho một ứng dụng sổ tay.

android:queryAfterZeroResults

Boolean. Đặt thành "true" nếu bạn muốn nhà cung cấp nội dung của mình được gọi cho các siêu tập hợp truy vấn trước đây trả về 0 kết quả. Ví dụ: nếu nhà cung cấp nội dung của bạn trả về 0 kết quả cho "bo", thì bạn phải yêu cầu lại cho "bob". Nếu được đặt thành "false", các tập hợp con sẽ bị bỏ qua trong một phiên duy nhất – "bob" sẽ không gọi lại truy vấn. Việc này chỉ kéo dài trong thời gian tồn tại của hộp thoại tìm kiếm hoặc thời gian tồn tại của hoạt động khi sử dụng tiện ích tìm kiếm. Khi hộp thoại hoặc hoạt động tìm kiếm được mở lại, "bo" sẽ truy vấn nhà cung cấp nội dung của bạn một lần nữa. Giá trị mặc định là false.

Thuộc tính tìm kiếm bằng giọng nói

Để bật tính năng tìm kiếm bằng giọng nói, bạn cần có một số thuộc tính <searchable> sau đây:

android:voiceSearchMode

Từ khoá. (Cần thiết để cung cấp khả năng tìm kiếm bằng giọng nói.) Cho phép tìm kiếm bằng giọng nói, với một chế độ cụ thể cho tính năng tìm kiếm bằng giọng nói. Thiết bị có thể không cung cấp tính năng tìm kiếm bằng giọng nói. Trong trường hợp đó, các cờ này sẽ không có hiệu lực. Các giá trị chế độ sau đây được chấp nhận:

Giá trị	Mô tả
"showVoiceSearchButton"	Hiện nút tìm kiếm bằng giọng nói nếu thiết bị có tính năng này. Nếu được đặt, thì bạn cũng phải đặt "launchWebSearch" hoặc "launchRecognizer", phân tách bằng ký tự sổ thẳng (|).
"launchWebSearch"	Nút tìm kiếm bằng giọng nói sẽ đưa người dùng đến thẳng một hoạt động tìm kiếm bằng giọng nói trên web được tích hợp sẵn. Hầu hết các ứng dụng đều không sử dụng cờ này, vì cờ này sẽ đưa người dùng ra khỏi hoạt động mà trong đó lệnh tìm kiếm được gọi.
"launchRecognizer"	Nút tìm kiếm bằng giọng nói sẽ đưa người dùng đến thẳng một hoạt động ghi âm giọng nói tích hợp. Hoạt động này nhắc người dùng nói, chép lời văn bản đã nói và chuyển tiếp văn bản truy vấn thu được đến hoạt động có thể tìm kiếm, giống như khi người dùng nhập văn bản đó vào giao diện người dùng tìm kiếm và nhấn vào nút tìm kiếm.

android:voiceLanguageModel

Từ khoá. Mô hình ngôn ngữ mà hệ thống nhận dạng giọng nói phải sử dụng. Các giá trị sau được chấp nhận:

Giá trị	Mô tả
"free_form"	Sử dụng tính năng nhận dạng lời nói tự do để đọc chính tả các cụm từ tìm kiếm. Tính năng này chủ yếu được tối ưu hoá cho tiếng Anh. Đây là tuỳ chọn mặc định.
"web_search"	Sử dụng tính năng nhận dạng cụm từ tìm kiếm trên web cho các cụm từ ngắn hơn, tương tự như cụm từ tìm kiếm. Tính năng này hỗ trợ nhiều ngôn ngữ hơn "free_form".

Hãy xem EXTRA_LANGUAGE_MODEL để biết thêm thông tin.

android:voicePromptText

Tài nguyên chuỗi. Một thông báo bổ sung sẽ xuất hiện trong hộp thoại nhập bằng giọng nói.

android:voiceLanguage

Chuỗi. Ngôn ngữ dự kiến được nói, được biểu thị dưới dạng giá trị chuỗi của một hằng số trong Locale, chẳng hạn như "de" cho tiếng Đức hoặc "fr" cho tiếng Pháp. Bạn chỉ cần cung cấp thông tin này nếu giá trị này khác với giá trị hiện tại của Locale.getDefault().

android:voiceMaxResults

Số nguyên. Đặt số lượng kết quả tối đa cần trả về, bao gồm cả kết quả "tốt nhất" luôn được cung cấp dưới dạng truy vấn chính của ý định ACTION_SEARCH. Phải có giá trị từ 1 trở lên. Sử dụng EXTRA_RESULTS để nhận kết quả từ ý định. Nếu không được cung cấp, trình nhận dạng sẽ chọn số lượng kết quả cần trả về.

<actionkey>

Xác định khoá và hành vi của thiết bị cho một thao tác tìm kiếm. Thao tác tìm kiếm mang đến một hành vi đặc biệt khi người dùng nhấn vào một nút trên thiết bị, dựa trên cụm từ tìm kiếm hiện tại hoặc đề xuất được lấy làm tâm điểm. Ví dụ: ứng dụng Danh bạ cung cấp một thao tác tìm kiếm để bắt đầu cuộc gọi điện thoại đến đề xuất liên hệ hiện đang được lấy làm tâm điểm khi người dùng nhấn vào nút GỌI.

Không phải thiết bị nào cũng có tất cả các khoá thao tác và không phải khoá nào cũng có thể bị ghi đè theo cách này. Ví dụ: bạn không thể ghi đè phím "Trang chủ" và phím này phải luôn đưa người dùng quay lại màn hình chính. Ngoài ra, hãy nhớ không xác định khoá hành động cho khoá cần thiết để nhập cụm từ tìm kiếm. Điều này giới hạn các phím thao tác hợp lý và có sẵn cho nút gọi và nút trình đơn.

Bạn phải xác định android:keycode để xác định khoá và ít nhất một trong ba thuộc tính còn lại để xác định hành động tìm kiếm.

Thuộc tính:

android:keycode

Chuỗi. (Bắt buộc.) Mã khoá từ KeyEvent đại diện cho khoá thao tác mà bạn muốn phản hồi, ví dụ: "KEYCODE_CALL". Tham số này được thêm vào ý định ACTION_SEARCH được truyền đến hoạt động có thể tìm kiếm của bạn. Để kiểm tra mã khoá, hãy dùng getIntExtra(SearchManager.ACTION_KEY). Không phải phím nào cũng được hỗ trợ cho thao tác tìm kiếm, vì nhiều phím được dùng để nhập, điều hướng hoặc thực hiện các chức năng hệ thống.

android:queryActionMsg

Chuỗi. Một thông báo hành động sẽ được gửi nếu người dùng nhấn phím hành động trong khi nhập văn bản truy vấn. Thao tác này sẽ thêm vào ý định ACTION_SEARCH mà hệ thống truyền đến hoạt động có thể tìm kiếm của bạn. Để kiểm tra chuỗi, hãy sử dụng getStringExtra(SearchManager.ACTION_MSG).

android:suggestActionMsg

Chuỗi. Một thông báo hành động sẽ được gửi nếu nhấn phím hành động trong khi một đề xuất đang được lấy tiêu điểm. Tham số này được thêm vào ý định mà hệ thống truyền đến hoạt động có thể tìm kiếm của bạn, bằng cách sử dụng thao tác mà bạn xác định cho đề xuất. Để kiểm tra chuỗi, hãy sử dụng getStringExtra(SearchManager.ACTION_MSG). Bạn chỉ được sử dụng phím hành động này nếu tất cả các đề xuất của bạn đều hỗ trợ phím này. Nếu không phải tất cả các đề xuất đều có thể xử lý cùng một khoá hành động, thì bạn phải sử dụng thuộc tính android:suggestActionMsgColumn sau đây.

android:suggestActionMsgColumn

Chuỗi. Tên của cột trong trình cung cấp nội dung xác định thông báo hành động cho khoá hành động này. Thông báo này sẽ được gửi nếu người dùng nhấn khoá hành động trong khi một đề xuất đang được lấy tiêu điểm. Thuộc tính này cho phép bạn kiểm soát khoá thao tác theo từng đề xuất, vì thay vì dùng thuộc tính android:suggestActionMsg để xác định thông báo thao tác cho tất cả đề xuất, mỗi mục trong trình cung cấp nội dung sẽ cung cấp thông báo thao tác riêng.

Trước tiên, bạn phải xác định một cột trong trình cung cấp nội dung cho từng đề xuất để cung cấp thông báo hành động, sau đó cung cấp tên của cột đó trong thuộc tính này. Hệ thống sẽ xem xét con trỏ đề xuất của bạn, sử dụng chuỗi được cung cấp ở đây để chọn cột thông báo hành động, sau đó chọn chuỗi thông báo hành động từ con trỏ. Chuỗi đó được thêm vào ý định mà hệ thống truyền đến hoạt động có thể tìm kiếm của bạn, bằng cách sử dụng thao tác mà bạn xác định cho các đề xuất. Để kiểm tra chuỗi, hãy sử dụng getStringExtra(SearchManager.ACTION_MSG). Nếu không có dữ liệu cho đề xuất đã chọn, khoá thao tác sẽ bị bỏ qua.

ví dụ:

Tệp XML được lưu vào res/xml/searchable.xml:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/search_label"
    android:hint="@string/search_hint"
    android:searchSuggestAuthority="dictionary"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:includeInGlobalSearch="true"
    android:searchSettingsDescription="@string/settings_description" >
</searchable>