語音命令定義 (VCD) 元素和屬性 v1.2Voice Command Definition (VCD) elements and attributes v1.2

用於語音命令定義 (VCD) 檔中的 XML 標記元素和屬性的參考檔,以指定辨識條件約束。Reference documentation for the XML markup elements and attributes used in Voice Command Definition (VCD) files to specify recognition constraints.

使用語音命令來啟動應用程式,並指定要執行的動作或命令。Use voice commands to launch an app and specify an action or command to execute. 例如,使用者可以利用 [開始] 按鈕,並說出 contoso widget,顯示最佳銷售人員」來啟動 Contoso widget 應用程式,並流覽至「最佳銷售者」頁面。For example, a user could tap the Start button and say "Contoso Widgets, show best sellers" to both launch the Contoso Widgets app and to navigate to a "best sellers" page.

元素和屬性Elements and attributes

如同任何 XML 檔案,VCD 檔案的開頭應該是指定 XML 版本和字元編碼的 XML 宣告。As with any XML file, a VCD file should begin with an XML declaration that specifies both the XML version and the character encoding.

<?xml version="1.0" encoding="utf-8"?>

根項目是 VoiceCommands 元素,其 xmlns 屬性必須設定為 http://schemas.microsoft.com/voicecommands/1.2 (沒有任何大寫字元) 。The root element is the VoiceCommands element, and its xmlns attribute must be set to http://schemas.microsoft.com/voicecommands/1.2 (no uppercase characters). 如需符合此架構的範例,請參閱 Cortana Voice 命令範例For an example that conforms to this schema, see the Cortana Voice Command sample.

項目Element 描述Description
VoiceCommandsVoiceCommands 必要。Required. VCD 檔案的根項目。The root element of a VCD file. 包含1到15個 CommandSet 元素,其中每個專案都代表單一語言的語音命令。Contains between 1 and 15 CommandSet elements, each of which represents the voice commands for a single language.
CommandSetCommandSet VoiceCommands元素的必要子項目。Required child element of the VoiceCommands element. 應用程式將會以必要的 xml: lang 屬性指定的語言接受的所有語音命令的容器。A container for all the voice commands that an app will accept in the language specified by the required xml:lang attribute.

Xml: lang屬性的值在VoiceCommand檔中必須是唯一的,而且它是語言名稱表單中指定的單一特定語言,對應于語音控制台中可用的語言。The value of the xml:lang attribute must be unique in the VoiceCommand document, and it is a single, specific language, specified in language name form, that corresponds to a language that is available in the Speech control panel.

注意   在 VCD 檔案中指定但系統不支援的語言,則會被忽略。Note  Languages specified in the VCD file, but not supported on the system, are ignored.

Name屬性是選擇性的,可以是任一字元串;不過,需要名稱屬性才能以程式設計方式參考和更新CommandSet元素的PhraseListThe Name attribute is optional and can be any arbitrary string; however, the Name attribute is required in order to reference and update a CommandSet element's PhraseList programmatically. CommandSet元素包含下列子項目: CommandPrefix (0 或 1) 或AppName (0 或 1) 、範例 (正好 1) 、命令 (1 到 100) 、 PhraseList元素 (0 到 10) ,以及PhraseTopic專案 (0 至 10) 。The CommandSet element contains the following child elements: CommandPrefix (0 or 1) or AppName (0 or 1), Example (exactly 1), Command (1 to 100), PhraseList elements (0 to 10), and PhraseTopic elements (0 to 10). 這些子專案必須依照列出的順序出現。These child elements must occur in the order listed.

互斥Mutually exclusive CommandPrefixCommandPrefix

CommandSet元素的選擇性子項目。Optional child element of the CommandSet element. 如果有的話,必須是 CommandSet 元素的第一個子項目。If present, must be the first child element of the CommandSet element.

