การกำหนดค่าการค้นหา

เพื่อใช้การค้นหาด้วยความช่วยเหลือจากระบบ Android ซึ่งก็คือการให้บริการการค้นหา คำค้นหาเกี่ยวกับกิจกรรมและให้คำแนะนำการค้นหา แอปพลิเคชันของคุณจะต้องให้บริการการค้นหา การกำหนดค่าในรูปแบบของไฟล์ XML

หน้านี้อธิบายไฟล์การกำหนดค่าการค้นหาในแง่ของไวยากรณ์และการใช้งาน สำหรับข้อมูลเพิ่มเติม ข้อมูลเกี่ยวกับวิธีใช้ฟีเจอร์การค้นหาสำหรับแอปพลิเคชันของคุณ โปรดดู สร้างอินเทอร์เฟซการค้นหา

ตำแหน่งที่ตั้งไฟล์:

res/xml/filename.xml

Android จะใช้ชื่อไฟล์เป็นรหัสทรัพยากร

ไวยากรณ์:

<?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>

องค์ประกอบ:

<searchable>

กำหนดค่าการค้นหาทั้งหมดที่ระบบ Android ใช้เพื่อให้บริการการค้นหาแบบมีตัวช่วย

แอตทริบิวต์

android:label

ทรัพยากรสตริง (ต้องระบุ) ชื่อแอปพลิเคชันของคุณ ซึ่งต้องเหมือนกับ ชื่อที่ใช้กับแอตทริบิวต์ android:label ของ <activity> หรือ <application> ของไฟล์ Manifest ป้ายกำกับนี้จะปรากฏต่อผู้ใช้เมื่อคุณตั้งค่า android:includeInGlobalSearch ถึง "true" ซึ่งในกรณีนี้จะใช้ป้ายกำกับนี้ เพื่อระบุว่าแอปพลิเคชันของคุณเป็นรายการที่ค้นหาได้ในการตั้งค่าการค้นหาของระบบ

android:hint

ทรัพยากรสตริง (แนะนำ) ข้อความที่จะแสดงในช่องข้อความเมื่อ ไม่ได้ป้อนข้อความ ให้คำแนะนำแก่ผู้ใช้ว่าเนื้อหาที่สามารถค้นหาได้ เพื่อความสอดคล้อง ร่วมกับแอปพลิเคชัน Android อื่นๆ ให้จัดรูปแบบสตริง android:hint เป็น "Search <content-or-product>" เช่น "ค้นหาเพลงและศิลปิน" หรือ "ค้นหาใน YouTube"

android:searchMode

คีย์เวิร์ด ตั้งค่าโหมดเพิ่มเติมที่ควบคุมการนําเสนอการค้นหา พร้อมใช้งาน โหมดต่างๆ จะกำหนดแนวทางการเขียนข้อความค้นหาใหม่เมื่อได้รับคำแนะนำที่กำหนดเอง โฟกัส ระบบยอมรับค่าโหมดต่อไปนี้

ค่า	คำอธิบาย
"queryRewriteFromData"	ใช้ค่าจากแอตทริบิวต์ SUGGEST_COLUMN_INTENT_DATA เพื่อเขียนข้อความข้อความค้นหาใหม่ โดยต้องใช้เมื่อค่าใน SUGGEST_COLUMN_INTENT_DATA เหมาะสำหรับการตรวจสอบและแก้ไขของผู้ใช้ เช่น HTTP URI
"queryRewriteFromText"	ใช้ค่าจากแอตทริบิวต์ SUGGEST_COLUMN_TEXT_1 เพื่อเขียนข้อความค้นหาใหม่

สำหรับข้อมูลเพิ่มเติม โปรดดูเอกสารประกอบเกี่ยวกับการเขียนข้อความคำค้นหาใหม่ใน เพิ่มการแนะนำการค้นหาที่กำหนดเอง

android:searchButtonText

ทรัพยากรสตริง ข้อความที่จะแสดงในปุ่มที่ดำเนินการค้นหา โดย ปุ่มนี้จะแสดงไอคอนค้นหา (แว่นขยาย) ซึ่งเหมาะสำหรับ ให้เป็นสากล ดังนั้นอย่าใช้แอตทริบิวต์นี้เพื่อเปลี่ยนปุ่ม เว้นแต่ลักษณะการทำงานจะเป็น บางอย่างนอกเหนือจากการค้นหา เช่น คำขอ URL ในเว็บเบราว์เซอร์

android:inputType

