Để 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:
- 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 đặtandroid: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ị trongSUGGEST_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. XemimeOptions
để 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ínhSUGGEST_COLUMN_INTENT_ACTION
thì giá trị này sẽ được đặt vào trường hành độngIntent
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ủaIntent
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ụngEXTRA_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àoACTION_SEARCH
được chuyển đến hoạt động có thể tìm kiếm. Để kiểm tra mã khoá, hãy sử dụnggetIntExtra(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ụnggetStringExtra(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ínhandroid: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>
res/xml/filename.xml