指定使用者在提供語音命令時可說出的應用程式使用者易記名稱。Specifies a user-friendly name for an app that a user can speak when giving a voice command. 這對於名稱很長或很難發音的應用程式很有用。This is useful for apps with names that are long or are difficult to pronounce.

避免使用與其他語音啟用體驗衝突的首碼。Avoid using prefixes that conflict with other voice-enabled experiences.

AppNameAppName

CommandSet元素的選擇性子項目。Optional child element of the CommandSet element. 如果有的話,必須是 CommandSet 元素的第一個子項目。If present, must be the first child element of the CommandSet element.

取代CommandPrefix ,並支援 ListenFor 元素的RequireAppName屬性和 {builtin:AppName} 片語。 ListenForReplaces CommandPrefix and supports the RequireAppName attribute and {builtin:AppName} phrase of the ListenFor element.

指定使用者在提供語音命令時可說出的應用程式使用者易記名稱。Specifies a user-friendly name for an app that a user can speak when giving a voice command. 這對於名稱很長或很難發音的應用程式很有用。This is useful for apps with names that are long or are difficult to pronounce.

避免使用與其他語音啟用體驗衝突的首碼。Avoid using prefixes that conflict with other voice-enabled experiences.

根據預設,在 voice 命令中,會將 AppName 支援做為尾碼。By default, the AppName is supported as a suffix in the voice command.

CommandCommand

CommandSet元素的必要子項目。Required child element of the CommandSet element.

採用 Name 屬性。Takes the Name attribute. 定義使用者可透過說話來起始的應用程式動作,以及使用者可以說出哪些動作來起始動作。Defines an app action that users can initiate by speaking and what users can say to initiate the action. 每個 命令 專案都可以與您應用程式中的特定頁面相關聯。Each Command element can be associated with a specific page in your app. 包含下列必要的子項目: 範例 只 (1) 、 ListenFor (1 到 20) 、 意見 反應 (正好 1) ,然後 流覽 (正好 1) 。Contains the following required child elements: Example (exactly 1), ListenFor (1 to 20), Feedback (exactly 1), and Navigate (exactly 1). 這些子專案必須依照列出的順序出現。These child elements must occur in the order listed.

範例Example CommandSet元素所需的子系必須剛好 (1) ,而且Command元素 (1 到 20) 。Required child of both the CommandSet element (exactly 1) and the Command element (1 to 20). 提供代表性的範例,說明使用者可以針對整個 CommandSet ,以及針對個別命令所說的內容。Gives a representative example of what a user can say for a CommandSet as a whole, and for an individual command. 使用者可以從 [ 我可以說 ] 畫面看到這些範例。These examples will be visible to a user from the What can I say screen. 當使用者在 Windows phone 上按下並按住 [ 搜尋 ] 按鈕 (時,會出現此畫面) 或叫用 Cortana ,然後說:「說明」或「我可以說什麼?」,或點擊 查看更多This screen appears when a user presses and holds the Search button (on Windows phones) or invokes Cortana and says, "Help" or "What can I say?", or taps See more.

注意   範例應包含AppNameCommandPrefixNote  Examples should include the AppName or CommandPrefix.

ListenForListenFor

Required (1 到 20) Command 元素的子項目。Required (1 to 20) child element of the Command element.

包含您的應用程式將針對此命令辨識的單字或片語。Contains a word or phrase that your app will recognize for this command. 這可能包括或參考 PhraseList (或 PhraseTopic) 專案的 Label 屬性,該屬性會出現在以大括弧括住的 ListenFor 元素中,例如: {myList} 或 {>mytopic}。This may include or be a reference to a PhraseList (or PhraseTopic) element's Label attribute, which appears in the ListenFor element enclosed in curly braces, for example: {myList}, or {myTopic}.

您可以辨識任何 ListenFor 元素的內容,以啟動命令。The content of any ListenFor elements can be recognized to activate the command.

