Schema JSON della definizione dell'azione per le azioni dell'app in Windows

2025-05-20

Questo articolo descrive il formato del formato di file JSON di definizione dell'azione per Le azioni dell'app in Windows. Questo file deve essere incluso nel progetto con l'azione di compilazione impostata su "Contenuto" e Copia nella directory di output impostata su "Copia se più recente". Specificare il percorso relativo del pacchetto al file JSON nel file XML del manifesto del pacchetto. Per ulteriori informazioni, vedere il formato XML del manifesto del pacchetto azioni del provider.

File JSON di esempio di definizione dell'azione

"version": 2, 
  "actions": [ 
    { 
      "id": "Contoso.SampleGreeting", 
      "description": "Send greeting with Contoso", 
      "icon": "ms-resource//...", 
      "usesGenerativeAI": false,
      "isAvailable": false,
      "inputs": [ 
        { 
          "name": "UserFriendlyName", 
          "kind": "Text" 
        }, 
        { 
          "name": "PetName", 
          "kind": "Text", 
          "required": false 
        } 
      ], 
      "inputCombinations": [ 
        { 
          "inputs": ["UserFriendlyName"], 
          "description": "Greet ${UserFriendlyName.Text}" 
        }, 
        { 
          "inputs": ["UserFriendlyName", "PetName"], 
          "description": "Greet ${UserFriendlyName.Text} and their pet ${PetName.Text}" 
        } 
      ], 
      "contentAgeRating": "child",  
      "invocation": 
      {
        { 
          "type": "Uri", 
          "uri": "contoso://greetUser?userName=${UserFriendlyName.Text}&petName=${PetName.Text}", 
        }, 
        "where": [ 
          "${UserFriendlyName.Length > 3}" 
        ] 
      } 
    }, 
    { 
      "id": "Contoso.SampleGetText", 
      "description": "Summarize file with Contoso", 
      "icon": "ms-resource://...", 
      "inputs": [ 
        { 
          "name": "FileToSummarize", 
          "kind": "File" 
        } 
      ], 
      "inputCombinations": [ 
        { 
          "inputs": ["FileToSummarize"], 
          "description": "Summarize ${FileToSummarize.Path}" 
        }, 
      ], 
      "outputs": [ 
        { 
          "name": "Summary", 
          "kind": "Text" 
        } 
      ],
      "contentAgeRating": "child", 
      "invocation": { 
        "type": "COM", 
        "clsid": "{...}" 
      } 
    } 
  ] 
}

Proprietà JSON di definizione dell'azione

Le tabelle seguenti descrivono le proprietà del file JSON di definizione dell'azione.

Radice documento

Proprietà	TIPO	Descrizione	Obbligatorio
Versione	corda	Versione dello schema. Quando sono state aggiunte nuove funzionalità, la versione viene incrementata di una.	Sì.
Azioni	Azione[]	Definisce le azioni fornite dall'app.	Sì.

Azione

Proprietà	TIPO	Descrizione	Obbligatorio
Id	corda	Identificatore dell'azione. Deve essere univoco per ogni pacchetto dell'app. Questo valore non è localizzabile.	Sì
descrizione	corda	Descrizione rivolta all'utente per questa azione. Questo valore è localizzabile.	Sì
icona	corda	Icona localizzabile per l'azione. Questo valore è una stringa ms-resource per un'icona distribuita con l'app.	NO
utilizza l'Intelligenza Artificiale Generativa	Booleano	Specifica se l'azione usa l'intelligenza artificiale generativa. Il valore predefinito è false.	NO
èDisponibile	Booleano	Specifica se l'azione è disponibile per l'uso al momento dell'installazione. Il valore predefinito è true.	Sì
Ingressi	Input[]	Elenco di entità accettate da questa azione come input.	Sì
combinazioni di input	CombinazioneInput[]	Fornisce descrizioni per diverse combinazioni di input.	Sì
Risultati	Risultato[]	Se specificato, deve essere una stringa vuota nella versione corrente.	NO
invocazione	Invocazione	Fornisce informazioni sulla modalità di chiamata dell'azione.	Sì
classificazioneEtàContenuto	corda	Nome di campo di UserAgeConsentGroup che specifica la classificazione dell'età appropriata per l'azione. I valori consentiti sono "Child", "Minor", "Adult". Se non viene specificato alcun valore, il comportamento predefinito consente l'accesso a tutte le età.	NO

Risultato

Proprietà	TIPO	Descrizione	Obbligatorio
nome	corda	Nome della variabile dell'entità. Questo valore non è localizzabile.	Sì
tipo/gentile	corda	Nome di campo dell'enumerazione ActionEntityKind che specifica il tipo di entità. Questo valore non è localizzabile. I valori consentiti sono "None", "Document", "File", "Photo", "Text".	Sì

Combinazione di input

Proprietà	TIPO	Descrizione	Obbligatorio
Ingressi	stringa[]	Elenco di nomi di input per una chiamata all'azione. L'elenco può essere vuoto.	Sì
descrizione	corda	Descrizione per la chiamata all'azione. Questo valore è localizzabile.	NO
dove	stringa[]	Una o più istruzioni condizionali che determinano le condizioni in cui si applica l'azione.	NO

Invocazione

