Trang này được dịch bởi Cloud Translation API.

Thêm cụm từ tìm kiếm được đề xuất tuỳ chỉnh

Khi sử dụng tiện ích tìm kiếm hoặc hộp thoại tìm kiếm trên Android, bạn có thể cung cấp đề xuất tìm kiếm tùy chỉnh được tạo từ dữ liệu trong ứng dụng của bạn. Ví dụ: nếu ứng dụng của bạn là từ điển, bạn có thể đề xuất các từ từ từ điển khớp với văn bản đã nhập vào trường tìm kiếm trước khi người dùng nhập xong truy vấn của họ. Những đề xuất này có giá trị vì có thể dự đoán một cách hiệu quả những gì người dùng muốn và cung cấp quyền truy cập tức thì vào nội dung đó. Hình 1 cho thấy một ví dụ của hộp thoại tìm kiếm với đề xuất tuỳ chỉnh.

Sau khi đưa ra đề xuất tuỳ chỉnh, bạn cũng có thể cung cấp đề xuất đó cho Hộp Tìm kiếm Nhanh trên toàn hệ thống, cung cấp quyền truy cập vào nội dung của bạn từ bên ngoài .

Trước khi bạn thêm đề xuất tuỳ chỉnh, hãy triển khai hộp thoại tìm kiếm trên Android hoặc tiện ích tìm kiếm cho các lượt tìm kiếm trong ứng dụng của bạn. Xem phần Tạo giao diện tìm kiếm và Nội dung .

Thông tin cơ bản

Hình 1. Ảnh chụp màn hình hộp thoại tìm kiếm có đề xuất tìm kiếm tuỳ chỉnh.

Khi người dùng chọn một đề xuất tuỳ chỉnh, hệ thống sẽ gửi một Intent vào hoạt động có thể tìm kiếm. Không giống như một truy vấn tìm kiếm thông thường gửi ý định cùng với ACTION_SEARCH hành động, bạn có thể xác định các đề xuất tuỳ chỉnh cần sử dụng ACTION_VIEW hoặc bất kỳ hành động theo ý định nào khác—và cũng bao gồm dữ liệu có liên quan đến đề xuất đã chọn. Trong ví dụ từ điển, khi người dùng chọn một đề xuất, ứng dụng có thể mở ngay định nghĩa cho từ đó, tìm kiếm kết quả phù hợp trong từ điển.

Để cung cấp nội dung đề xuất tuỳ chỉnh, hãy làm theo các bước sau:

Triển khai một hoạt động có thể tìm kiếm cơ bản, như được mô tả trong Tạo giao diện tìm kiếm.
Sửa đổi cấu hình có thể tìm kiếm được với thông tin về nội dung cung cấp các đề xuất tùy chỉnh.
Tạo một bảng, chẳng hạn như trong một SQLiteDatabase, cho đề xuất của bạn và định dạng bảng với các cột bắt buộc.
Tạo nội dung trình cung cấp có quyền truy cập vào bảng đề xuất và khai báo trong tệp kê khai của bạn.
Khai báo loại Intent sẽ được gửi khi người dùng chọn một bao gồm cả thao tác tuỳ chỉnh và dữ liệu tuỳ chỉnh.

Giống như khi hệ thống Android hiển thị hộp thoại tìm kiếm, hệ thống cũng hiển thị cụm từ tìm kiếm được đề xuất. Bạn cần một nhà cung cấp nội dung mà hệ thống có thể truy xuất đề xuất của bạn. Đã đọc Trình cung cấp nội dung để tìm hiểu cách tạo trình cung cấp nội dung.

Khi hệ thống xác định rằng hoạt động của bạn có thể tìm kiếm được và cung cấp các đề xuất tìm kiếm, quy trình sau đây sẽ diễn ra khi người dùng nhập truy vấn:

Hệ thống sẽ lấy văn bản cụm từ tìm kiếm, tức là bất cứ thông tin nào được nhập cho đến thời điểm này—và thực hiện truy vấn tới trình cung cấp nội dung quản lý nội dung đề xuất.
Trình cung cấp nội dung của bạn trả về một Cursor trỏ đến tất cả nội dung đề xuất có liên quan đến cụm từ tìm kiếm .
Hệ thống sẽ hiển thị danh sách các đề xuất do Cursor.

Sau khi các đề xuất tuỳ chỉnh được hiển thị, những điều sau có thể xảy ra:

Nếu người dùng nhập một chữ cái khác hoặc thay đổi truy vấn theo bất kỳ cách nào, thì các bước trước đó lặp lại và danh sách đề xuất sẽ cập nhật tương ứng.
Nếu người dùng thực hiện tìm kiếm, đề xuất sẽ bị bỏ qua và tìm kiếm sẽ được phân phối tới hoạt động có thể tìm kiếm của bạn bằng cách sử dụng Ý định ACTION_SEARCH.
Nếu người dùng chọn một đề xuất, hệ thống sẽ gửi ý định đó đến trang web có thể tìm kiếm hoạt động, mang theo thao tác tuỳ chỉnh và dữ liệu tuỳ chỉnh để ứng dụng của bạn có thể mở nội dung được đề xuất.