您可以指定選擇性的 RequireAppName 屬性,以指出 AppName 專案的值是否可以附加、附加或搭配 ListenFor 元素一起使用。An optional RequireAppName attribute can be specified to indicate whether the value of the AppName element can be prepended, appended, or used inline with the ListenFor element.

這個屬性支援四個值:This attribute supports four values:

  • BeforePhraseBeforePhrase

    使用者必須在ListenFor片語之前說出AppNameThe user must say the AppName before the ListenFor phrase.

  • AfterPhraseAfterPhrase

    使用者必須說「In |開啟 |使用 |使用ListenFor片語後面的「 AppName 」。The user must say "In|On|Using|With" AppName after the ListenFor phrase.

  • BeforeOrAfterPhraseBeforeOrAfterPhrase

    使用者必須說出ListenFor片語之前或之後的AppNameThe user must say the AppName before or after the ListenFor phrase.

  • ExplicitlySpecifiedExplicitlySpecified

    您可以使用在ListenFor中明確參考AppName {builtin:AppName}The AppName is explicitly referenced in the ListenFor, using {builtin:AppName}. 使用者不需要在ListenFor片語之前或之後說出AppNameThe user is not required to say the AppName before or after the ListenFor phrase.

使用括弧括住可選擇的單字或單字。Use brackets around a word or words that are optional. 也就是說,可以說出單字或單字,但不需要進行相符。That is, the word or words can be spoken, but are not necessary for a match. 例如: <ListenFor>[Show] {options}</ListenFor>For example, <ListenFor>[Show] {options}</ListenFor>.

您可以藉由在成對的大括弧內包含星號字元(例如)來設定萬用字元功能 <ListenFor> Find {\*} </ListenFor>You can set up wildcard functionality by including an asterisk character inside a pair of curly braces, such as <ListenFor> Find {\*} </ListenFor>. 在此範例中,只要使用者說話「尋找」(選擇性地接著其他任何單字或片語),語音命令就會相符。In this example, the voice command will match as long as the user speaks "Find", optionally followed by any other word or phrase. 如果已啟用萬用字元的 ListenFor 專案的語音命令相符, SpeechRecognitionResult 將會包含字串 "..."與萬用字元相同的位置。If the voice command for a wildcard-enabled ListenFor element is matched, the SpeechRecognitionResult.Text property will contain the string "…" in the same position as the wildcard.

意見反應Feedback Command元素的必要子項目。Required child element of the Command element. 指定當命令可辨識時,將顯示的文字,並將其讀回給使用者。Specifies the text that will be displayed and read back to the user when the command is recognized. 如果回饋元素包含PhraseList (或PhraseTopic) 專案之Label屬性的參考,則包含命令專案中的每個ListenFor專案也都必須參考PhraseList (或PhraseTopic) 元素的相同label屬性。If the Feedback element includes a reference to a Label attribute of a PhraseList (or PhraseTopic) element, then every ListenFor element in the containing Command element must also reference the same Label attribute of the PhraseList (or PhraseTopic) element.
互斥Mutually exclusive NavigateNavigateCommand專案的必要子專案,除非Command元素有VoiceCommandService子項目。Required child element of the Command element, unless the Command element has a VoiceCommandService child element. 目標屬性是選擇性的,通常用來指定應用程式在啟動時流覽至的頁面。The Target attribute is optional and is typically used to specify the page that the app should navigate to when it launches. 您可以使用 "NavigationTarget" 索引鍵,取得目標屬性的值 (或空字串(如果您使用 "" 索引鍵從SpeechRecognitionSemanticInterpretation中省略目標屬性) )。You can obtain the value of the Target attribute (or the empty string if you omit the Target attribute) from the SpeechRecognitionSemanticInterpretation.Properties dictionary using the "NavigationTarget" key.
VoiceCommandServiceVoiceCommandService Command專案的必要子項目,除非Command專案具有導覽子項目。Required child element of the Command element, unless the Command element has a Navigate child element. 這個元素會指定透過 app service 來處理語音命令 (請參閱 ApplicationModel AppService) ,其中包含顯示在 Cortana 畫布上的意見反應。This element specifies that the voice command is handled through an app service (see Windows.ApplicationModel.AppService) with feedback displayed on the Cortana canvas. 目標屬性是強制性的,且必須符合應用程式封裝資訊清單AppService元素的Name屬性值。The Target attribute is mandatory and must match the value of the Name attribute of the AppService element in the app package manifest.
PhraseListPhraseList

