Searchable之自定义Suggestions（中）

原文地址：http://developer.android.com/guide/topics/search/adding-custom-suggestions.html

提取suggestions的Content Provider

用于提取suggestions的Content Provider和普通的Content Provider差不多，只是它返回的Cursor必须包含特定的列，这样系统才好从中提取数据。

当用户开始向search dialog or search widget键入的时候,键入一个字符，系统都会通过query()函数在你的Content Provider中进行查询。

当你在你的Content Provider中实现query()函数的时候，你必须对suggestion进行查询，然后用Cursor返回你认为比较好的suggestion。

关于该 Content Provider的更多内容请参照下面的两部分： suggestions查询的处理和 suggestions表的创建

suggestions查询的处理

当系统向你的 Content Provider请求 suggestion的时候，它将调用你的Content Provider的 query()方法， 你必须在该函数中进行suggestion查询，然后用Cursor返回你认为合适的suggestion

下面是传到你的query()的参数的列表：

uri

它是一个content  Uri, 

它的格式如下: content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY

默认情况下系统是在上面格式的Uri基础上再加上query text。比如：

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

注意这里的Uri末尾的query text是用URL方式进行编码的，所以你需要解码。

一般都是采用如下的方式取得它：String query = uri.getLastPathSegment().toLowerCase();

这里的optional.suggest.path就是在你的searchable配置文件中设置的android:searchSuggestPath，如果在searchable配置文件没有设置它，optional.suggest.path当然也不会包括在uri中。只有你需要一个Content Provider为多个searchable activities提供suggestions查询的时候，才需要设置android:searchSuggestPath，这时它用于区分是哪个searchable activities。