คีย์เวิร์ด กำหนดประเภทของวิธีการป้อนข้อมูลที่จะใช้ เช่น ประเภทของซอฟต์แวร์ แป้นพิมพ์ สำหรับการค้นหาส่วนใหญ่ที่ต้องการข้อความรูปแบบอิสระ คุณไม่จำเป็นต้องใช้แอตทริบิวต์นี้ ดูรายการของ inputType ค่าที่เหมาะสมสำหรับแอตทริบิวต์นี้

android:imeOptions

คีย์เวิร์ด ระบุตัวเลือกเพิ่มเติมสำหรับวิธีการป้อนข้อมูล สำหรับการค้นหาส่วนใหญ่ ใน ข้อความรูปแบบอิสระใดที่ระบบคาดว่าจะเป็น คุณก็ไม่จําเป็นต้องใช้แอตทริบิวต์นี้ IME เริ่มต้นคือ actionSearch ซึ่งแสดง "การค้นหา" แทนปุ่มขึ้นบรรทัดใหม่ แป้นพิมพ์เสมือน โปรดดู imeOptions เพื่อดูรายการค่าที่เหมาะสมสำหรับแอตทริบิวต์นี้

แอตทริบิวต์คำแนะนำการค้นหา

หากคุณกำหนดผู้ให้บริการเนื้อหาเพื่อสร้างคำแนะนำการค้นหา คุณจะต้องระบุ แอตทริบิวต์เพิ่มเติมที่กำหนดค่าการสื่อสารกับผู้ให้บริการเนื้อหา เมื่อให้บริการการค้นหา คุณต้องมีแอตทริบิวต์ <searchable> ต่อไปนี้

android:searchSuggestAuthority

สตริง (ต้องระบุเพื่อให้การแนะนำการค้นหา) ค่านี้ต้องตรงกับแอตทริบิวต์ สตริงหน่วยงานที่ระบุใน android:authorities ขององค์ประกอบ <provider> ของไฟล์ Manifest ของ Android

android:searchSuggestPath

สตริง ระบบจะใช้เส้นทางนี้เป็นส่วนหนึ่งของคำแนะนำ คำค้นหา Uri หลังคำนำหน้าและ และก่อนหน้าเส้นทางการแนะนำมาตรฐาน โดยต้องระบุเฉพาะเมื่อคุณมี ผู้ให้บริการเนื้อหารายเดียวที่ออกคำแนะนำประเภทต่างๆ เช่น ประเภทข้อมูล และคุณต้องหาวิธีแยกแยะข้อความค้นหาคำแนะนำที่คุณได้รับ ให้พวกเขา

android:searchSuggestSelection

สตริง ค่านี้จะส่งผ่านไปยัง ฟังก์ชันการค้นหาเป็นพารามิเตอร์ selection โดยทั่วไปจะเป็นประโยค WHERE สำหรับฐานข้อมูลของคุณ และต้องมีเครื่องหมายคำถามตัวเดียวเป็นตัวยึดตำแหน่งสำหรับ สตริงการค้นหาจริงที่ผู้ใช้ป้อน เช่น "query=?" อย่างไรก็ตาม คุณยังสามารถใช้ค่าที่ไม่ใช่ค่าว่างเพื่อทริกเกอร์การส่งข้อความโดยใช้เงื่อนไข selectionArgs แล้วไม่สนใจพารามิเตอร์ selection)

android:searchSuggestIntentAction

สตริง การดำเนินการผ่าน Intent เริ่มต้นที่จะใช้เมื่อผู้ใช้ แตะการแนะนำการค้นหาที่กำหนดเอง เช่น "android.intent.action.VIEW" หากคำแนะนำที่เลือกไม่ได้ลบล้างค่านี้โดยใช้พารามิเตอร์ SUGGEST_COLUMN_INTENT_ACTION ค่าจะอยู่ในช่องการดำเนินการของ Intentเมื่อผู้ใช้แตะ คำแนะนำ

android:searchSuggestIntentData

สตริง ข้อมูล Intent เริ่มต้นที่จะใช้เมื่อผู้ใช้ แตะที่คำแนะนำการค้นหาที่กำหนดเอง หากคำแนะนำที่เลือกไม่ได้ลบล้างให้ทำดังนี้ SUGGEST_COLUMN_INTENT_DATA - ค่านี้จะอยู่ในช่องข้อมูลของฟิลด์ Intentเมื่อผู้ใช้แตะ คำแนะนำ

android:searchSuggestThreshold