Sửa đổi cấu hình có thể tìm kiếm

Để thêm tính năng hỗ trợ cho các đề xuất tùy chỉnh, hãy thêm phương thức Thuộc tính android:searchSuggestAuthority cho <searchable> trong tệp cấu hình có thể tìm kiếm được, như trong ví dụ sau:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider">
</searchable>

Bạn có thể cần các thuộc tính bổ sung, tuỳ thuộc vào loại ý định mà bạn có đính kèm vào mỗi đề xuất và cách bạn muốn định dạng truy vấn cho nội dung của mình Google Cloud. Các thuộc tính không bắt buộc khác được thảo luận trong phần sau đây .

Tạo một trình cung cấp nội dung

Để tạo một trình cung cấp nội dung cho các đề xuất tuỳ chỉnh, trước tiên hãy xem Trình cung cấp nội dung để tìm hiểu cách tạo trình cung cấp nội dung. Trình cung cấp nội dung cho dịch vụ tương tự như mọi trình cung cấp nội dung khác. Tuy nhiên, đối với mỗi đề xuất mà bạn cung cấp, thì hàng tương ứng trong Cursor phải bao gồm các cột cụ thể mà hệ thống hiểu và sử dụng để định dạng nội dung đề xuất.

Khi người dùng nhập văn bản vào hộp thoại tìm kiếm hoặc tiện ích tìm kiếm, hệ thống truy vấn nhà cung cấp nội dung của bạn để nhận các đề xuất bằng cách gọi query() mỗi khi một chữ cái được nhập vào. Trong quá trình triển khai query(), trình cung cấp nội dung phải tìm kiếm dữ liệu đề xuất và trả về một Cursor trỏ đến những hàng mà hệ thống xác định là phù hợp nội dung đề xuất.

Thông tin chi tiết về cách tạo trình cung cấp nội dung cho đề xuất tuỳ chỉnh là sẽ được thảo luận trong 2 phần sau đây:

Xử lý truy vấn đề xuất: Cách hệ thống gửi yêu cầu đến trình cung cấp nội dung của bạn và cách xử lý chúng.
Tạo bảng đề xuất: Cách xác định các cột mà hệ thống dự kiến trong Đã trả về Cursor cho mỗi truy vấn.

Xử lý truy vấn đề xuất

Khi yêu cầu nội dung đề xuất từ nhà cung cấp nội dung của bạn, hệ thống sẽ gọi phương thức query() của trình cung cấp nội dung. Triển khai phương thức này để tìm kiếm dữ liệu đề xuất và trả về Cursor trỏ đến các đề xuất mà bạn cho là phù hợp.

Dưới đây là phần tóm tắt về các thông số mà hệ thống chuyển đến query(), được liệt kê theo thứ tự:

uri: Luôn là một nội dung Uri, có định dạng là sau:
content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY

Hành vi mặc định là để hệ thống truyền URI này và thêm truy vấn văn bản vào đó:

content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY/puppies

Văn bản truy vấn ở cuối được mã hoá bằng các quy tắc mã hoá URI, do đó bạn có thể cần giải mã mã trước khi thực hiện tìm kiếm.

Phần optional.suggest.path chỉ có trong URI nếu bạn đặt một đường dẫn như vậy trong tệp cấu hình có thể tìm kiếm bằng thuộc tính android:searchSuggestPath. Chỉ cần thiết nếu bạn sử dụng cùng một nhà cung cấp nội dung cho nhiều hoạt động có thể tìm kiếm. Nếu trong trường hợp này, hãy phân biệt nguồn của truy vấn đề xuất.

Lưu ý: SUGGEST_URI_PATH_QUERY không phải là chuỗi ký tự được cung cấp trong URI; thì đó là một hằng số. Hãy sử dụng thuộc tính này nếu bạn cần tham khảo đường dẫn.
projection: Luôn rỗng.
selection: Giá trị được cung cấp trong android:searchSuggestSelection của tệp cấu hình có thể tìm kiếm của bạn hoặc rỗng nếu bạn không thể Hãy khai báo thuộc tính android:searchSuggestSelection. Chiến lược phát hành đĩa đơn chúng ta sẽ thảo luận thêm về vấn đề này trong phần sau.
selectionArgs: Chứa cụm từ tìm kiếm dưới dạng phần tử đầu tiên và duy nhất của mảng nếu bạn khai báo thuộc tính android:searchSuggestSelection trong cấu hình có thể tìm kiếm của bạn. Nếu bạn không khai báo android:searchSuggestSelection, thì tham số này có giá trị rỗng. Phần sau đây sẽ thảo luận thêm về vấn đề này.
sortOrder: Luôn rỗng.

