Схема определения действия JSON для действий приложений в Windows

2025-05-20

В этой статье описывается формат json-файла определения действия для действий приложений в Windows. Этот файл должен быть включен в проект с действием сборки с параметром "Содержимое" и "Копировать в выходной каталог ", равным "Копировать, если новее". Укажите относительный путь к JSON-файлу в XML-файле манифеста пакета. Для получения дополнительной информации смотрите XML формат манифеста пакета поставщика действий.

Пример JSON-файла определения действия

"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": "{...}" 
      } 
    } 
  ] 
}

Свойства JSON определения действия

В таблицах ниже описаны свойства JSON-файла определения действия.

Корневой каталог документа

Недвижимость	Тип	Описание	Обязательно
версия	струна	Версия схемы. При добавлении новых функций версия увеличивается на единицу.	Да.
Действия	Действие[]	Определяет действия, предоставляемые приложением.	Да.

Действие

Недвижимость	Тип	Описание	Обязательно
идентификатор	струна	Идентификатор действия. Должен быть уникальным для каждого пакета приложения. Это значение не локализуется.	Да
описание	струна	Описание этого действия для пользователя. Это значение локализуется.	Да
икона	струна	Локализуемый значок для действия. Это значение представляет собой строку ms-resource для значка, развернутого с помощью приложения.	нет
использует генеративный ИИ	Логический	Указывает, используется ли действие генеративным искусственным интеллектом. По умолчанию используется значение false.	нет
доступен	Логический	Указывает, доступно ли действие для использования после установки. Значение по умолчанию — true.	Да
входные данные	Входные данные[]	Список сущностей, которые это действие принимает в качестве входных данных.	Да
входные комбинации	ВходнаяКомбинация[]	Содержит описания различных сочетаний входных данных.	Да
выходные данные	Выходные данные[]	Если задано, в текущем выпуске это должно быть пустой строкой.	нет
вызов	Инвокация	Предоставляет сведения о том, как вызывается действие.	Да
возрастной рейтинг контента	струна	Имя поля из UserAgeConsentGroup , указывающее соответствующий возрастной рейтинг действия. Допустимые значения: "Ребенок", "Несовершеннолетний", "Взрослый". Если значение не указано, поведение по умолчанию разрешает доступ ко всем возрастам.	нет

Выходные данные

Недвижимость	Тип	Описание	Обязательно
имя	струна	Название переменной сущности. Это значение не локализуется.	Да
добрый	струна	Имя поля из перечисления ActionEntityKind , указывающее тип сущности. Это значение не локализуется. Допустимые значения: "Нет", "Документ", "Файл", "Фото", "Текст".	Да

Комбинация ввода

Недвижимость	Тип	Описание	Обязательно
входные данные	строка[]	Список имен входных данных для вызова действия. Список может быть пустым.	Да
описание	струна	Описание вызова действия. Это значение локализуется.	нет
где	строка[]	Одно или несколько условных выражений, определяющих, при каких условиях применяется действие.	нет

Инвокация

Недвижимость	Тип	Описание	Обязательно
тип	струна	Тип инстанцирования действия. Допустимые значения: "URI" и "com"	Да
УРИ	струна	Абсолютный универсальный код ресурса (URI) для запуска действия. Использование сущностей можно включить в строку.	Да, для URI, где выполнены действия.
clsid	струна	Идентификатор класса COM, реализующий IActionProvider.	Да, для действий COM
входныеДанные	Список пар name/value, указывающих дополнительные данные для действий URI.	Нет. Действительно только для действий URI.

Перечисление типа ActionEntityKind

Перечисление ActionEntityKind указывает типы сущностей, поддерживаемых действиями приложений в Windows. В контексте определения действия JSON типы сущностей представляют собой строковые литералы, которые чувствительны к регистру.