CommandSet元素的選擇性子系。Optional child of the CommandSet element. 一個CommandSet元素不能包含超過2000個專案專案,而 2000專案專案CommandSet中所有PhraseList專案的組合總數。One CommandSet element can contain no more than 2,000 Item elements, and 2,000 Item elements is the combined total limit across all PhraseList elements in a CommandSet. 每個 專案 都會指定一個可辨識的單字或片語,以起始參考 PhraseList的命令。Each Item specifies a word or phrase that can be recognized to initiate the command that references the PhraseList. 專案內容可能會以程式設計方式從您的應用程式中更新。The Items content may be programmatically updated from within your application. PhraseList需要Label屬性,其值可能會以大括弧括住(以大括弧括住)在ListenFor意見專案內,並用來參考PhraseList。A PhraseList requires the Label attribute, the value of which may appear—enclosed by curly braces—inside ListenFor or Feedback elements, and is used to reference the PhraseList.

PhraseList 具有選擇性的 混淆屬性 (預設的 true) ,指定當同時辨識清單中的多個專案時,此 PhraseList 是否會產生使用者去除混淆。PhraseList has an optional Disambiguate attribute (default true), which specifies whether this PhraseList will produce user disambiguation when multiple items from the list are simultaneously recognized. 若為 false,此 PhraseList 也會在 意見 專案中無法使用,而且不會產生應用程式的參數。When false, this PhraseList will also be unusable from within Feedback elements and will not produce parameters for your application. 這對以替代方式指出相同內容的片語很有用,但不需要任何特定的動作。That's useful for phrases that are alternative ways of saying the same thing, but do not require any specific action.

在您的應用程式中,若要找出清單中的哪一個句子,您可以使用與PhraseList標籤相同的索引鍵來存取SpeechRecognitionSemanticInterpretation 屬性字典。In your app, to find out which phrase from the list was spoken, you can access the SpeechRecognitionSemanticInterpretation.Properties dictionary using a key with the same value as the Label of the PhraseList.

項目Item PhraseList元素的選擇性子系。Optional child of the PhraseList element. 可辨識以起始命令的多個單字或片語之一。One of multiple words or phrases that can be recognized to initiate a command. CommandSet可在其所有子PhraseList元素中包含2000個以上的專案專案A CommandSet can contain no more than 2,000 Item elements across all of its child PhraseList elements.
PhraseTopicPhraseTopic

CommandSet元素的選擇性子系。Optional child of the CommandSet element. 指定大型詞彙辨識的主題。Specifies a topic for large vocabulary recognition. 本主題可能會指定單一 (0 或 1) 案例 屬性,以及情節的數個 (0 到 20) 主體 子專案,這可能會用來改善達成辨識的相關性。The topic may specify a single (0 or 1) Scenario attribute and several (0 to 20) Subject child elements for the scenario, which may be used to improve the relevance of the recognition achieved. PhraseTopic需要Label屬性,其值可能會以大括弧括住(以大括弧括住)在ListenFor意見專案內,並用來參考PhraseTopicA PhraseTopic requires the Label attribute, the value of which may appear—enclosed by curly braces—inside ListenFor or Feedback elements, and is used to reference the PhraseTopic.

