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à để cung cấp tính năng tìm kiếm truy vấn một hoạt động và cung cấp cụm từ tìm kiếm được đề xuất. Ứng dụng của bạn phải cung cấp tính năng 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. Để 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 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 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. Mã này phải giống với tên áp dụng cho thuộc tính android:label của <activity> hoặc <application> phần tử tệp kê khai. Nhãn này chỉ hiển thị cho người dùng khi bạn đặt android:includeInGlobalSearch đến "true". Trong trường hợp đó, nhãn này sẽ được sử dụng để xác định ứng dụng của bạn là mục có thể tìm kiếm trong 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. Tính năng này gợi ý cho người dùng về nội dung có thể tìm kiếm được. Đảm bảo tính nhất quán với các ứng dụng Android khác, hãy định dạng chuỗi cho android:hint thành "Tìm kiếm" <content-or-product>". Ví dụ: "Tìm bài hát và nghệ sĩ" hoặc "Tìm trên YouTube".

android:searchMode

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

Giá trị	Mô tả
"queryRewriteFromData"	Sử dụng giá trị từ SUGGEST_COLUMN_INTENT_DATA để viết lại văn bản truy vấn. Giá trị này chỉ được sử dụng 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, như URI HTTP.
"queryRewriteFromText"	Sử dụng giá trị từ SUGGEST_COLUMN_TEXT_1 để viết lại nội dung 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 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 cần hiển thị trong nút thực thi quá trình tìm kiếm. Theo Mặc định, nút này sẽ hiển thị biểu tượng tìm kiếm (kính lúp). Đây là biểu tượng lý tưởng để 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 đó một thứ gì đó khác ngoài lượt 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 dữ liệu cần sử dụng, chẳng hạn như loại phần mềm . Đối với hầu hết các lượt tìm kiếm, trong đó văn bản dạng tự do được mong đợi, bạn không cần thuộc tính nà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, bằng cần có văn bản dạng tự do, nên bạn không cần thuộc tính này. IME mặc định là actionSearch, cung cấp chức năng "tìm kiếm" thay vì nút trả lại vị trí đầu dòng trong bàn phím mềm. 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ụm từ tìm kiếm được đề xuất, bạn cần xác định các thuộc tính bổ sung định cấu hình giao tiếp với nhà cung cấp nội dung. Khi cung cấp công cụ tìm kiếm đề 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ác cụm từ tìm kiếm được đề xuất.) Giá trị này phải khớp với chuỗi đơn vị quản lý được cung cấp trong 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 trong các đề xuất truy vấn Uri, sau tiền tố và 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 nhà cung cấp nội dung đưa ra nhiều loại đề xuất, chẳng hạn như đề xuất 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 chuyển vào dưới dạng tham số selection. Thông thường, đây là mệnh đề WHERE cho cơ sở dữ liệu của mình 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ị 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 đượ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ách sử dụng thuộc tính SUGGEST_COLUMN_INTENT_ACTION thì giá trị này sẽ được đặt vào trường hành động Intent khi người dùng nhấn một đề xuất.

android:searchSuggestIntentData

Chuỗi. Dữ liệu ý định mặc định đượ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 không bị đề xuất đã chọn ghi đè, thông qua SUGGEST_COLUMN_INTENT_DATA cột—giá trị này được đặt trong trường dữ liệu của Intent khi người dùng nhấn một đề xuất.

android:searchSuggestThreshold

Số nguyên. Số ký tự tối thiểu cần thiết để kích hoạt tra cứu đề xuất. Điều này chỉ đảm bảo rằng hệ thống sẽ không truy vấn nhà cung cấp nội dung 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 đối với cụm từ tìm kiếm được đề xuất ở trên, hãy xem tài liệu để thêm cụm từ tìm kiếm được đề xuất tuỳ chỉnh và thêm đề xuất tuỳ chỉnh.

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

Để tạo đề xuất tìm kiếm tuỳ chỉnh khả dụng cho Hộp Tìm kiếm Nhanh, bạn cần một số thuộc tính <searchable> sau:

android:includeInGlobalSearch

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

android:searchSettingsDescription

Tài nguyên chuỗi. Cung cấp mô tả ngắn gọn về các đề xuất tìm kiếm bạn cung cấp cho Hộp Tìm kiếm Nhanh. Hộp này sẽ được hiển thị trong mục nhập mục có thể tìm kiếm cho . Phần mô tả của bạn phải mô tả ngắn gọn nội dung có thể tìm kiếm. Cho ví dụ: "Nghệ sĩ, đĩa nhạc và bản nhạc" đối với ứng dụng nhạc hoặc "Ghi chú đã lưu" cho một ứng dụng Notepad.

android:queryAfterZeroResults

