16. Локальные xml аннотации

16. Локальные XML аннотации для Fiori Elements и SmartFields

В этом разделе собраны основные XML аннотации, которые чаще всего используются при разработке Fiori Elements и SmartFields-приложений. Аннотации позволяют управлять отображением фильтров, колонок таблиц, фасетов, экшн-кнопок, value helps и других элементов UI без необходимости писать много кода на JavaScript.

Основные пространства имён аннотаций

  • com.sap.vocabularies.UI.v1 — UI-аннотации (LineItem, FieldGroup, Facet, Action и др.)
  • com.sap.vocabularies.Common.v1 — Общие аннотации (ValueList, Text, SemanticKey и др.)
  • com.sap.vocabularies.SelectionPresentationVariant.v1 — Варианты представления и фильтрации

1. Фильтры (SelectionFields)

Определяют поля, которые будут отображаться в фильтре (SmartFilterBar).

<Annotations Target="MyService.EntityType">
  <Annotation Term="com.sap.vocabularies.UI.v1.SelectionFields">
    <Collection>
      <PropertyPath>Field1</PropertyPath>
      <PropertyPath>Field2</PropertyPath>
    </Collection>
  </Annotation>
</Annotations>

2. Поля таблицы (LineItem)

Определяют колонки для SmartTable/ListReport.

<Annotations Target="MyService.EntityType">
  <Annotation Term="com.sap.vocabularies.UI.v1.LineItem">
    <Collection>
      <Record Type="com.sap.vocabularies.UI.v1.DataField">
        <PropertyValue Property="Value" Path="Field1"/>
      </Record>
      <Record Type="com.sap.vocabularies.UI.v1.DataField">
        <PropertyValue Property="Value" Path="Field2"/>
      </Record>
    </Collection>
  </Annotation>
</Annotations>

3. Фасеты (Facets)

Группируют поля на Object Page (например, секции, вкладки, группы).

<Annotations Target="MyService.EntityType">
  <Annotation Term="com.sap.vocabularies.UI.v1.Facets">
    <Collection>
      <Record Type="com.sap.vocabularies.UI.v1.CollectionFacet">
        <PropertyValue Property="Label" String="Общие данные"/>
        <PropertyValue Property="Facets">
          <Collection>
            <Record Type="com.sap.vocabularies.UI.v1.ReferenceFacet">
              <PropertyValue Property="Target" AnnotationPath="@com.sap.vocabularies.UI.v1.FieldGroup#General"/>
              <PropertyValue Property="Label" String="Основная информация"/>
            </Record>
          </Collection>
        </PropertyValue>
      </Record>
    </Collection>
  </Annotation>
</Annotations>

<!-- Пример FieldGroup -->
<Annotations Target="MyService.EntityType">
  <Annotation Term="com.sap.vocabularies.UI.v1.FieldGroup" Qualifier="General">
    <Record>
      <PropertyValue Property="Label" String="Основная информация"/>
      <PropertyValue Property="Data">
        <Collection>
          <Record Type="com.sap.vocabularies.UI.v1.DataField">
            <PropertyValue Property="Value" Path="Field1"/>
          </Record>
          <Record Type="com.sap.vocabularies.UI.v1.DataField">
            <PropertyValue Property="Value" Path="Field2"/>
          </Record>
        </Collection>
      </PropertyValue>
    </Record>
  </Annotation>
</Annotations>

4. Экшн-кнопки (Actions)

Добавляют кнопки для действий (например, Approve, Reject) в таблице или на Object Page.

<Annotations Target="MyService.EntityType">
  <Annotation Term="com.sap.vocabularies.UI.v1.LineItem">
    <Collection>
      <!-- ... другие поля ... -->
      <Record Type="com.sap.vocabularies.UI.v1.DataFieldForAction">
        <PropertyValue Property="Label" String="Approve"/>
        <PropertyValue Property="Action" String="MyService.EntityType_Approve"/>
      </Record>
    </Collection>
  </Annotation>
</Annotations>

5. ValueHelp (ValueList)

Определяет справочник значений для поля (value help/F4).

<Annotations Target="MyService.EntityType/Field1">
  <Annotation Term="com.sap.vocabularies.Common.v1.ValueList">
    <Record Type="com.sap.vocabularies.Common.v1.ValueListType">
      <PropertyValue Property="CollectionPath" String="ValueHelpEntitySet"/>
      <PropertyValue Property="Parameters">
        <Collection>
          <Record Type="com.sap.vocabularies.Common.v1.ValueListParameterOut">
            <PropertyValue Property="LocalDataProperty" PropertyPath="Field1"/>
            <PropertyValue Property="ValueListProperty" String="ID"/>
          </Record>
          <Record Type="com.sap.vocabularies.Common.v1.ValueListParameterDisplayOnly">
            <PropertyValue Property="ValueListProperty" String="Description"/>
          </Record>
        </Collection>
      </PropertyValue>
    </Record>
  </Annotation>
</Annotations>

6. Отображение текста вместо ID (Text)

Позволяет показывать текст вместо технического ключа.

<Annotations Target="MyService.EntityType/Field1">
  <Annotation Term="com.sap.vocabularies.Common.v1.Text" Path="DescriptionField"/>
</Annotations>

7. Критичность (Criticality)

Используется для отображения статусов (цвета, иконки) в таблицах и объектах.

<Annotations Target="MyService.EntityType/StatusField">
  <Annotation Term="com.sap.vocabularies.UI.v1.Criticality" EnumMember="com.sap.vocabularies.UI.v1.CriticalityType/Negative"/>
</Annotations>

8. Заголовок и описание объекта (HeaderInfo)

Определяет, какие поля используются как заголовок и описание на Object Page.

<Annotations Target="MyService.EntityType">
  <Annotation Term="com.sap.vocabularies.UI.v1.HeaderInfo">
    <Record>
      <PropertyValue Property="TypeName" String="Документ"/>
      <PropertyValue Property="TypeNamePlural" String="Документы"/>
      <PropertyValue Property="Title">
        <Record Type="com.sap.vocabularies.UI.v1.DataField">
          <PropertyValue Property="Value" Path="ID"/>
        </Record>
      </PropertyValue>
      <PropertyValue Property="Description">
        <Record Type="com.sap.vocabularies.UI.v1.DataField">
          <PropertyValue Property="Value" Path="Description"/>
        </Record>
      </PropertyValue>
    </Record>
  </Annotation>
</Annotations>

9. SemanticKey

Определяет ключевые поля для навигации и уникальности объекта.

<Annotations Target="MyService.EntityType">
  <Annotation Term="com.sap.vocabularies.Common.v1.SemanticKey">
    <Collection>
      <PropertyPath>ID</PropertyPath>
    </Collection>
  </Annotation>
</Annotations>

10. Дополнительные полезные аннотации

  • UI.Hidden — скрыть поле на UI
  • UI.Importance — важность поля (High, Medium, Low)
  • UI.DataPoint — визуализация числовых значений (например, прогресс-бар)
  • UI.Chart — определение графиков
  • UI.PresentationVariant — сортировка, группировка, топ-N
  • UI.SelectionPresentationVariant — комбинация фильтров и представления

Полезные ссылки

Примечание:
Аннотации можно добавлять как в backend (CDS, MPC_EXT), так и в локальных XML-файлах (например, annotation.xml), которые подключаются через manifest.json.

См. также