diff --git a/README.md b/README.md index e2e81f0..fbd11d6 100644 --- a/README.md +++ b/README.md @@ -2941,6 +2941,61 @@ export { Cyclogram }; Полные актуальные исходные коды примеров можно увидеть в "db/PKG_P8PANELS_SAMPLES.pck" и "app/panels/samples/cyclogram.js" данного репозитория соответственно. +##### Индикатор "P8PIndicator" + +Компонент предназначен для отображения данных в виде индикатора. Поддерживается: + +- Цветовая индикация предопределёнными цветами в зависимости от состояния (не определено, позитивное, негативное, пограничное) +- Цветовая индикация пользовательскими цветами +- Обработка нажатий +- Отображение иконки +- Упрвление внешним видом (парение, рамка) +- Интерактивные подсказки + +![Пример P8PIndicator](docs/img/74.png) + +**Подключение** + +Клиентская часть индикатора реализована в компоненте `P8PIndicator`, объявленном в "app/components/p8p_indicator". Для использования компонента на панели его необходимо импортировать: + +``` +import { P8PIndicator } from "../../components/p8p_indicator"; + +const MyPanel = () => { + return ( +
+ +
+ ); +} +``` + +**Свойства** + +`caption` - обязательный, строка, подпись индикатора\ +`value` - обязательный, строка, значение индикатора\ +`icon` - необязательный, строка, код иконки индикатора из символов шрифта [Google Material Icons](https://fonts.google.com/icons?icon.set=Material+Icons) (по умолчанию - не указана, если указана - отображается в левой части области индикатора)\ +`state` - необязательный, строка, состояние индикатора, принимает значения `UNDEFINED|OK|ERR|WARN` (по умолчанию - `UNDEFINED`, см. константу `P8P_INDICATOR_STATE` в исходном коде компонента), определяет цвет заливки индикатора, если не указаны пользовательские цвета (см. ниже свойства `backgroundColor`и`color`)\ +`square` - необязательный, логический, определяет необходимость скругления углов области индикатора (по умолчанию - `false`)\ +`elevation` - необязательный, число, высота парения индикатора (по умолчанию - 3, используется только при `variant = 'elevation'`)\ +`variant` - необязательный, строка, вариант исполнения, принимает значения `elevation|outlined` (по умолчанию - `elevation`, см. константу `P8P_INDICATOR_VARIANT` в исходном коде компонента), определяет внешний вид индикатора - парящая область или область с рамкой\ +`hint` - необязательный, строка, текст подсказки для индикатора (если указан - слева от значения индикатора формируется кнопка открытия диалога с текстом подсказки, поддерживается HTML-форматирование)\ +`onClick` - необязательный, функция, будет вызвана при нажатии пользователем на индикатор (если указана - индикатор формируется в виде кнопки), сигнатура функции `f()`, результат функции не интерпретируется\ +`backgroundColor` - необязательный, строка, HTML-код пользовательского цвета фона, если указан - будет использован (вне зависимости от `state`) для заливки области индикатора (по умолчанию - не указан) \ +`color` - необязательный, строка, HTML-код пользовательского цвета шрифта, если указан - будет использован (вне зависимости от `state`) для значения, подписи и иконки индикатора (по умолчанию - не указан) + +**API на сервере БД** + +Компонент `P8PIndicator` требует от разработчика передачи данных в определённом формате. С целью снижения трудозатрат на приведение собранных хранимым объектом данных Системы к форматам, потребляемым `P8PIndicator`, реализован специальный API на стороне сервера БД. + +Для индикатора это (см. детальные описания программных интерфейсов в пакете `PKG_P8PANELS_VISUAL`): +`PKG_P8PANELS_VISUAL.TINDICATOR_MAKE` - функция, инициализация индикатора, возвращает объект для хранения его описания\ +`PKG_P8PANELS_VISUAL.TINDICATOR_TO_XML` - функция, производит сериализацию объекта, описывающего индикатор, в специальный XML-формат, корректно интерпретируемый клиентским компонентом `P8PIndicator` при передаче в WEB-приложение + +**Пример** + +Полный актуальный исходный код примера можно увидеть в "app/panels/samples/indicator.js" данного репозитория. + ### Ограничения дизайна пользовательского интерфейса Фреймворк позволяет реализовать любые пользовательские интерфейсы, вёрстка которых не противоречит возможностям современного HTML. Тем не менее, при разработке пользовательских интерфейсов панелей важно придерживаться предложенных ниже правил. Это позволит создавать их в едином ключе и упростит работу конечного пользователя при их освоении. diff --git a/app/panels/samples/indicator.js b/app/panels/samples/indicator.js new file mode 100644 index 0000000..61bbbe5 --- /dev/null +++ b/app/panels/samples/indicator.js @@ -0,0 +1,156 @@ +/* + Парус 8 - Панели мониторинга - Примеры для разработчиков + Пример: Индикатор "P8PIndicator" +*/ + +//--------------------- +//Подключение библиотек +//--------------------- + +import React, { useContext } from "react"; //Классы React +import PropTypes from "prop-types"; //Контроль свойств компонента +import { Typography, Stack, Divider } from "@mui/material"; //Интерфейсные элементы +import { MessagingСtx } from "../../context/messaging"; //Контекст сообщений +import { P8P_INDICATOR_VARIANT, P8P_INDICATOR_STATE, P8PIndicator } from "../../components/p8p_indicator"; //Индикатор + +//--------- +//Константы +//--------- + +//Стили +const STYLES = { + CONTAINER: { textAlign: "center", paddingTop: "20px" }, + TITLE: { paddingBottom: "15px" }, + DIVIDER: { margin: "15px" } +}; + +//----------- +//Тело модуля +//----------- + +//Пример: Индикатор "P8PIndicator" +const Indicator = ({ title }) => { + //Подключение к контексту сообщений + const { showMsgInfo } = useContext(MessagingСtx); + + //Генерация содержимого + return ( +
+ + {title} + + Иконка + + {/* Индикатор (без иконки) */} + + {/* Индикатор (с иконкой 1) */} + + {/* Индикатор (с иконкой 2) */} + + + Состояние + + {/* Индикатор (нейтральный) */} + + {/* Индикатор (позитивный) */} + + {/* Индикатор (пограничный) */} + + {/* Индикатор (негативный) */} + + + Скругление + + {/* Индикатор (скругленный) */} + + {/* Индикатор (квадратный) */} + + + Парение + + {/* Индикатор (парение - 0) */} + + {/* Индикатор (парение - 3) */} + + {/* Индикатор (парение - 6) */} + + {/* Индикатор (парение - 12) */} + + {/* Индикатор (парение - 18) */} + + + Исполнение + + {/* Индикатор (парение) */} + + {/* Индикатор (рамка) */} + + + Подсказка + + {/* Индикатор (подсказка без форматирования) */} + + {/* Индикатор (подсказка с форматирование) */} + постоянная, равная отношению длины окружности + к её диаметру: +

π = L/d

`} + /> + + Активность + + {[P8P_INDICATOR_STATE.UNDEFINED, P8P_INDICATOR_STATE.OK, P8P_INDICATOR_STATE.WARN, P8P_INDICATOR_STATE.ERR].map( + (indicatorState, i) => ( + showMsgInfo(`Нажатие на индикатор #${i + 1}`)} + hint={`Подсказка индикатора #${i + 1}`} + /> + ) + )} + + Пользовательские цвета + + {[ + ["yellow", "black"], + ["darkred", "yellow"], + ["orange", "darkblue"], + ["magenta", "darkmagenta"] + ].map((userColor, i) => ( + + ))} + +
+ ); +}; + +//Контроль свойств - Пример: Индикатор "P8PIndicator" +Indicator.propTypes = { + title: PropTypes.string.isRequired +}; + +//---------------- +//Интерфейс модуля +//---------------- + +export { Indicator }; diff --git a/app/panels/samples/samples.js b/app/panels/samples/samples.js index 3746450..57a75ef 100644 --- a/app/panels/samples/samples.js +++ b/app/panels/samples/samples.js @@ -19,6 +19,7 @@ import { Chart } from "./chart"; //Пример: Графики "P8PChart" import { Gantt } from "./gantt"; //Пример: Диаграмма Ганта "P8PGantt" import { Svg } from "./svg"; //Пример: Интерактивные изображения "P8PSVG" import { Cyclogram } from "./cyclogram"; //Пример: Циклограмма "P8PCyclogram" +import { Indicator } from "./indicator"; //Пример: Индикатор "P8PIndicator" //--------- //Константы @@ -34,7 +35,8 @@ const MODES = { CHART: { name: "CHART", caption: 'Графики "P8PChart"', component: Chart }, GANTT: { name: "GANTT", caption: 'Диаграмма Ганта "P8PGantt"', component: Gantt }, SVG: { name: "SVG", caption: 'Интерактивные изображения "P8PSVG"', component: Svg }, - CYCLOGRAM: { name: "CYCLOGRAM", caption: 'Циклограмма "P8PCyclogram"', component: Cyclogram } + CYCLOGRAM: { name: "CYCLOGRAM", caption: 'Циклограмма "P8PCyclogram"', component: Cyclogram }, + INDICATOR: { name: "INDICATOR", caption: 'Индикатор "P8PIndicator"', component: Indicator } }; //Стили diff --git a/docs/Image Sources.pptx b/docs/Image Sources.pptx index cd2d093..9d56981 100644 Binary files a/docs/Image Sources.pptx and b/docs/Image Sources.pptx differ diff --git a/docs/img/74.png b/docs/img/74.png new file mode 100644 index 0000000..db752f4 Binary files /dev/null and b/docs/img/74.png differ