จำนวนเต็ม จำนวนอักขระต่ำสุดที่ต้องใช้เพื่อ เรียกใช้การค้นหาคำแนะนำ ซึ่งเป็นการรับประกันว่าระบบจะไม่ค้นหา ผู้ให้บริการเนื้อหาสำหรับทุกสิ่งที่สั้นกว่าเกณฑ์ ค่าเริ่มต้นคือ 0

สำหรับข้อมูลเพิ่มเติมเกี่ยวกับแอตทริบิวต์ข้างต้นสำหรับการแนะนำการค้นหา โปรดดูเอกสารประกอบ สำหรับการเพิ่มการแนะนำการค้นหาที่กำหนดเอง และ การเพิ่มคำแนะนำที่กำหนดเอง

แอตทริบิวต์ของช่อง Quick Search

หากต้องการทำให้คำแนะนำการค้นหาที่กำหนดเองของคุณพร้อมใช้งานในช่อง Quick Search คุณต้องใช้ แอตทริบิวต์ <searchable> ต่อไปนี้

android:includeInGlobalSearch

บูลีน (ต้องระบุเพื่อให้การแนะนำการค้นหาในมิติข้อมูล ช่องค้นหาแบบรวดเร็ว) ตั้งค่าเป็น "true" หากต้องการให้ระบบแสดงคำแนะนำ ที่อยู่ในช่อง Quick Search ที่เข้าถึงได้ทั่วโลก ผู้ใช้ต้อง เปิดใช้งานแอปพลิเคชันของคุณเป็นรายการที่ค้นหาได้ในการตั้งค่าการค้นหาระบบก่อนที่จะ คำแนะนำของคุณจะปรากฏขึ้นในช่อง Quick Search

android:searchSettingsDescription

ทรัพยากรสตริง ให้คำอธิบายสั้นๆ เกี่ยวกับการแนะนำการค้นหาที่ ที่คุณระบุในช่อง Quick Search ซึ่งจะปรากฏในรายการที่ค้นหาได้สำหรับ แอปพลิเคชัน คำอธิบายของคุณต้องอธิบายถึงเนื้อหาที่ค้นหาได้แบบกระชับ สำหรับ เช่น "ศิลปิน อัลบั้ม และแทร็ก" สำหรับแอปพลิเคชันเพลง หรือ "โน้ตที่บันทึกไว้" สำหรับ แอปพลิเคชัน Notepad

android:queryAfterZeroResults

บูลีน ตั้งค่าเป็น "true" ถ้าต้องการให้ผู้ให้บริการเนื้อหา เรียกใช้สำหรับชุดย่อยของคำค้นหาที่ก่อนหน้านี้แสดงผลลัพธ์เป็น 0 รายการ ตัวอย่างเช่น หาก ผู้ให้บริการเนื้อหาของคุณแสดงผลลัพธ์เป็นศูนย์สำหรับ "bo" แต่ต้องใช้ข้อความค้นหานี้เพื่อค้นหา "bob" ถ้า ตั้งค่าเป็น "false" ระบบจะละเว้นซูเปอร์เซ็ตในเซสชันเดียว นั่นคือ "bob" จะไม่เรียกการค้นหาใหม่ ระยะเวลานี้จำกัดไว้ตลอดอายุการใช้งานของกล่องโต้ตอบการค้นหา หรือตลอดอายุของ กิจกรรมเมื่อใช้วิดเจ็ต Search เมื่อกล่องโต้ตอบหรือกิจกรรมการค้นหาเปิดขึ้นอีกครั้ง "bo" สอบถามผู้ให้บริการเนื้อหาของคุณอีกครั้ง ค่าเริ่มต้นคือ false

แอตทริบิวต์ของการค้นหาด้วยเสียง

หากต้องการเปิดใช้การค้นหาด้วยเสียง คุณต้องมีบางอย่าง แอตทริบิวต์ <searchable> ต่อไปนี้

android:voiceSearchMode

คีย์เวิร์ด (ต้องระบุเพื่อใช้ความสามารถในการค้นหาด้วยเสียง) เปิดใช้การค้นหาด้วยเสียงด้วยโหมดเฉพาะสำหรับค้นหาด้วยเสียง อุปกรณ์อาจไม่ได้ให้บริการค้นหาด้วยเสียง ซึ่งในกรณีนี้การตั้งค่าสถานะเหล่านี้ จะไม่มีผล ระบบยอมรับค่าโหมดต่อไปนี้