注意: SUGGEST_URI_PATH_QUERY 并不是URI的字面字符串,它是一个静态成员常量，表示是把该常量的值加到uri中

   
   
   
   

    
    
    
    
   
   
   
   
   
   
   
   

    
    
    
    projection
   
   
   
   
   
   
   
   

    
    
    
     
    
    
    
    总是为null.在程序中我们总是把查询的projection写死的,不需要外部传入。
   
   
   
   
   
   
   
   

    
    
    
    selection
   
   
   
   
   
   
   
   

    
    
    
      
    
    
    
    该值就是在searchable配置文件中设置的android:searchSuggestSelection属性的值。如果在searchable配置文件中没有设置该属性，这该值为null.
   
   
   
   
   
   
   
   

    
    
    
    selectionArgs
   
   
   
   
   
   
   
   

    
    
    
      
    
    
    
     如果你在searchable配置文件中设置了android:searchSuggestSelection属性的值，那么search query将做为该数组的第一项（其实最多也只有这项目）。如果没有设置则该参数为null.
   
   
   
   
   
   
   
   

    
    
    
    sortOrder
   
   
   
   
   
   
   
   

    
    
    
        
    
    
    
    总是为null
   
   
   
   
   
   
   
   

    
    
    
    系统能以两种方式向你传送search query text。默认的是以附在content URI末尾的方式。然而如果你在searchable配置文件设置了
   
   
   
   
   
   
   
   

    
    
    
    android:searchSuggestSelection属性的话, query text就以做为selectionArgs字符串数组的第一个元素的形式传给你.
   
   
   
   
   
   
   
   

    
    
    
    在uri中取query
   
   
   
   
   
   
   
   

    
    
    
    默认情况下, query是追加到uri参数的最后一部分的. 在这种情况下，提取query text很简单, 使用getLastPathSegment()命令就可以了
    
    
    
    .比如： String query = uri.getLastPathSegment().toLowerCase(); 
    
    
    
    该函数返回的是Uri的最后一部分, 这里的话就是用户键入的query text
   
   
   
   
   
   
   
   

    
    
    
    在selection参数中提取query
   
   
   
   
   
   
   
   

    
    
    
    如果你想query()方法的扩展性更高，想让它可以收到执行look-up处理所需要的所有东西的， 那么这时你就要不使用URI来传递query，而是使用selection and selectionArgs参数来携带合适的values. 采用这种方式的话， 你就需要在searchable配置文件中设置和你的SQLite selection相对应的android:searchSuggestSelection属性.在selection字符串种,必须包括
    
    
    
    a question mark ("?") as a placeholder for the actual search query. 系统将以该selection字符串作为selection参数和search query作为selectionArgs数组参数第一元素的形式调用query().
   
   
   
   
   
   
   
   

    
    
    
    比如你可以以下的方式设置android:searchSuggestSelection： 
    
    
    
    示例2： 
    
    
    
    <?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> 
    
    
    
    
 
     通过这样的配置, 你的query()方法的selection参数将是"word MATCH ?"且selectionArgs参数就是search query. 当你把他们传到SQLite的query()方法后, 他们将进行合成（问号将被query text所代替。如果你采用该方式来进行suggestion的查询且需要在query text的基础上再使用通配符,那么请在selectionArgs上追加他们（and/or prefix），因为该值用quotes进行wrap,然后插入到“？”所在的位置. 
    
    
    
    
    
 
     示例2 
     的另外一个新属性是android:searchSuggestIntentAction, 它定义了当用户选择一个suggestion后，发送的intent的action值我们将在下文对它进行更深入的讨论。 
    
    
    
    
    
 
     Tip 
     :如果你不想在 
     android:searchSuggestSelection 
     中定义selection clause,但是你还是想通过 
     selectionArgs 
     参数接收query text, 那么只需要把 
     android:searchSuggestSelection 
     设置为非空就可以了。这样query text还是会被传到 
     selectionArgs 
     ，你忽略selection参数就行了.通过这种方式你可以在更底层定义selection clause（这里的更底层是哪里呢？puzzle）这样你的content provider就根本不需要处理它了。 
    
    
    
    
    
 
     Building a suggestion table 
      当你通过Cursor向系统返回suggestion列表时，系统希望该Cursor中包含了一些specific的列。 所以无论你的suggestion data是以SQLite database的形式存储在设备上或以SQLite database的形式存储在web服务器上, 还是以其他的格式存储在你设备或web上,你都必须把suggestions格式为table中的rows，且以Cursor的形式来提供suggestion. 系统能够understands几个columns, 其中有2个是必须要提供的： _ID  
     每个suggestion的unique integer row ID. 系统需要它，以便在ListView中显示suggestions. 
       
    
    
    
    
    
 
     SUGGEST_COLUMN_TEXT_1 
    
    
    
    
    
 
      主suggestion text 
    
    
    
    
    
 
     下面的几列是可选： 
    
    
    
    
    
 
     SUGGEST_COLUMN_TEXT_2 
    
    
    
    
    
 
      次suggestion text。如果你的Cursor包含了该列，那么suggestion将以2行的形式进行显示。次 
     suggestion text将在首 
     suggestion text下面一行以更小的字体进行显示。如果该列的值为空或null,则表示没有次 
     suggestion text。 
    
    
    
    
    
 
     SUGGEST_COLUMN_ICON_1 
    
    
    
    
    
 
      它表示的是一个drawable resource, content或file的URI字符串形式. 如果你的Cursor包含了该column, 那么所有的suggestions将以文本+图标的形式进行显示，该图标在文本的左边. 该值可以为null或zero以表示该行所对应的suggestion没icon. 
    
    
    
    
    
 
     SUGGEST_COLUMN_ICON_2 
    
    
    
    
    
 
      
      它表示的是一个drawable resource, content或file的URI字符串形式. 如果你的Cursor包含了该column, 那么所有的suggestions将以文本+图标的形式进行显示，该图标在文本的右边. 该值可以为null或zero以表示该行所对应的suggestion没icon. 
    
    
    
    
    
 
     SUGGEST_COLUMN_INTENT_ACTION 
    
    
    
    
    
 
      它是一个intent action的字符串形式. 它用于定义当用户选择了suggestion时的intent的action。 如果该列没有被提供, 则次时intent的action为searchable配置文件中 
     android:searchSuggestIntentAction 
     属性的值. 如果你的所有的suggestions的action都一样, 那么最好使用 
     android:searchSuggestIntentAction 
     来定的该intent的action，而不用该列。 
    
    
    
    
    
 
     SUGGEST_COLUMN_INTENT_DATA 
    
    
    
    
    
 
      它表示的是一个data的URI字符串形式。它用于定义当用户选择了suggestion时的intent的data。 如果该列没有被提供, 则次时intent的action为searchable配置文件中 
     android:searchSuggestIntentData 
     属性的值. 如果你的所有的suggestions的intent的data都一样, 那么最好使用 
     android:searchSuggestIntentData 
     来定义该intent的data，而不用该列。 
    
    
    
    
    
 
      
     SUGGEST_COLUMN_INTENT_DATA_ID 
    
    
    
    
    
 
      它是URI字符串形式. 如果该列被提供，"/"+该列的值将被追加到intent的data域上.只有searchable配置文件的android:searchSuggestIntentData属性被设置了（这时该属性做为data的基本URL字符串），该列才有意义. 
    
    
    
    
    
 
     SUGGEST_COLUMN_INTENT_EXTRA_DATA 
      
    
    
    
    
    
 
      它可以是任意的数据. 如果提供了该列的值，它会被加入到当用户选择了suggestion时的intent的extra data。如果没有提供，那么intent的extra data域就是null.该列让suggestions可以提供额外的data，以便在intent的extras中通过 
     EXTRA_DATA_KEY 
     key进行提取。 
    
    
    
    
    
 
     SUGGEST_COLUMN_QUERY 
    
    
    
    
    
 
     它表示该suggestion所对应的query(查询关键字). 如果提供了该列的值，它会被加入到当用户选择了suggestion时的intent的 
    
    
    
    
    
 
     extra data。可以在intent的extras中通过 
     QUERY 
     key进行提取，如果suggestion的action是 
     ACTION_SEARCH 
     ，这该列为必选。否则，为可选的 
    
    
    
    
    
 
     SUGGEST_COLUMN_SHORTCUT_ID 
    
    
    
    
    
 
      该列只有为Quick Search Box提供suggestions才有用.该列说明了search suggestion是否会被做为a shortcut而被保存以及它是否是validated. 当用户在Quick Search Box中点击一个suggestion，那么针对该suggestion的Shortcuts通常会被生成并被存储.如果没该列，则suggestion的Shortcuts会被存储，但是永远不会被刷新。如果把它设置为 
     SUGGEST_NEVER_MAKE_SHORTCUT, 
     那么就不会有Shortcuts,否则该shortcut Id是在使用 
     SUGGEST_URI_PATH_SHORTCUT 
     进行最新suggestion检查时使用。 
       
    
    
    
    
    
 
     SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING 
    
    
    
    
    
 
      该列只有为Quick Search Box提供suggestions才有用。在Quick Search Box中，当系统在进行 
     Quick Search Box 
     的更新时，该列所表示的图标将取代 
     SUGGEST_COLUMN_ICON_2 
     在其位置进行显示。 
    
    
    
    
    
 
     关于上面几列的详细信息，后文还会继续介绍。