Hệ thống có thể gửi cho bạn văn bản cụm từ tìm kiếm theo hai cách. Cách mặc định là để văn bản truy vấn được đưa vào dưới dạng đường dẫn cuối cùng của URI nội dung được chuyển vào tham số uri. Tuy nhiên, nếu bạn đưa một giá trị lựa chọn vào android:searchSuggestSelection của cấu hình có thể tìm kiếm thì văn bản truy vấn sẽ chuyển dưới dạng phần tử đầu tiên của Mảng chuỗi selectionArgs. Hai tuỳ chọn này được mô tả tiếp theo.

Nhận truy vấn trong URI

Theo mặc định, truy vấn được thêm vào dưới dạng phân đoạn cuối cùng của uri tham số — một đối tượng Uri. Để truy xuất văn bản truy vấn trong trường hợp, sử dụng getLastPathSegment(), như trong ví dụ sau:

Kotlin

val query: String = uri.lastPathSegment.toLowerCase()

Java

String query = uri.getLastPathSegment().toLowerCase();

Thao tác này sẽ trả về phân đoạn cuối cùng của Uri, chính là truy vấn văn bản mà người dùng nhập.

Lấy truy vấn trong đối số lựa chọn

Thay vì sử dụng URI, URI này có thể phù hợp hơn cho Phương thức query() để nhận mọi thứ cần thiết nhằm thực hiện và bạn có thể muốn selection và Tham số selectionArgs để mang các giá trị thích hợp. Trong phần này trường hợp, hãy thêm thuộc tính android:searchSuggestSelection vào cấu hình có thể tìm kiếm được bằng chuỗi lựa chọn SQLite. Trong phần lựa chọn chuỗi, hãy bao gồm dấu chấm hỏi (?) làm phần giữ chỗ cho cụm từ tìm kiếm. Hệ thống gọi query() bằng chuỗi lựa chọn là tham số selection và cụm từ tìm kiếm là phần tử đầu tiên trong mảng selectionArgs.

Ví dụ: dưới đây là cách bạn có thể tạo Thuộc tính android:searchSuggestSelection để tạo văn bản đầy đủ câu lệnh tìm kiếm:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:searchSuggestSelection="word MATCH ?">
</searchable>

Với cấu hình này, phương thức query() của bạn sẽ phân phối tham số selection làm "word MATCH ?" và selectionArgs làm truy vấn tìm kiếm. Khi bạn chuyển các thông số này đến một SQLite query() phương pháp, như các đối số tương ứng, chúng được tổng hợp có nghĩa là dấu chấm hỏi sẽ được thay thế bằng văn bản truy vấn. Nếu bạn nhận được các truy vấn đề xuất theo cách này và cần thêm ký tự đại diện vào truy vấn text, hãy thêm hoặc thêm tiền tố vào tham số selectionArgs vì giá trị này được đặt trong dấu ngoặc kép và được chèn vào vị trí dấu chấm hỏi.

Một thuộc tính khác trong ví dụ trước là android:searchSuggestIntentAction xác định thao tác theo ý định được gửi cùng với từng ý định khi người dùng chọn một đề xuất. Vấn đề này sẽ được thảo luận trong phần Khai báo ý định cho đề xuất.

Mẹo: Nếu bạn không muốn xác định mệnh đề lựa chọn trong android:searchSuggestSelection, nhưng bạn vẫn muốn nhận văn bản truy vấn trong tham số selectionArgs, hãy cung cấp giá trị không rỗng cho thuộc tính android:searchSuggestSelection. Thao tác này sẽ kích hoạt truy vấn truyền vào selectionArgs và bạn có thể bỏ qua thông số selection. Bằng cách này, bạn có thể xác định mệnh đề lựa chọn thực tế ở cấp thấp hơn để nhà cung cấp nội dung của bạn không phải xử lý.

Tạo bảng đề xuất

Khi bạn trả về các đề xuất cho hệ thống bằng Cursor, yêu cầu các cột cụ thể trong mỗi hàng. Bất kể bạn lưu trữ dữ liệu đề xuất của bạn trong cơ sở dữ liệu SQLite trên thiết bị, một cơ sở dữ liệu trên web máy chủ hoặc định dạng khác trên thiết bị hoặc web, hãy định dạng các đề xuất dưới dạng hàng trong bảng rồi trình bày chúng bằng một Cursor.

Lưu ý: Nếu cụm từ tìm kiếm được đề xuất không được lưu trữ trong bảng định dạng (chẳng hạn như bảng SQLite) bằng cách sử dụng các cột theo yêu cầu của hệ thống, sau đó bạn có thể tìm kiếm dữ liệu đề xuất để tìm kết quả phù hợp rồi định dạng chúng vào bảng cần thiết trong mỗi yêu cầu. Để thực hiện điều này, hãy tạo một MatrixCursor bằng cách sử dụng các tên cột bắt buộc, sau đó thêm hàng cho từng đề xuất bằng cách sử dụng addRow(Object[]) Trả lại sản phẩm cuối cùng từ query() của nhà cung cấp nội dung .

Hệ thống hiểu được một số cột, nhưng chỉ có 2 cột trong số đó là bắt buộc:

_ID: Mã nhận dạng hàng số nguyên duy nhất cho mỗi đề xuất. Hệ thống yêu cầu điều này để đưa ra đề xuất một cách ListView.
SUGGEST_COLUMN_TEXT_1: Chuỗi được biểu thị ở dạng đề xuất.