Строка типа сущности	Описание
"Файл"	Включает все типы файлов, которые не поддерживаются типами сущностей фотографий или документов.
Фото	Типы файлов изображений. Поддерживаемые расширения файлов изображений: ".jpg", ".jpeg" и ".png".
"Документ"	Типы файлов документов. Поддерживаемые расширения файлов документов: ".doc", ".docx", ".pdf", ".txt"
"Текст"	Поддерживает строки текста.
StreamingText	Поддерживает постепенную передачу строк текста.
RemoteFile	Поддерживает метаданные для включения действий для проверки и извлечения резервных файлов из облачной службы.

Свойства сущности

Каждый тип сущности поддерживает одно или несколько свойств, которые предоставляют данные экземпляра для сущности. Имена свойств сущностей чувствительны к регистру.

В следующем примере показано, как сущности ссылаются в строке запроса для действий, запускаемых с помощью активации URI:

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

Сведения об использовании свойств сущности для создания условных разделов в определении действия JSON см. раздел «условия Where».

Свойства сущности файла

Недвижимость	Тип	Описание
ИмяФайла	струна	Имя файла.
"Путь"	струна	Путь к файлу.
"Расширение"	струна	Расширение файла.

Свойства сущности документа

Сущность Document поддерживает те же свойства, что и Файл.

Свойства фото объекта

Сущность Photo поддерживает все свойства файла в дополнение к следующим свойствам.

Недвижимость	Тип	Описание
ЯвляетсяВременнымПутем	Логический	Значение, указывающее, хранится ли фотография во временном пути. Например, это свойство верно для фотографий, которые хранятся в памяти из растрового изображения, а не хранятся постоянно в файле.

Свойства сущности текста

Недвижимость	Тип	Описание
"Текст"	струна	Полный текст.
Короткий текст	струна	Сокращенная версия текста, подходящая для отображения пользовательского интерфейса.
Заголовок	струна	Заголовок текста.
"Описание"	струна	Описание текста.
"Длина"	двойной	Длина текста в символах.
"Подсчет слов"	двойной	Количество слов в тексте.

Свойства сущности StreamingText

Недвижимость	Тип	Описание
"TextFormat"	струна	Формат потокового текста. Поддерживаемые значения: "Plain", "Markdown".

Свойства сущности RemoteFile

Недвижимость	Тип	Описание
ИдентификаторАккаунта	струна	Идентификатор учетной записи облачной службы, связанной с удаленным файлом.
ТипКонтента	струна	Тип MIME удаленного файла.
DriveId	струна	Идентификатор удаленного диска, связанного с удаленным файлом.
"Расширение"	струна	Расширение удаленного файла.
Идентификатор файла	струна	Идентификатор удаленного файла.
FileKind	RemoteFileKind	Тип удаленного файла.
Идентификатор источника	струна	Идентификатор облачной службы, на котором размещен удаленный файл.
SourceUri	струна	URI удаленного файла.

Перечисление вида удалённого файла

Перечисление RemoteFileKind указывает типы файлов, которые поддерживаются для сущности RemoteFile .

Строка типа сущности	Описание
"Файл"	Включает все типы файлов, которые не поддерживаются типами сущностей фотографий или документов.
Фото	Типы файлов изображений. Поддерживаемые расширения файлов изображений: ".jpg", ".jpeg" и ".png".
"Документ"	Типы файлов документов. Поддерживаемые расширения файлов документов: ".doc", ".docx", ".pdf", ".txt"

Условные выражения WHERE

Формат JSON определения действия поддерживает конструкции where, которые можно использовать для реализации условной логики, например, указания того, что действие должно вызываться только в том случае, если свойство сущности имеет указанное значение.

С условиями WHERE можно использовать следующие операторы.

Оператор	Описание
==	Равенство
~=	Равенство без учета регистра
!=	Неравенство
<	Меньше
<=	Меньше или равно
>	Больше чем
>=	Больше или равно
\|\|	Логическое ИЛИ
&&	Логическое AND

Где предложения используют следующий формат:

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

В следующем примере показано предложение where , которое вычисляет значение true, если сущность файла имеет расширение файла ".txt".

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

Несколько условий WHERE можно объединить с помощью логических операторов И и ИЛИ.

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