案例屬性 (預設值 "聽寫" ) 為此PhraseTopic指定所需的案例,這可能會使用PhraseTopic來優化語音命令的基礎語音辨識,以產生更適合命令所需內容的結果。The Scenario attribute (default "Dictation") specifies the desired scenario for this PhraseTopic, which may optimize the underlying speech recognition of voice commands using the PhraseTopic to produce results that are better-suited to the desired context of the command. 有效的值為「自然語言」、「搜尋」、「簡短訊息」、「聽寫」、「命令」和「表單填滿」。Valid values are "Natural Language", "Search", "Short Message", "Dictation", "Commands", and "Form Filling".

主旨子項目會指定父PhraseTopic案例屬性專屬主體,以使用PhraseTopic進一步調整語音辨識結果在語音辨識結果中的相關性。The Subject child elements specify a subject specific to the Scenario attribute of the parent PhraseTopic to further refine the relevance of speech recognition results within spoken commands using the PhraseTopic. 將會依照提供的順序來評估主旨,且稍後指定的主旨將會限制較早指定的主體。Subjects will be evaluated in the order provided and, when appropriate, later-specified subjects will constrain earlier-specified ones. 有效的內部文字值為「日期/時間」、「位址」、「縣/市」、「人員姓名」、「電影」、「音樂」和「電話號碼」。Valid inner text values are "Date/Time", "Addresses", "City/State", "Person Names", "Movies", "Music", and "Phone Number". 例如:<Subject>Phone Number</Subject>For example: <Subject>Phone Number</Subject>

在您的應用程式中,若要找出以PhraseTopic參考表示的ListenFor專案子集所說的內容,您可以使用具有與PhraseTopic標籤相同值的索引鍵來存取SpeechRecognitionSemanticInterpretation 屬性字典。In your app, to find out the content spoken in the subset of a ListenFor element represented by a PhraseTopic reference, you can access the SpeechRecognitionSemanticInterpretation.Properties dictionary using a key with the same value as the Label of the PhraseTopic.

重要

您無法將下列特殊字元嵌套。It’s not possible to nest the special characters listed below. 例如,和和之類的語句 [[start] new game] [{myPhraseList}] 是不可行的。For example, statements like [[start] new game] and [{myPhraseList}] are not possible.

特殊字元Special character 描述Description
{} 包含要參考之PhraseListPhraseTopic標籤屬性值,例如: {myList} 或 {>mytopic}。Contains the value of the Label attribute for the PhraseList or PhraseTopic to reference, for example: {myList}, or {myTopic}. 用於 ListenFor意見 專案中。Used within a ListenFor or Feedback element. 意見專案中的PhraseListPhraseTopic參考必須與相同命令中的ListenFor元素中的對應參考相符。A PhraseList or PhraseTopic reference in a Feedback element must match a corresponding reference in a ListenFor element in the same command.
[][]指定括住的單字或片語是選擇性的。Designates that the enclosed word or phrase is optional. 可以說出包含的單字或片語,但不一定要加以辨識才能起始命令。The enclosed word or phrase may be spoken but is not required to be recognized to initiate the command. 例如,如果 ListenFor 元素的內容是「開始」 [開始] 新遊戲」,則使用者可以說「開始新遊戲」或「新遊戲」或「開始新遊戲」, (或甚至「開始新遊戲」 ) 來起始命令。For example, if the contents of a ListenFor element are "[start] [begin] new game", the user can speak "start new game" or "new game" or "begin new game" (or even "start begin new game") to initiate the command. 每個以括弧括住的元素都是獨立的,但必須以正確的順序來讀出才能辨識。Each bracketed element is independently optional, but they must be spoken in the correct order to be recognized. 因此,在「新遊戲」範例中,「開始新遊戲」會正常運作,但「開始新遊戲」會因為其宣告的順序而無法運作。So, in the "new game" example, "start begin new game" would work, but "begin start new game" would not work because of the order in which they were declared.

另請參閱See also

ApplicationModel. VoiceCommandsWindows.ApplicationModel.VoiceCommands

Cortana 互動Cortana interactions

設計工具Designers
Cortana 設計指導方針Cortana design guidelines

範例Samples
Cortana 語音命令範例Cortana voice command sample