Tất cả các cột sau đây là không bắt buộc. Hầu hết sẽ được thảo luận kỹ hơn trong các phần sau.

SUGGEST_COLUMN_TEXT_2: Một chuỗi. Nếu Cursor của bạn bao gồm cột này, thì tất cả đề xuất được cung cấp ở định dạng hai dòng. Chuỗi trong cột này là được hiển thị dưới dạng dòng văn bản thứ hai, nhỏ hơn bên dưới đề xuất chính . Có thể để trống hoặc để trống để cho biết không có văn bản phụ.
SUGGEST_COLUMN_ICON_1: Một tài nguyên có thể vẽ, nội dung hoặc chuỗi URI tệp. Nếu Cursor bao gồm cột này, sau đó tất cả đề xuất đều được cung cấp ở định dạng biểu tượng và văn bản với biểu tượng có thể vẽ ở bên trái. Chiến dịch này có thể rỗng hoặc 0 để cho biết không có biểu tượng nào trong hàng này.
SUGGEST_COLUMN_ICON_2: Một tài nguyên có thể vẽ, nội dung hoặc chuỗi URI tệp. Nếu Cursor bao gồm cột này, sau đó tất cả đề xuất đều được cung cấp ở định dạng biểu tượng kết hợp văn bản với biểu tượng ở bên phải. Thông tin này có thể là rỗng hoặc 0 để cho biết không có biểu tượng nào trong hàng này.
SUGGEST_COLUMN_INTENT_ACTION: Chuỗi thao tác theo ý định. Nếu cột này tồn tại và chứa một giá trị ở hàng nhất định, hành động được xác định ở đây được sử dụng khi tạo ý định. Nếu phần tử này không được cung cấp, thao tác sẽ được thực hiện từ Trường android:searchSuggestIntentAction trong nội dung có thể tìm kiếm . Nếu thao tác của bạn giống nhau đối với tất cả nội dung đề xuất, thì sẽ có nhiều hiệu quả để chỉ định hành động bằng cách sử dụng android:searchSuggestIntentAction và bỏ qua cột này.
SUGGEST_COLUMN_INTENT_DATA: Một chuỗi URI dữ liệu. Nếu cột này tồn tại và chứa giá trị ở hàng, dữ liệu này được sử dụng khi hình thành ý định của đề xuất. Nếu phần tử không được cung cấp, dữ liệu sẽ được lấy từ Trường android:searchSuggestIntentData trong nội dung có thể tìm kiếm . Nếu không có nguồn nào được cung cấp, trường dữ liệu của ý định sẽ là rỗng. Nếu dữ liệu của bạn là giống nhau cho tất cả nội dung đề xuất hoặc có thể được mô tả bằng cách sử dụng một hằng số và một mã nhận dạng cụ thể, thì việc chỉ định đối số đó sẽ hiệu quả hơn sử dụng android:searchSuggestIntentData và bỏ qua .
SUGGEST_COLUMN_INTENT_DATA_ID: Chuỗi đường dẫn URI. Nếu cột này tồn tại và chứa giá trị ở hàng, rồi đến "/" và giá trị này sẽ được thêm vào trường dữ liệu trong ý định. Chỉ sử dụng thuộc tính này nếu trường dữ liệu được chỉ định bởi Thuộc tính android:searchSuggestIntentData trong thuộc tính có thể tìm kiếm đã được đặt thành một chuỗi cơ sở thích hợp.
SUGGEST_COLUMN_INTENT_EXTRA_DATA: Dữ liệu tuỳ ý. Nếu cột này tồn tại và chứa giá trị ở một hàng cho trước, đây là dữ liệu bổ sung được dùng khi hình thành ý định của đề xuất. Nếu không được cung cấp, trường dữ liệu bổ sung của ý định sẽ rỗng. Cột này cho phép sẽ cung cấp thêm dữ liệu được đưa vào dưới dạng thông tin bổ sung trong ý định EXTRA_DATA_KEY .
SUGGEST_COLUMN_QUERY: Nếu cột này tồn tại và phần tử này tồn tại ở hàng đã cho, thì đây là dữ liệu được sử dụng khi hình thành truy vấn của đề xuất, được đưa vào dưới dạng trong phần bổ sung của ý định QUERY . Đây là trường bắt buộc nếu hành động của đề xuất là ACTION_SEARCH, nhưng không bắt buộc.
SUGGEST_COLUMN_SHORTCUT_ID: Chỉ được dùng khi cung cấp gợi ý cho Hộp tìm kiếm nhanh. Cột này cho biết liệu đề xuất tìm kiếm có phải được lưu trữ dưới dạng lối tắt hay không và liệu có phải được xác thực hay không. Lối tắt thường được tạo khi người dùng nhấn vào một gợi ý từ Hộp tìm kiếm nhanh. Nếu thiếu, kết quả sẽ được lưu trữ dưới dạng một lối tắt và không bao giờ được làm mới. Nếu đặt thành SUGGEST_NEVER_MAKE_SHORTCUT, kết quả không được lưu trữ dưới dạng lối tắt. Nếu không, mã lối tắt sẽ được dùng để hãy kiểm tra lại để xem đề xuất cập nhật bằng cách sử dụng SUGGEST_URI_PATH_SHORTCUT.
SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING: Chỉ được dùng khi cung cấp gợi ý cho Hộp tìm kiếm nhanh. Cột này chỉ định một vòng quay phải được hiển thị thay vì biểu tượng từ SUGGEST_COLUMN_ICON_2 trong khi khẩu lệnh nhanh của đề xuất này là làm mới trong Hộp Tìm kiếm Nhanh.

