Темы оформления мобильного приложения

Материал из PayControl Wiki
Версия от 15:53, 15 февраля 2021; A.bursakov (обсуждение | вклад) (→‎Описание состава файлов тем)
Перейти к: навигация, поиск

Описание состава файлов тем

v5.0

Структура файла темы

.
├── locales.json // optional
├── base
│   ├── fonts
│   │   ├── fontName1.ttf
│   │   └── fontName2.ttf
│   ├── text
│   │   └── about.html
│   ├── images
│   │   ├── imageName1.png
│   │   ├── imageName2.png
│   │   └── imageName3.png
│   └── theme.json
├── ru-RU
│   ├── fonts
│   │   └── ...
│   ├── text
│   │   └── ...
│   ├── images
│   │   └── ...
│   └── theme.json
├── en-US
│   ├── fonts
│   │   └── ...
│   ├── text
│   │   └── ...
│   ├── images
│   │   └── ...
│   └── theme.json
└── ...
    ├── fonts
    │   └── ...
    ├── text
    │   └── ...
    ├── images
    │   └── ...
    └── theme.json

Каждая тема состоит из папок с локализованными версиями тем и опционального файла locales.json, который описывает какую версию темы использовать для определенных региональных параметров.

Локализация

Каждая тема может включать базовую локализацию base, а так же локализации для других языков и регионов (ru-RU, en-US, ...). Приложение должно подтягивать информацию из локализированной версии темы. Если информация в локализированной версии отсутствует — она подтягивается из base. Если отсутствует base, то из локализированной версии дефолтной темы или Base-версии дефолтной темы.

Файл locales.json опционален. Он необходим, если нужно сопоставить разные региональные идентификаторы с определённым идентификатором. Например, если для Украины, Беларуси нужно использовать русскую версию темы, то файл будет выглядеть так: 

{
    "ru-UA": "ru-RU",
    "be-BY": "ru-RU"
}

Структура локализированной версии

base // ru-RU, en-US, ...
│   ├── fonts
│   │   ├── fontName1.ttf
│   │   └── fontName2.ttf
│   ├── text
│   │   └── about.html
│   ├── images
│   │   ├── imageName1.png
│   │   ├── imageName2.png
│   │   └── imageName3.png
│   └── theme.json

Каждая локализация содержит файл theme.json, который описывает тему, и папки с ресурсами (images, fonts, text).


Структура theme.json

Набор установленных значений дан в качестве примера. 

{
    "images": {
        "menuImage": "logo.png",
        ...
    },
    "fonts": {
        "default": "fontName.ttf"
    },
    "colors": {
	"text": "#FFFFFF",
	"error": "#FF0000",
	"success": "#0000FF",
	"background": "#110011",
	"menuBackground": "#00ff00",
        ...
    },
    "sizes": {
        "large": 20.0,
        "default": 16.0,
        "small": 14.0
        ...
    },
    "elements": {
        "heading": {
            "fontSize": "large",
            "fontWeight": "medium",
            "textColor": "text"
        },
        "caption": {
            "fontSize": "default",
            "fontWeight": "medium",
            "textColor": "text"
        },
        "body": {
            "fontSize": "default",
            "fontWeight": "regular",
            "textColor": "text"
        },
        "footnote": {
            "fontSize": "small",
            "fontWeight": "regular",
            "textColor": "text"
        },
        "error": {
            "fontSize": "small",
            "fontWeight": "regular",
            "textColor": "text",
            "iconColor": "iconColor"
        },
        "menu": {
            "fontSize": "default",
            "fontWeight": "regular",
            "textColor": "menuText",
            "iconColor": "menuIcons"
        },
        "primaryButton": {
            "fontSize": "default",
            "fontWeight": "medium",
            "textColor": "background",
            "backgroundNormalColor": "button"
        },
        "secondaryButton": {
            "fontSize": "default",
            "fontWeight": "medium",
            "textColor": "text",
            "iconColor": "text",
            "backgroundNormalColor": "secondaryButton"
        },
        "confirmationButton": {
            "fontSize": "default",
            "fontWeight": "medium",
            "textColor": "text",
            "backgroundNormalColor": "button"
        },
        "declineButton": {
            "fontSize": "default",
            "fontWeight": "medium",
            "textColor": "text",
            "backgroundNormalColor": "button"
        },
        "bar": {
            "textColor": "barText",
            "iconColor": "text",
            "backgroundNormalColor": "background"
        },
        "timer": {
            "fontSize": "timer",
            "fontWeight": "medium",
            "textColor": "text"
        },
        "confirmation": {
            "fontSize": "confirmation",
            "fontWeight": "regular",
            "textColor": "text"
        }
    },
    "feedback": "feedback@paycontrol.ru"
}
  • images: Список картинок. Каждому ключу соответствует определённая картинка из папки images. Есть системные ключи (список ниже), которые можно перезаписывать (тогда картинка в приложении соответствующая ключу поменяется), но можно добавлять и свои. Ключи картинок можно использовать в описании элементов.
  • fonts: Список шрифтов. Каждому ключу соответствует определённый шрифт в папке fonts. В описании элементов указывается непосредственно ключ шрифта, а не конкретное значение. В дефолтной теме приложения словарь пустой — используется системный шрифт. Но если перезаписать ключ default на кастомный шрифт, то шрифт приложения должен поменяться на указанный.
  • colors: Список цветов. Каждому ключу соответствует определённый цвет. В описании элементов указывается непосредственно ключ цвета, а не конкретное значение. Есть системные ключи (например background, весь список ниже), если их перезаписать, то поменяется цвет у элементов приложения, соответствующих ключу. Можно указывать свои ключи и значения, а потом использовать ключ в описании элементов.
  • sizes: Список размеров текста. Каждому ключу соответствует определённые размер. В описании элементов указывается непосредственно ключ размера, а не конкретное значение. Есть системные ключи (например default, весь список ниже), если их перезаписать, то поменяется размер текста у элементов, которые используют данные ключ. Можно указывать свои ключи и значения, а потом использовать их в описании элементов.
  • elements: Описание стилей всех элементов приложения. Список элементов ограничен, добавлять можем только мы. Создатель темы может лишь перезаписать нужные ему значения. Каждый элемент содержит ограниченный набор полей.