ค่า	คำอธิบาย
"showVoiceSearchButton"	แสดงปุ่มค้นหาด้วยเสียง หากอุปกรณ์สามารถค้นหาด้วยเสียงได้ หากตั้งค่าไว้ ก็ต้องตั้งค่า "launchWebSearch" หรือ "launchRecognizer" ด้วย คั่นด้วยอักขระไปป์ (|)
"launchWebSearch"	ปุ่มค้นหาด้วยเสียงจะพาผู้ใช้โดยตรง ในกิจกรรมค้นหาด้วยเสียงในตัว แอปพลิเคชันส่วนใหญ่ไม่ใช้แฟล็กนี้ เนื่องจาก ระบบจะนําผู้ใช้ออกจากกิจกรรมที่เรียกใช้การค้นหา
"launchRecognizer"	ใช้ปุ่มค้นหาด้วยเสียง ไปยังกิจกรรมการบันทึกเสียงในแอปโดยตรง กิจกรรมนี้ แจ้งให้ผู้ใช้พูด ถอดเสียงข้อความที่พูด และส่งต่อผลลัพธ์ ข้อความค้นหาไปยังกิจกรรมที่ค้นหาได้ เช่นเดียวกับที่ผู้ใช้พิมพ์ข้อความลงใน UI การค้นหา แล้วแตะปุ่มค้นหา

android:voiceLanguageModel

คีย์เวิร์ด โมเดลภาษาที่ ต้องใช้โดยระบบการจดจำเสียง ระบบยอมรับค่าต่อไปนี้

ค่า	คำอธิบาย
"free_form"	ใช้การจดจำคำพูดรูปแบบอิสระในการพิมพ์ตามคำบอก หลักๆ แล้ว ที่ปรับให้เหมาะสำหรับภาษาอังกฤษ โดยตัวเลือกนี้คือค่าเริ่มต้น
"web_search"	ใช้การจดจำข้อความค้นหาบนเว็บสำหรับวลีที่สั้นลงและคล้ายการค้นหา นี่คือ มีให้บริการในภาษามากกว่า "free_form"

โปรดดู EXTRA_LANGUAGE_MODELสำหรับข้อมูลเพิ่มเติม

android:voicePromptText

ทรัพยากรสตริง ข้อความเพิ่มเติมที่จะแสดงในกล่องโต้ตอบการป้อนข้อมูลด้วยเสียง

android:voiceLanguage

สตริง ภาษาพูดที่ควรจะเป็น ซึ่งแสดงเป็นค่าสตริงของ ค่าคงที่ใน Locale เช่น "de"สำหรับเยอรมันหรือ"fr"สำหรับฝรั่งเศส โดยต้องใช้เฉพาะในกรณีที่เป็นคนละรายการกัน จากค่าปัจจุบันที่ Locale.getDefault()

android:voiceMaxResults

จำนวนเต็ม ตั้งค่าจำนวนผลลัพธ์สูงสุดที่จะแสดง รวมถึงช่อง "ดีที่สุด" ซึ่งมักจะระบุเป็น ACTION_SEARCH คำค้นหาหลักของ Intent ต้องมีจำนวน 1 ขึ้นไป ใช้ EXTRA_RESULTS เพื่อให้ได้ผลลัพธ์จากความตั้งใจ หากไม่ระบุ เครื่องมือจดจำจะเลือกจำนวนผลลัพธ์ที่จะแสดง

<actionkey>

กำหนดคีย์และลักษณะการทำงานของอุปกรณ์สำหรับการดำเนินการค้นหา การดำเนินการค้นหาจะระบุข้อเสนอพิเศษ พฤติกรรมเมื่อแตะปุ่มบนอุปกรณ์ โดยอิงตามการค้นหาปัจจุบันหรือที่โฟกัสอยู่ แนะนำ ตัวอย่างเช่น แอปพลิเคชัน Contacts จะมีการดำเนินการค้นหาเพื่อเริ่มต้นโทรศัพท์ โทรไปยังคำแนะนำรายชื่อติดต่อที่โฟกัสอยู่ในปัจจุบันเมื่อแตะปุ่ม "โทร"

แป้นดำเนินการบางแป้นจะใช้ไม่ได้ในอุปกรณ์บางเครื่อง และคีย์บางรายการจะลบล้างไม่ได้ในส่วนนี้ ตัวอย่างเช่น "หน้าแรก" ไม่สามารถลบล้างคีย์และต้องกลับไปที่หน้าแรกเสมอ บนหน้าจอ นอกจากนี้ โปรดอย่ากำหนดแป้นดำเนินการสำหรับแป้นใดแป้นหนึ่งที่จำเป็นต้องใช้ในการพิมพ์คำค้นหา คำถาม การดำเนินการนี้จะจำกัดปุ่มดำเนินการที่ใช้ได้และสมเหตุสมผลไว้สำหรับปุ่มโทรและเมนู