Hầu hết các cột này sẽ được thảo luận thêm trong các phần sau.

Khai báo một ý định cho nội dung đề xuất

Khi người dùng chọn một đề xuất từ danh sách xuất hiện bên dưới hộp thoại tìm kiếm hoặc tiện ích tìm kiếm, hệ thống sẽ gửi một Intent tuỳ chỉnh đến hoạt động có thể tìm kiếm. Bạn phải xác định hành động và dữ liệu cho ý định.

Khai báo thao tác theo ý định

Thao tác theo ý định phổ biến nhất cho đề xuất tuỳ chỉnh là ACTION_VIEW, phù hợp khi bạn muốn mở nội dung nào đó, chẳng hạn như định nghĩa của một từ, thông tin liên hệ của một người hoặc một trang web. Tuy nhiên, thao tác theo ý định có thể là bất kỳ thao tác nào khác và mỗi thao tác có thể khác nhau .

Tuỳ thuộc vào việc bạn có muốn tất cả đề xuất sử dụng cùng một thao tác theo ý định hay không, bạn có thể xác định hành động theo 2 cách:

Sử dụng thuộc tính android:searchSuggestIntentAction của tệp cấu hình có thể tìm kiếm để xác định hành động cho tất cả các đề xuất, như như trong ví dụ sau:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW" >
</searchable>

Dùng cột SUGGEST_COLUMN_INTENT_ACTION để xác định cho từng đề xuất. Để thực hiện việc này, hãy thêm phương thức SUGGEST_COLUMN_INTENT_ACTION cột đến bảng đề xuất và đối với mỗi đề xuất, hãy đặt vào hành động để sử dụng, chẳng hạn như "android.intent.action.VIEW"

Bạn cũng có thể kết hợp hai kỹ thuật này. Ví dụ: bạn có thể đưa vào Thuộc tính android:searchSuggestIntentAction có thao tác sẽ được thực hiện được sử dụng với tất cả đề xuất theo mặc định, sau đó ghi đè hành động này cho một số bằng cách khai báo một hành động khác trong Cột SUGGEST_COLUMN_INTENT_ACTION. Nếu bạn không thêm giá trị vào cột SUGGEST_COLUMN_INTENT_ACTION, thì ý định mà bạn cung cấp trong thuộc tính android:searchSuggestIntentAction là đã sử dụng.

Lưu ý: Nếu bạn không bao gồm Thuộc tính android:searchSuggestIntentAction trong danh sách có thể tìm kiếm , thì bạn phải đưa một giá trị vào thuộc tính Cột SUGGEST_COLUMN_INTENT_ACTION cho mọi đề xuất, hoặc nếu không thì ý định không thành công.

Khai báo dữ liệu ý định

Khi người dùng chọn một đề xuất, hoạt động có thể tìm kiếm của bạn sẽ nhận được ý định bằng hành động mà bạn xác định—như được thảo luận trong phần trước – nhưng ý định cũng phải mang theo dữ liệu cho hoạt động của bạn để xác định đề xuất nào được chọn. Cụ thể, dữ liệu phải là dữ liệu duy nhất cho từng đề xuất, chẳng hạn như mã hàng cho đề xuất trong bảng SQLite. Khi nhận được ý định, bạn có thể truy xuất dữ liệu đính kèm bằng getData() hoặc getDataString()

Bạn có thể xác định dữ liệu đi kèm với ý định theo 2 cách:

Xác định dữ liệu cho từng đề xuất bên trong SUGGEST_COLUMN_INTENT_DATA cột trong bảng đề xuất.
Cung cấp tất cả thông tin dữ liệu cần thiết cho từng ý định trong nội dung đề xuất bảng bằng cách bao gồm cột SUGGEST_COLUMN_INTENT_DATA và sau đó điền dữ liệu duy nhất cho mỗi hàng. Dữ liệu từ cột này được đính kèm vào ý định chính xác như bạn xác định trong cột này. Bạn có thể sau đó truy xuất bằng getData() hoặc getDataString()