Системные значения images

Названия картинок даны в качестве примера. 

"images": {
    "main":   "key_large.png",   // Основная картинка приложения (там где сейчас ключ на главном экране)
    "menu":   "logo_small.png",  // Логотип в боковом меню
    "keys":   "key_small.png",   // Логотип в списке ключей
    "bar":    "logo_small.png",  // Логотип в AppBar'е на Android или NavigationBar'е на iOS
    "launch": "logo.png"         // Логотип на сплешскрине
}

Системные значения fonts

Название шрифта дано в качестве примера. В дефолтной теме приложения этого ключа нет, т.к. используется системный шрифт. Если добавить данные ключ-значение — то шрифт приложения поменяется на указанный. 

"fonts": {
    "default": "font.ttf" // Глобальный шрифт приложения
}

Системные значения sizes

Значения, которые используются по-умолчанию. Если любое значение изменить — поменяется размер во всех элементах, которые его используют. 

"sizes": {
    "large": 20.0,
    "default": 16.0,
    "small": 14.0,
    "timer": 24.0,
    "confirmation": 54.0
}

Системные значения colors

Значения указаны в качестве примера. Цвета указываются в формате hex, могут использоваться как RGB, так и RGBA. 

"colors": {
    "text":           "#FFFFFF",    // Цвет основного текста
    "error":          "#FF0000",    // Цвет для элементов указывающих на ошибку
    "success":        "#00FF00",    // Цвет для элементов указывающих на успешное действие
    "background":     "#0000FF",    // Цвет фона приложения
    "menuBackground": "#FFFFFF",    // Цвет фона в боковом меню
    "menuHeader":     "#0000FF",    // Цвет шапки бокового меню
    "menuIcons":      "#AAAAAA",    // Цвет иконок в боковом меню,
    "menuText":       "#000000",    // Цвет разделов в боковом меню
    "bar":            "#FFFFFF",    // Цвет фона AppBar'а/NavigationBar'а
    "timer":          "#FFFFFF",    // Цвет таймера обратного отсчёта
    "statusbar":      "#0000FF",    // Цвет фона статусбара (для Android)
    "button":         "#FFFFFF",    // Цвет фона кнопки в нормальном состоянии
    "secondaryButton":"#0000FF",    // Цвет вторичных кнопок
    "badge":          "#F44336"     // Цвет фона бейджа
}

Системные значения sizes

"sizes": {
    "large":        20.0,    // В основном используется для заголовков
    "default":      16.0,    // Основной размер текста, кнопок, разделов меню
    "small":        14.0,    // Для подписей к текстовым полям, ошибкам
    "timer":        24.0,    // Размер таймера обратного отсчёта
    "confirmation": 54.0     // Максимальный размер кода подтверждения
},

Элементы приложения elements