Proprietà	TIPO	Descrizione	Obbligatorio
tipo	corda	Tipo di istanza per l'azione. I valori consentiti sono "uri" e "com"	Sì
URI	corda	URI assoluto per l'avvio dell'azione. L'utilizzo delle entità può essere incluso nella stringa.	Sì, per le azioni instanziate URI.
clsid	corda	ID classe per la classe COM che implementa IActionProvider.	Sì, per le azioni COM
dati di input	Elenco di coppie nome/valore che specificano dati aggiuntivi per le azioni URI.	No Valido solo per le azioni URI.

Enumerazione ActionEntityKind

L'enumerazione ActionEntityKind specifica i tipi di entità supportate da Azioni app in Windows. Nel contesto di una definizione di azione JSON, i tipi di entità sono stringhe letterali sensibili alle maiuscole.

Stringa del tipo di entità	Descrizione
Documento	Include tutti i tipi di file non supportati dai tipi di entità foto o documento.
Foto	Tipi di file di immagine. Le estensioni di file di immagine supportate sono ".jpg", ".jpeg" e ".png"
"Documento"	Tipi di file di documento. Le estensioni di file di documento supportate sono ".doc", ".docx", ".pdf", ".txt"
"Testo"	Supporta stringhe di testo.
StreamingText	Supporta stringhe di testo con flusso incrementale.
"RemoteFile"	Supporta i metadati per consentire alle azioni di convalidare e recuperare file di backup da un servizio cloud.

Proprietà delle entità

Ogni tipo di entità supporta una o più proprietà che forniscono i dati dell'istanza per l'entità. I nomi delle proprietà di entità fanno distinzione tra maiuscole e minuscole.

Nell'esempio seguente viene illustrato come viene fatto riferimento alle entità nella stringa di query per le azioni avviate tramite l'attivazione URI:

...?param1=${entityName.property1}&param2=${entityName.property2}

Per informazioni sull'uso delle proprietà dell'entità per creare sezioni condizionali nel file JSON di definizione dell'azione, vedere Clausole Where.

Proprietà dell'entità file

Proprietà	TIPO	Descrizione
Nome del File	corda	Nome del file.
"Percorso"	corda	Percorso del file.
"Estensione"	corda	L'estensione del file.

Proprietà dell'entità di documento

L'entità Document supporta le stesse proprietà di File.

Proprietà delle entità foto

L'entità Photo supporta tutte le proprietà di File oltre alle proprietà seguenti.

Proprietà	TIPO	Descrizione
IsTemporaryPath	Booleano	Valore che specifica se la foto viene archiviata in un percorso temporaneo. Ad esempio, questa proprietà è true per le foto archiviate in memoria da una bitmap, non archiviate in modo permanente in un file.

Proprietà dell'entità di testo

Proprietà	TIPO	Descrizione
"Testo"	corda	Testo completo.
Testo breve	corda	Versione abbreviata del testo, adatta per la visualizzazione dell'interfaccia utente.
"Titolo"	corda	Titolo del testo.
"Descrizione"	corda	Descrizione del testo.
Lunghezza	doppio	Lunghezza del testo in caratteri.
ContaParole	doppio	Numero di parole nel testo.

Proprietà dell'entità StreamingText

Proprietà	TIPO	Descrizione
"TextFormat"	corda	Formato del testo in streaming. I valori supportati sono "Plain", "Markdown".

Proprietà dell'entità RemoteFile

Proprietà	TIPO	Descrizione
"AccountId"	corda	Identificatore dell'account del servizio cloud associato al file remoto.
Tipo di Contenuto	corda	Tipo MIME del file remoto.
"DriveId"	corda	Identificatore dell'unità remota associata al file remoto.
"Estensione"	corda	Estensione del file remoto.
ID del file	corda	Identificatore del file remoto.
"FileKind"	RemoteFileKind	Tipo di file remoto.
SourceId	corda	Identificatore del servizio cloud che ospita il file remoto.
"SourceUri"	corda	URI del file remoto.

Enumerazione RemoteFileKind

L'enumerazione RemoteFileKind specifica i tipi di file supportati per l'entità RemoteFile .

Stringa del tipo di entità	Descrizione
Documento	Include tutti i tipi di file non supportati dai tipi di entità foto o documento.
Foto	Tipi di file di immagine. Le estensioni di file di immagine supportate sono ".jpg", ".jpeg" e ".png"
"Documento"	Tipi di file di documento. Le estensioni di file di documento supportate sono ".doc", ".docx", ".pdf", ".txt"

Clausole Where

Il formato JSON della definizione di azione supporta le clausole where che possono essere usate per implementare la logica condizionale, ad esempio specificando che un'azione deve essere richiamata solo quando una proprietà di entità ha un valore specificato.

Gli operatori seguenti possono essere usati con le clausole where .

Operatore	Descrizione
==	Uguaglianza
~=	Uguaglianza senza distinzione tra maiuscole e minuscole
!=	Disuguaglianza
<	Meno di
<=	Minore o uguale a
>	Maggiore di
>=	Maggiore o uguale a
\|\|	oppure logico
&&	E logico

Le clausole Where usano il formato seguente:

"where": [ 
    "${<property_accessor>} <operator> <value>" 
]

Nell'esempio seguente viene illustrata una clausola where che restituisce true se un'entità File ha l'estensione di file ".txt".

"where": [ 
    "${File.Extension} ~= \".txt\"" 
]

Più clausole where possono essere combinate usando gli operatori AND logici e OR logici.

"where": [ 
  "${File.Extension} ~= \".txt\" || ${File.Extension} ~= \".md\"" 
]