Mẹo: Thường thì việc dùng mã hàng của bảng làm ý định sẽ dễ dàng hơn vì dữ liệu này luôn là duy nhất. Cách dễ nhất để thực hiện việc này là sử dụng Tên cột SUGGEST_COLUMN_INTENT_DATA là bí danh của hàng Mã nhận dạng.
Phân mảnh URI dữ liệu thành hai phần: phần chung cho tất cả đề xuất và phần duy nhất cho mỗi đề xuất. Đặt các phần này vào Thuộc tính android:searchSuggestintentData của có thể tìm kiếm được và cột SUGGEST_COLUMN_INTENT_DATA_ID của bảng đề xuất tương ứng.
Ví dụ sau đây trình bày cách khai báo phần URI chung cho tất cả các đề xuất trong Thuộc tính android:searchSuggestIntentData của kết quả tìm kiếm được cấu hình:
```
  <?xml version="1.0" encoding="utf-8"?>
  <searchable xmlns:android="http://schemas.android.com/apk/res/android"
      android:label="@string/app_label"
      android:hint="@string/search_hint"
      android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
      android:searchSuggestIntentAction="android.intent.action.VIEW"
      android:searchSuggestIntentData="content://com.example/datatable" >
  </searchable>
  
```
Thêm đường dẫn cuối cùng cho mỗi đề xuất (phần riêng biệt) cột SUGGEST_COLUMN_INTENT_DATA_ID của đề xuất bảng. Khi người dùng chọn một đề xuất, hệ thống sẽ lấy chuỗi từ android:searchSuggestIntentData, thêm dấu gạch chéo (/), rồi thêm giá trị tương ứng từ SUGGEST_COLUMN_INTENT_DATA_ID để tạo một nội dung hoàn chỉnh URI. Sau đó, bạn có thể truy xuất Uri bằng getData()

Thêm dữ liệu khác

Nếu cần diễn đạt thêm thông tin về ý định của mình, bạn có thể thêm một cột trong bảng, chẳng hạn như SUGGEST_COLUMN_INTENT_EXTRA_DATA, có thể lưu trữ thông tin bổ sung về đề xuất. Dữ liệu được lưu trong cột này được đặt trong EXTRA_DATA_KEY thuộc gói bổ sung của ý định.

Xử lý ý định

Sau khi cung cấp cụm từ tìm kiếm được đề xuất tuỳ chỉnh dựa trên ý định tuỳ chỉnh, bạn cần hoạt động có thể tìm kiếm của bạn để xử lý các ý định này khi người dùng chọn một . Việc này ngoài việc xử lý ACTION_SEARCH ý định mà hoạt động có thể tìm kiếm của bạn đã thực hiện. Sau đây là ví dụ về cách bạn có thể xử lý các ý định trong lúc onCreate() gọi lại:

Kotlin

when(intent.action) {
    Intent.ACTION_SEARCH -> {
        // Handle the normal search query case.
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            doSearch(query)
        }
    }
    Intent.ACTION_VIEW -> {
        // Handle a suggestions click, because the suggestions all use ACTION_VIEW.
        showResult(intent.data)
    }
}

Java

Intent intent = getIntent();
if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
    // Handle the normal search query case.
    String query = intent.getStringExtra(SearchManager.QUERY);
    doSearch(query);
} else if (Intent.ACTION_VIEW.equals(intent.getAction())) {
    // Handle a suggestions click, because the suggestions all use ACTION_VIEW.
    Uri data = intent.getData();
    showResult(data);
}

Trong ví dụ này, thao tác theo ý định là ACTION_VIEW và dữ liệu chứa URI đầy đủ trỏ đến mục được đề xuất, như được tổng hợp bởi Chuỗi android:searchSuggestIntentData và Cột SUGGEST_COLUMN_INTENT_DATA_ID. Sau đó, URI chuyển đến cục bộ showResult() truy vấn trình cung cấp nội dung cho mục do URI chỉ định.

Lưu ý: Bạn không cần thêm bộ lọc ý định vào thiết bị Android tệp kê khai cho thao tác theo ý định mà bạn đã xác định bằng thuộc tính android:searchSuggestIntentAction hoặc SUGGEST_COLUMN_INTENT_ACTION. Hệ thống sẽ mở hoạt động có thể tìm kiếm theo tên để truyền đạt ý định của đề xuất, vì vậy hoạt động không cần khai báo hành động được chấp nhận.

Viết lại văn bản truy vấn

Theo mặc định, nếu người dùng di chuyển qua danh sách đề xuất bằng cách sử dụng các điều khiển hướng, chẳng hạn như bi xoay hoặc D-pad, văn bản truy vấn không cập nhật. Tuy nhiên, bạn có thể tạm thời viết lại văn bản truy vấn của người dùng khi văn bản đó xuất hiện vào hộp văn bản có truy vấn khớp với đề xuất được lấy tiêu điểm. Điều này cho phép người dùng thấy cụm từ tìm kiếm đang được đề xuất, đồng thời họ có thể chọn hộp tìm kiếm và chỉnh sửa truy vấn đó trước khi gửi dưới dạng một lượt tìm kiếm.

Bạn có thể viết lại nội dung truy vấn theo các cách sau:

Thêm thuộc tính android:searchMode vào nội dung có thể tìm kiếm có giá trị "queryRewriteFromText". Trong phần này trường hợp, nội dung từ SUGGEST_COLUMN_TEXT_1 của đề xuất được dùng để viết lại văn bản truy vấn.
Thêm thuộc tính android:searchMode vào tính năng tìm kiếm được\ có giá trị "queryRewriteFromData". Trong phần này trường hợp, nội dung từ đề xuất Cột SUGGEST_COLUMN_INTENT_DATA được dùng để ghi lại truy vấn . Chỉ sử dụng loại này với URI hoặc các định dạng dữ liệu khác được dự định là hiển thị cho người dùng, chẳng hạn như URL HTTP. Không sử dụng giao thức URI nội bộ để viết lại truy vấn theo cách này.
Cung cấp một chuỗi văn bản truy vấn duy nhất trong SUGGEST_COLUMN_QUERY cột trong bảng đề xuất. Nếu trường hợp này đang hiển thị và chứa giá trị cho đề xuất hiện tại, thì được dùng để viết lại văn bản truy vấn và ghi đè văn bản trước đó thực tế.

Hiện cụm từ tìm kiếm được đề xuất trong Hộp tìm kiếm nhanh

Khi bạn định cấu hình ứng dụng để cung cấp các đề xuất tìm kiếm tuỳ chỉnh, khả dụng cho Hộp Tìm kiếm Nhanh có thể truy cập trên toàn cầu cũng dễ dàng như sửa đổi cấu hình có thể tìm kiếm của bạn để thêm android:includeInGlobalSearch có giá trị "true"

Trường hợp duy nhất mà bạn cần thực hiện thêm công việc là khi nội dung của mình sẽ yêu cầu quyền đọc. Trong trường hợp đó, bạn cần thêm Phần tử <path-permission> để trình cung cấp cấp quyền truy cập nhanh Quyền đọc Hộp tìm kiếm đối với nhà cung cấp nội dung của bạn, như được minh hoạ trong ví dụ:

<provider android:name="MySuggestionProvider"
          android:authorities="com.example.MyCustomSuggestionProvider"
          android:readPermission="com.example.provider.READ_MY_DATA"
          android:writePermission="com.example.provider.WRITE_MY_DATA">
  <path-permission android:pathPrefix="/search_suggest_query"
                   android:readPermission="android.permission.GLOBAL_SEARCH" />
</provider>

Trong ví dụ này, trình cung cấp hạn chế quyền đọc và ghi đối với nội dung. Phần tử <path-permission> sẽ sửa đổi giới hạn bằng cách cấp quyền đọc nội dung bên trong "/search_suggest_query" tiền tố đường dẫn khi quyền "android.permission.GLOBAL_SEARCH" đã tồn tại. Thao tác này sẽ cấp quyền truy cập vào Hộp Tìm kiếm Nhanh để có thể truy vấn nội dung của bạn để có các đề xuất.

Nếu trình cung cấp nội dung của bạn không thực thi quyền đọc, thì tính năng Tìm kiếm nhanh Box sẽ đọc thông báo theo mặc định.

Bật tính năng đề xuất trên thiết bị

Theo mặc định, các ứng dụng không được bật để cung cấp đề xuất trong Hộp tìm kiếm nhanh, ngay cả khi chúng được định cấu hình để làm như vậy. Người dùng chọn có đưa vào hoặc không đề xuất từ ứng dụng của bạn trong Hộp tìm kiếm nhanh bằng cách mở Có thể tìm kiếm được mục—nằm trong Cài đặt > Tìm kiếm—và bật ứng dụng dưới dạng một mục có thể tìm kiếm.

Mỗi ứng dụng khả dụng với Hộp Tìm kiếm Nhanh có một mục nhập trong Trang cài đặt Mục có thể tìm kiếm. Mục nhập chứa tên của ứng dụng và một đoạn mô tả ngắn về nội dung có thể tìm kiếm được từ ứng dụng và khiến có sẵn cho các đề xuất trong Hộp Tìm kiếm Nhanh. Để xác định văn bản nội dung mô tả cho ứng dụng có thể tìm kiếm này, hãy thêm android:searchSettingsDescription vào cấu hình có thể tìm kiếm của bạn, như được hiển thị trong phần ví dụ:

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

Tạo chuỗi cho android:searchSettingsDescription thật súc tích càng tốt và nêu rõ nội dung có thể tìm kiếm được. Ví dụ: "Nghệ sĩ, đĩa nhạc, bản nhạc" đối với ứng dụng nhạc hoặc "Ghi chú đã lưu" cho ứng dụng sổ tay. Việc cung cấp mô tả này rất quan trọng để người dùng biết loại được cung cấp. Luôn bao gồm thuộc tính này khi android:includeInGlobalSearch là đúng.

Vì người dùng phải truy cập trình đơn cài đặt để bật tính năng đề xuất tìm kiếm cho ứng dụng của bạn, nếu tìm kiếm là một khía cạnh quan trọng của ứng dụng, hãy xem xét cách truyền tải thông tin đó đến người dùng. Ví dụ: bạn có thể cung cấp ghi chú vào lần đầu tiên một người dùng chạy ứng dụng giải thích cách bật tính năng đề xuất tìm kiếm cho mục Quick Hộp tìm kiếm.