Значения указаны в качестве примера. Цвета указываются в формате hex, могут использоваться как RGB, так и RGBA. 

"elements": {
    "heading":               { ... },    // Крупные заголовки
    "caption":               { ... },    // Мелкие заголовки (заголовки текстовых полей)
    "body":                  { ... },    // Основной текст
    "footnote":              { ... },    // Сноски и примечания
    "error":                 { ... },    // Текст ошибок
    "menu":                  { ... },    // Разделы бокового меню
    "primaryButton":         { ... },    // Стиль основных кнопок (например, «Далее»)
    "secondaryButton":       { ... },    // Стиль дополнительных кнопок (например, выбор типа пароля)
    "confirmationButton":    { ... },    // Кнопка подтверждения
    "declineButton":         { ... },    // Кнопка отклонения
    "bar":                   { ... },    // Стиль AppBar'a или NavigationBar'a
    "timer":                 { ... },    // Стиль обратного отсчёта
    "confirmation":          { ... },    // Стиль кода подтверждения
    "badge":                 { ... }     // Стиль контента бейджа
}

Описание стиля элемента

Эти ключи опциональны и есть у каждого элемента. Значения указаны в качестве примера. 

"elementName": 
{
    "font":                      "fontKey",      // Ключ шрифта из списка fonts
    "fontSize":                  "sizeKey",       // Ключ размера из списка sizes
    "fontWeight":                "regular",      // Начертание шрифта
    "textColor":                 "text",         // Ключ цвета из списка colors
    "iconColor":                 "iconColor",    // Цвет иконки, если она присутствует у элемента
    "icon":                      "iconKey",      // Ключ изображения из списка images
    "backgroundNormalColor":     "button",       // Цвет фона в нормальном состоянии
    "backgroundPressedColor":    "button",       // Цвет фона в нажатом состоянии. Если пусто — используется системное поведение. Например, в iOS — полупрозрачный цвет нормального состояния
    "backgroundDisabledColor":   "button",       // Цвет фона в неактивном состоянии. Если пусто — используется системное поведение. Например, в iOS — почти прозрачный цвет нормального состояния
}

Обратная связь feedback

В качестве значения указывается email. У каждой локализации может быть свой адрес. 

{
    "feedback": "feedback@paycontrol.ru"
}

Файлы с текстом из директории text

Папка text содержит файлы с текстом для различных экранов. Сейчас есть только about.html, он подставляется на экран about. Но в дальнейшем могут появится другие.

Правила получения значений

Т.к. все значения опциональны, то значения берутся по цепочке:

Локализированное значение > Значение из base > Локализированное значение из дефолтной темы > Значение из base дефолтной темы > Системной значение (Там где возможно. Например, для AppBar/NavigationBar)

Публикация темы оформления на сервере PayControl

Скины размещаются на Interaction-Rest сервер (PCIS Internal).

Для приложения PayControl Classic (v3)

  1. Убедиться, что название файла скина имеет вид {systemid}.zip, где {systemid} - идентификатор системы, для которой размещается скин;
  2. Разместить не распаковывая файл скина на сервере PCIS External в папке (создав её при необходимости):
    • Linux
      /opt/wildfly/paycontrol_skins
    • Windows
      C:\wildfly\paycontrol_skins

После добавления скина на сервер, он должен стать доступным по адресу: 

http{s}://{servername}/PayControl-interaction-rest/skin/{systemid}

Для приложения PayControl (v5)

  1. Убедиться, что название файла скина имеет вид {systemid}.zip, где {systemid} - идентификатор системы, для которой размещается скин;
  2. Разместить не распаковывая файл скина на сервере PCIS External в папке (создав её при необходимости):
    • Linux
      /opt/wildfly/pc_themes/v5
    • Windows
      C:\wildfly\pc_themes\v5

После добавления скина на сервер, он должен стать доступным по адресу: 

http{s}://{servername}/pc-client-api/themes/v5/{systemid}

Для приложения PayControl (v5.2)

  1. Убедиться, что название файла скина имеет вид {systemid}.zip, где {systemid} - идентификатор системы, для которой размещается скин;
  2. Разместить не распаковывая файл скина на сервере PCIS External в папке (создав её при необходимости):
    • Linux
      /opt/wildfly/pc_themes/v52
    • Windows
      C:\wildfly\pc_themes\v52

После добавления скина на сервер, он должен стать доступным по адресу: 

http{s}://{servername}/pc-client-api/themes/v52/{systemid}
Источник — «https://repo.paycontrol.org/wiki/index.php?title=Темы_оформления_мобильного_приложения&oldid=479»