หมายเหตุ: โดยทั่วไปแล้วคีย์การดำเนินการจะค้นพบไม่ได้ ดังนั้นอย่าระบุเป็นผู้ใช้หลัก

คุณต้องกำหนด android:keycode เพื่อกำหนดคีย์และอย่างน้อยหนึ่ง และอีก 3 รายการเพื่อกำหนดการดำเนินการค้นหา

แอตทริบิวต์

android:keycode

สตริง (ต้องระบุ) รหัสคีย์จาก KeyEvent ที่แสดงถึง แป้นดำเนินการที่ต้องการตอบสนอง เช่น "KEYCODE_CALL" ช่วงเวลานี้ จะเพิ่มลงใน ACTION_SEARCH ผ่านไปยังกิจกรรมที่ค้นหาได้ หากต้องการตรวจสอบโค้ดคีย์ ให้ใช้ getIntExtra(SearchManager.ACTION_KEY) คีย์บางตัวอาจใช้ไม่ได้กับการทำงานการค้นหา เพราะหลายๆ คีย์ก็ใช้สำหรับการพิมพ์ การนำทาง หรือฟังก์ชันของระบบ

android:queryActionMsg

สตริง ข้อความการทำงานที่จะส่งเมื่อกดแป้นการทำงานขณะ ผู้ใช้กำลังป้อนข้อความค้นหา โดยมีการเพิ่ม ACTION_SEARCH ที่ระบบส่งไปยังกิจกรรมที่ค้นหาได้ของคุณ หากต้องการตรวจสอบสตริง ให้ใช้ getStringExtra(SearchManager.ACTION_MSG)

android:suggestActionMsg

สตริง ข้อความการทำงานที่จะส่งเมื่อกดแป้นการทำงานขณะ คำแนะนำกำลังโฟกัส ซึ่งจะเพิ่มลงใน Intent ที่ระบบส่งไปยัง กิจกรรมที่ค้นหาได้ โดยใช้การดำเนินการที่คุณระบุสำหรับคำแนะนำ หากต้องการตรวจสอบ สตริง, ใช้ getStringExtra(SearchManager.ACTION_MSG) โดยจะใช้เฉพาะในกรณีที่คำแนะนำทั้งหมดรองรับคีย์การดำเนินการนี้เท่านั้น หากไม่ใช่ทั้งหมด คำแนะนำจะจัดการคีย์การดำเนินการเดียวกันได้ คุณจึงต้องใช้แป้นต่อไปนี้แทน android:suggestActionMsgColumn

android:suggestActionMsgColumn

สตริง ชื่อของคอลัมน์ในผู้ให้บริการเนื้อหาที่กำหนด ข้อความดำเนินการสำหรับคีย์การดำเนินการนี้ ซึ่งจะส่งหากผู้ใช้กดแป้นดำเนินการ ขณะที่กำลังโฟกัสกับคำแนะนำ แอตทริบิวต์นี้ช่วยให้คุณควบคุมคีย์การดำเนินการบน ที่แนะนำแต่ละรายการได้ เนื่องจากแทนที่จะใช้ แอตทริบิวต์ android:suggestActionMsg เพื่อกำหนดข้อความการดำเนินการสำหรับทุกคน แต่ละรายการในผู้ให้บริการเนื้อหาจะแสดงข้อความการดำเนินการของตนเอง

ก่อนอื่น คุณต้องกำหนดคอลัมน์ในผู้ให้บริการเนื้อหาสำหรับคำแนะนำแต่ละรายการ ข้อความการดำเนินการ ให้ระบุชื่อคอลัมน์นั้นในแอตทริบิวต์นี้ ระบบ ดูเคอร์เซอร์คำแนะนำโดยใช้สตริงที่ให้ไว้ที่นี่เพื่อเลือกการดำเนินการ ข้อความ แล้วเลือกสตริงข้อความการดำเนินการจากเคอร์เซอร์ สตริงนั้นจะ ลงใน Intent ที่ระบบส่งผ่านไปยังกิจกรรมที่ค้นหาได้ โดยใช้การดำเนินการที่คุณ กำหนดสำหรับคำแนะนำ หากต้องการตรวจสอบสตริง ให้ใช้ getStringExtra(SearchManager.ACTION_MSG) หากไม่มีข้อมูลสำหรับคำแนะนำที่เลือก ระบบจะไม่สนใจคีย์การดำเนินการ

ตัวอย่าง:

ไฟล์ XML ที่บันทึกไว้ที่ 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>