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

ลองใช้ Compose

Jetpack Compose เป็นชุดเครื่องมือ UI ที่แนะนำสำหรับ Android ดูวิธีเพิ่มฟังก์ชันการค้นหาใน Compose

แถบค้นหา →

หากต้องการใช้การค้นหาโดยรับความช่วยเหลือจากระบบ 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 เป็น "ค้นหา <เนื้อหาหรือผลิตภัณฑ์>" เช่น "ค้นหาเพลงและศิลปิน" หรือ "ค้นหาใน YouTube"

android:searchMode

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

ค่านิยม	คำอธิบาย
"queryRewriteFromData"	ใช้ค่าจากคอลัมน์ SUGGEST_COLUMN_INTENT_DATA เพื่อเขียนข้อความ bquery ใหม่ ต้องใช้ในกรณีที่ค่าใน SUGGEST_COLUMN_INTENT_DATA เหมาะสมสำหรับการตรวจสอบและแก้ไขของผู้ใช้เท่านั้น เช่น URI ของ HTTP
"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 หลังจากคำนำหน้าและ Authority และก่อนเส้นทางคำแนะนำมาตรฐาน คุณจะต้องระบุพารามิเตอร์นี้ก็ต่อเมื่อมีผู้ให้บริการเนื้อหารายเดียวที่ออกคำแนะนำประเภทต่างๆ เช่น สำหรับข้อมูลประเภทต่างๆ และคุณต้องการวิธีแยกความแตกต่างของคำค้นหาคำแนะนำเมื่อได้รับคำค้นหาเหล่านั้น

android:searchSuggestSelection

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

android:searchSuggestIntentAction

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

android:searchSuggestIntentData

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

android:searchSuggestThreshold

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

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

แอตทริบิวต์ของช่องค้นหาแบบรวดเร็ว

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

android:includeInGlobalSearch

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

android:searchSettingsDescription

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

android:queryAfterZeroResults

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

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

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

android:voiceSearchMode

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

ค่านิยม	คำอธิบาย
"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 คำค้นหาหลักของเจตนาเสมอ ต้องเป็น 1 ขึ้นไป ใช้ EXTRA_RESULTS เพื่อรับผลลัพธ์จาก Intent หากไม่ได้ระบุไว้ ตัวจดจำจะเลือกจำนวนผลลัพธ์ที่จะแสดง

<actionkey>

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

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

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

แอตทริบิวต์

android:keycode

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

android:queryActionMsg

สตริง ข้อความการดำเนินการที่จะส่งหากกดปุ่มการดำเนินการขณะที่ ผู้ใช้ป้อนข้อความค้นหา โดยจะเพิ่มลงใน ACTION_SEARCH Intent ที่ระบบส่งไปยังกิจกรรมที่ค้นหาได้ หากต้องการตรวจสอบสตริง ให้ใช้ 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>