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

Để triển khai tính năng tìm kiếm với sự hỗ trợ của hệ thống Android, tức là để phân phối các cụm từ tìm kiếm cho một hoạt động và đưa ra đề 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 theo cú pháp và cách sử dụng của tệp. Để 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, vui lòng xem phần Tạo giao diện tìm kiếm.

vị trí tệp:

res/xml/filename.xml
Android sử 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ấu hình tìm kiếm mà hệ thống Android sử 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 áp dụng cho thuộc tính android:label của phần tử tệp kê khai <activity> hoặc <application>. Nhãn này chỉ hiển thị cho người dùng 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. (Được đề xuất.) Văn bản sẽ hiển thị trong trường văn bản tìm kiếm khi không có văn bản nào được nhập. Tính năng này gợi ý cho người dùng về nội dung có thể tìm kiếm được. Để 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á. Thiết lập các chế độ bổ sung kiểm soát việc trình bày nội dung tìm kiếm. Các chế độ có sẵn xác định cách cần viết lại văn bản truy vấn khi một đề xuất tuỳ chỉnh được lấy tiêu điểm. Các giá trị chế độ sau được chấp nhận:

Giá trị	Nội dung mô tả
"queryRewriteFromData"	Sử dụng giá trị từ cột SUGGEST_COLUMN_INTENT_DATA để viết lại văn bản truy vấn. Bạn chỉ được sử dụng tính năng này khi các giá trị trong SUGGEST_COLUMN_INTENT_DATA phù hợp để 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ị từ 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 bài viết Thêm cụm từ tìm kiếm được đề xuất 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 thi lệnh tìm kiếm. Theo mặc định, nút này hiển thị một biểu tượng tìm kiếm (kính lúp), lý tưởng cho việc quốc tế hoá. Vì vậy, đừng sử dụng thuộc tính này để thay đổi nút trừ phi hành vi đó không phải là tìm kiếm, chẳng hạn như 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 sử dụng, chẳng hạn như loại bàn phím mềm. Đối với hầu hết các lượt tìm kiếm 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 tuỳ 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 có văn bản dạng tự do theo dự kiến, bạn không cần thuộc tính này. IME mặc định là actionSearch. IME này cung cấp nút "tìm kiếm" thay vì trả về vị trí đầu dòng trong bàn phím mềm. 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 đề xuất tìm kiếm

Nếu xác định một trình cung cấp nội dung để tạo các cụm từ tìm kiếm được đề xuất, thì bạn cần xác định các thuộc tính bổ sung để định cấu hình hoạt động giao tiếp với nhà cung cấp nội dung đó. Khi cung cấp cụm từ tìm kiếm được đề xuất, bạn cần có một số thuộc tính <searchable> sau:

android:searchSuggestAuthority

Chuỗi. (Bắt buộc để 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 như một phần của truy vấn đề xuất Uri, sau tiền tố và quyền và trước đường dẫn đề xuất chuẩn. Điều này chỉ bắt buộc nếu bạn 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 các loại dữ liệu khác nhau) và bạn cần có 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 chuyển vào hàm truy vấn dưới dạng tham số selection. Thông thường, đây là 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ào — ví dụ: "query=?". Tuy nhiên, bạn cũng có thể sử dụng bất kỳ giá trị không rỗng nào để 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. Thao tác theo ý định mặc định sẽ được sử dụng khi người dùng nhấn vào một cụm từ tìm kiếm được đề xuất 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 vào trường hành động 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 sử dụng khi người dùng nhấn vào một cụm từ tìm kiếm được đề xuất tuỳ chỉnh. Nếu đề xuất đã chọn không bị ghi đè (thông qua cột SUGGEST_COLUMN_INTENT_DATA), thì 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 tính năng tra cứu đề xuất. Điều này chỉ đảm bảo rằng hệ thống không truy vấn trình cung cấp nội dung của bạn cho 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 ở trên cho cụm từ tìm kiếm được đề xuất, hãy xem tài liệu về cách thêm cụm từ tìm kiếm được đề xuất tuỳ chỉnh và thêm nội dung đề xuất tuỳ chỉnh.

Thuộc tính 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ắt buộc khi 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 đưa nội dung đề xuất vào 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 dưới dạng một mục có thể tìm kiếm trong phần cài đặt tìm kiếm hệ thống trước khi đề xuất của bạn 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 cụm từ tìm kiếm mà bạn cung cấp cho Hộp tìm kiếm nhanh. Hộp tìm kiếm này xuất hiện trong mục có thể tìm kiếm cho ứng dụng của bạn. Phần mô tả của bạn phải mô tả chính xác nội dung có thể tìm kiếm được. Ví dụ: "Nghệ sĩ, đĩa nhạc và bản nhạc" đối với ứng dụng âm nhạc hoặc "Ghi chú đã lưu" đối với ứng dụng sổ tay.