Quản lý lối tắt đề xuất Hộp tìm kiếm nhanh

Các đề xuất mà người dùng chọn từ Hộp tìm kiếm nhanh có thể được tự động thêm vào được tạo thành lối tắt. Đây là các đề xuất mà hệ thống sao chép từ trình cung cấp nội dung để có thể nhanh chóng truy cập đề xuất mà không cần truy vấn lại trình cung cấp nội dung của bạn.

Theo mặc định, tính năng này được bật cho tất cả các đề xuất do tính năng Tìm kiếm nhanh truy xuất Box, nhưng nếu dữ liệu đề xuất của bạn thay đổi theo thời gian, thì bạn có thể yêu cầu các lối tắt sẽ được làm mới. Ví dụ: nếu đề xuất của bạn đề cập đến động của bạn, chẳng hạn như trạng thái hiện diện của một địa chỉ liên hệ, sau đó yêu cầu đề xuất đó các lối tắt sẽ được làm mới khi hiển thị cho người dùng. Để thực hiện việc này, hãy đưa vào SUGGEST_COLUMN_SHORTCUT_ID trong bảng đề xuất. Bạn có thể sử dụng cột này để định cấu hình hành vi của phím tắt cho mỗi đề xuất trong một trong các cách sau:

Làm cho Hộp tìm kiếm nhanh truy vấn lại nhà cung cấp nội dung của bạn để có của lối tắt đề xuất.

Cung cấp giá trị trong cột SUGGEST_COLUMN_SHORTCUT_ID cho đề xuất được truy vấn lại để nhận được phiên bản mới mỗi khi lối tắt sẽ được hiển thị. Phím tắt sẽ nhanh chóng hiển thị cùng với bất kỳ dữ liệu nào quan trọng nhất khả dụng gần đây cho đến khi truy vấn làm mới trả về, tại thời điểm đó được làm mới với thông tin mới. Truy vấn làm mới là được gửi đến nhà cung cấp nội dung của bạn bằng đường dẫn URI là SUGGEST_URI_PATH_SHORTCUT—thay vì SUGGEST_URI_PATH_QUERY

Đặt Cursor bạn trả về chứa một đề xuất bằng cách sử dụng phương thức giống với cột đề xuất ban đầu hoặc để trống, cho biết rằng lối tắt không còn hợp lệ. Trong trường hợp đó, đề xuất sẽ biến mất và lối tắt bị loại bỏ.

Nếu nội dung đề xuất đề cập đến dữ liệu có thể mất nhiều thời gian hơn để làm mới, chẳng hạn như làm mới dựa trên mạng, bạn cũng có thể thêm SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING cột vào bảng đề xuất có giá trị true để hiển thị vòng quay tiến trình cho biểu tượng bên phải cho đến khi quá trình làm mới hoàn tất. Bất kỳ giá trị nào khác true không hiện vòng quay tiến trình.
Không cho sao chép đề xuất vào một lối tắt.

Cung cấp giá trị SUGGEST_NEVER_MAKE_SHORTCUT trong phần tử Cột SUGGEST_COLUMN_SHORTCUT_ID. Trong trường hợp này, đề xuất không bao giờ được sao chép vào lối tắt. Điều này chỉ cần thiết nếu bạn hoàn toàn không muốn đề xuất đã sao chép trước đó xuất hiện. Nếu bạn cung cấp giá trị bình thường cho cột, sau đó phím tắt đề xuất chỉ xuất hiện cho đến khi truy vấn làm mới được trả về.
Áp dụng hành vi mặc định của phím tắt.

Để trống SUGGEST_COLUMN_SHORTCUT_ID cho mỗi tùy chọn là gợi ý không thay đổi và có thể được lưu dưới dạng lối tắt.

Nếu không có đề xuất nào thay đổi, thì bạn không cần SUGGEST_COLUMN_SHORTCUT_ID cột.

Giới thiệu về xếp hạng đề xuất của Hộp tìm kiếm nhanh

Khi bạn đưa đề xuất tìm kiếm của ứng dụng vào Hộp tìm kiếm nhanh, xếp hạng Hộp tìm kiếm nhanh xác định cách các đề xuất được hiển thị cho cho một truy vấn cụ thể. Điều này có thể tuỳ thuộc vào số lượng ứng dụng khác có kết quả cho truy vấn đó và tần suất người dùng chọn kết quả của bạn so với những kết quả từ các ứng dụng khác. Không có gì đảm bảo về việc nội dung bạn đề xuất sẽ hữu ích như thế nào hoặc liệu các đề xuất của ứng dụng có hiển thị cho một truy vấn nhất định hay không. Trong nói chung, việc cung cấp kết quả chất lượng sẽ làm tăng khả năng ứng dụng của bạn các đề xuất được đưa ra ở vị trí nổi bật và các ứng dụng cung cấp các đề xuất có chất lượng thấp có nhiều khả năng bị xếp hạng thấp hơn hoặc không được hiển thị.