Boolean. Đặt thành "true" nếu bạn muốn là nhà cung cấp nội dung của mình được gọi cho tập mẹ các truy vấn 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ì phải gửi yêu cầu lại cho "bob". Nếu được đặt thành "false", các tập mẹ sẽ bị bỏ qua trong một phiên — "bob" sẽ không gọi ra một truy vấn lại. Điều 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 dùng tiện ích tìm kiếm. Khi hộp thoại tìm kiếm hoặc hoạt động được mở lại, "bo" truy vấn trì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ó thuộc tính <searchable> sau:

android:voiceSearchMode

Từ khoá. (Bắt buộc để cung cấp khả năng tìm kiếm bằng giọng nói.) Bật tìm kiếm bằng giọng nói với một chế độ cụ thể cho 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 đó, những cờ này đều không có tác dụng. Các giá trị sau đây của chế độ được chấp nhận:

Giá trị	Mô tả
"showVoiceSearchButton"	Hiển thị nút tìm kiếm bằng giọng nói nếu tính năng tìm kiếm bằng giọng nói có sẵn trên thiết bị. Nếu được đặt, thì bạn cũng phải đặt "launchWebSearch" hoặc "launchRecognizer", được phân tách bằng dấu gạch đứng (|).
"launchWebSearch"	Nút tìm kiếm bằng giọng nói đưa người dùng đến thẳng vào hoạt động tìm kiếm bằng giọng nói tích hợp sẵn trên web. Hầu hết các ứng dụng không sử dụng cờ này vì phương thức này đưa người dùng ra khỏi hoạt động mà tìm kiếm được gọi ra.
"launchRecognizer"	Nút tìm kiếm bằng giọng nói sẽ lấy đưa người dùng đến hoạt động ghi âm giọng nói được tích hợp sẵn. 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 kết quả văn bản truy vấn vào 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à phải được hệ thống nhận dạng giọng nói sử dụng. Các giá trị sau được chấp nhận:

Giá trị	Mô tả
"free_form"	Sử dụng công nghệ nhận dạng lời nói dạng tự do để nhập truy vấn bằng giọng nói. Việ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ác cụm từ tìm kiếm. Đây là được hỗ trợ bằng nhiều ngôn ngữ hơn "free_form".

Xem EXTRA_LANGUAGE_MODEL để xem thêm của bạn.

android:voicePromptText

Tài nguyên chuỗi. Một 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ị dưới dạ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 nó khác từ giá trị hiện tại là Locale.getDefault().

android:voiceMaxResults

Số nguyên. Đặt số lượng kết quả tối đa cần trả về, bao gồm lựa chọn "tốt nhất" luôn được cung cấp dưới dạng ACTION_SEARCH truy vấn chính của ý định. 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 một khoá thiết bị và hành vi cho một hành động tìm kiếm. Mỗi hành động tìm kiếm mang lại khi nhấn vào một nút trên thiết bị, dựa trên truy vấn hiện tại hoặc được lấy tiêu điểm . Ví dụ: ứng dụng Danh bạ cung cấp một thao tác tìm kiếm để kích hoạt cuộc gọi cuộc gọi đến đề xuất người liên hệ hiện được lấy làm tiêu điểm khi nhấn vào nút GỌI.

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

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

Thuộc tính:

android:keycode

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

android:queryActionMsg

Chuỗi. Hệ thống sẽ gửi một thông báo hành động nếu người dùng nhấn phím hành động trong khi người dùng đang nhập văn bản truy vấn. Thông tin này được thêm vào ACTION_SEARCH ý định mà hệ thống chuyển sang 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. Hệ thống sẽ gửi một thông báo hành động nếu người dùng nhấn phím hành động trong khi đề xuất đang nằm trong tiêu điểm. Mã 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—sử dụng hành động bạn xác định cho đề xuất. Để kiểm tra chuỗi, 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ả nội dung đề xuất của bạn đều hỗ trợ khoá hành động này. Nếu không phải tất cả các đề xuất có thể xử lý cùng một phím hành động, thì bạn phải sử dụng Thuộc tính android:suggestActionMsgColumn.

android:suggestActionMsgColumn

Chuỗi. Tên của cột trong trình cung cấp nội dung của bạn 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 khi một gợi ý đang nằm trong tiêu điểm. Thuộc tính này cho phép bạn kiểm soát phím hành động trên cơ sở từng đề xuất, bởi 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ả đề xuất, mỗi mục nhập trong trình cung cấp nội dung của bạn sẽ 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 của mình cho mỗi đề xuất cần cung cấp một thông báo hành động cho, rồi cung cấp tên của cột đó trong thuộc tính này. Hệ thống xem xét con trỏ đề xuất của bạn, sử dụng chuỗi được cung cấp ở đây để chọn hành động thông báo rồi chọn chuỗi thông báo hành động từ con trỏ. Chuỗi đó là được thêm vào ý định mà hệ thống chuyển sang hoạt động có thể tìm kiếm của bạn, bằng cách sử dụng thao tác bạn xác định 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>