android:queryAfterZeroResults

Boolean. Đặt thành "true" nếu bạn muốn gọi trình cung cấp nội dung cho các tập mẹ của truy vấn mà trước đó không trả về kết quả nào. Ví dụ: Nếu trình cung cấp nội dung của bạn trả về 0 kết quả cho "bo", thì kết quả đó phải được yêu cầu là "bob". Nếu bạn đặt thành "false", các tập mẹ sẽ bị bỏ qua trong một phiên – "bob" sẽ không gọi lại truy vấn lại. Việc này chỉ kéo dài trong vòng đời của hộp thoại tìm kiếm hoặc vòng đờ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 lại trình cung cấp nội dung của bạn. 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:

android:voiceSearchMode

Từ khoá. (Bắt buộc để cung cấp chức 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 chế độ cụ thể cho tính năng tìm kiếm bằng giọng nói. Có thể thiết bị không cung cấp tính năng tìm kiếm bằng giọng nói. Trong trường hợp đó, những cờ này sẽ không có tác dụng. Các giá trị chế độ sau được chấp nhận:

Giá trị	Nội dung 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 tìm kiếm bằng giọng nói. Nếu đặt giá trị, thì bạn cũng phải đặt "launchWebSearch" hoặc "launchRecognizer", phân tách bằng ký tự gạch đứ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 trên web bằng giọng nói tích hợp sẵn. Hầu hết ứng dụng không dùng cờ này vì cờ này sẽ đưa người dùng rời khỏi hoạt động mà tính năng 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 sẵn. Hoạt động này nhắc người dùng nói, chép lời và chuyển tiếp văn bản truy vấn kết quả đế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 rồi 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ị	Nội dung mô tả
"free_form"	Sử dụng chế độ nhận dạng lời nói dạng tự do để nhập truy vấn bằng giọng nói. Thao tác 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, giống như cụm từ tìm kiếm. Tính năng này hiện được hỗ trợ bằng 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. Thông báo bổ sung sẽ hiển thị trong hộp thoại nhập bằng giọng nói.

android:voiceLanguage

Chuỗi. Ngôn ngữ nói dự kiến được biểu thị bằng giá trị chuỗi của một hằng số trong Locale, chẳng hạn như "de" đối với tiếng Đức hoặc "fr" đối với tiếng Pháp. Điều này chỉ cần thiết nếu 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". Kết quả này luôn được cung cấp làm truy vấn chính của ý định ACTION_SEARCH. Phải 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á thiết bị và hành vi cho một hành động tìm kiếm. Một thao tác tìm kiếm cung cấp 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 nội dung đề 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 người liên hệ mà bạn đang đặt tiêu điểm khi nhấn vào nút GỌI.

Không phải tất cả các phím hành động đều dùng được trên mọi thiết bị và không phải mọi phím đều có thể được ghi đè theo cách này. Ví dụ: bạn không thể ghi đè phím "Home" (Màn hình chính) và phải luôn quay lại màn hình chính. Ngoài ra, hãy nhớ không xác định phím hành động cho một phím cần thiết để nhập cụm từ tìm kiếm. Điều này giới hạn các khoá hành động 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ột mã phím từ KeyEvent đại diện cho phím hành động bạn muốn phản hồi (ví dụ: "KEYCODE_CALL"). Ý định 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 sử dụng getIntExtra(SearchManager.ACTION_KEY). Không phải phím nào cũng được hỗ trợ cho một thao tác tìm kiếm, vì có nhiều phím được dùng để nhập, di chuyển hoặc thực hiện các chức năng của 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 khi đang nhập văn bản truy vấn. Ý định này được thêm vào ý định ACTION_SEARCH mà hệ thống chuyể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 bạn nhấn phím hành động khi một gợi ý được lấy làm tiêu điểm. Hành động này được thêm vào ý định mà hệ thống chuyể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 thuộc tính này nếu tất cả đề xuất đều hỗ trợ phím hành động này. Nếu không phải đề xuất nào cũng có thể xử lý cùng một phím hành động, thì bạn phải dùng thuộc tính android:suggestActionMsgColumn sau.

android:suggestActionMsgColumn

Chuỗi. Tên của cột trong trình cung cấp nội dung của bạn giúp xác định thông báo hành động cho phím hành động này. Thông báo này sẽ được gửi nếu người dùng nhấn phím hành động trong khi có tiêu điểm đề xuất. Thuộc tính này cho phép bạn kiểm soát khoá hành động trên cơ sở từng đề xuất, vì thay vì sử dụng thuộc tính android:suggestActionMsg để xác định thông báo hành động cho tất cả các đề xuất, mỗi mục nhập trong trình cung cấp nội dung của bạn lại cung cấp thông báo hành động 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 mỗi đề xuất cần 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, 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 chuyể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, thì phím hành động 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>