WEBAPP+Документация: Примеры и документация P8PIndicator

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 (
+        <div>
+            <P8PIndicator .../>
+        </div>
+    );
+}
+```
+
+**Свойства**
+
+`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. Тем не менее, при разработке пользовательских интерфейсов панелей важно придерживаться предложенных ниже правил. Это позволит создавать их в едином ключе и упростит работу конечного пользователя при их освоении.

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 (
+        <div style={STYLES.CONTAINER}>
+            <Typography sx={STYLES.TITLE} variant={"h6"}>
+                {title}
+            </Typography>
+            <Divider>Иконка</Divider>
+            <Stack direction={"row"} spacing={2} p={5}>
+                {/* Индикатор (без иконки) */}
+                <P8PIndicator caption={"Без иконки"} value={10} />
+                {/* Индикатор (с иконкой 1) */}
+                <P8PIndicator caption={"С иконкой - Back Hand"} value={20} icon={"back_hand"} />
+                {/* Индикатор (с иконкой 2) */}
+                <P8PIndicator caption={"С иконкой - Scoreboard"} value={30} icon={"scoreboard"} />
+            </Stack>
+            <Divider>Состояние</Divider>
+            <Stack direction={"row"} spacing={2} p={5}>
+                {/* Индикатор (нейтральный) */}
+                <P8PIndicator caption={"Нейтральное состояние"} value={10} icon={"sentiment_neutral"} />
+                {/* Индикатор (позитивный) */}
+                <P8PIndicator caption={"Позитивное состояние"} value={20} state={P8P_INDICATOR_STATE.OK} icon={"check_circle"} />
+                {/* Индикатор (пограничный) */}
+                <P8PIndicator caption={"Пограничное состояние"} value={30} state={P8P_INDICATOR_STATE.WARN} icon={"warning"} />
+                {/* Индикатор (негативный) */}
+                <P8PIndicator caption={"Негативное состояния"} value={40} state={P8P_INDICATOR_STATE.ERR} icon={"dangerous"} />
+            </Stack>
+            <Divider>Скругление</Divider>
+            <Stack direction={"row"} spacing={2} p={5}>
+                {/* Индикатор (скругленный) */}
+                <P8PIndicator caption={"Скругленный"} />
+                {/* Индикатор (квадратный) */}
+                <P8PIndicator caption={"Квадрадтный"} square={true} />
+            </Stack>
+            <Divider>Парение</Divider>
+            <Stack direction={"row"} spacing={2} p={5}>
+                {/* Индикатор (парение - 0) */}
+                <P8PIndicator caption={"Парение"} value={0} state={P8P_INDICATOR_STATE.OK} elevation={0} />
+                {/* Индикатор (парение - 3) */}
+                <P8PIndicator caption={"Парение (по умолчанию)"} value={3} state={P8P_INDICATOR_STATE.WARN} elevation={3} />
+                {/* Индикатор (парение - 6) */}
+                <P8PIndicator caption={"Парение"} value={6} state={P8P_INDICATOR_STATE.OK} elevation={6} />
+                {/* Индикатор (парение - 12) */}
+                <P8PIndicator caption={"Парение"} value={12} state={P8P_INDICATOR_STATE.OK} elevation={12} />
+                {/* Индикатор (парение - 18) */}
+                <P8PIndicator caption={"Парение"} value={18} state={P8P_INDICATOR_STATE.OK} elevation={18} />
+            </Stack>
+            <Divider>Исполнение</Divider>
+            <Stack direction={"row"} spacing={2} p={5}>
+                {/* Индикатор (парение) */}
+                <P8PIndicator caption={"Парящий (по умолчанию)"} value={123} />
+                {/* Индикатор (рамка) */}
+                <P8PIndicator caption={"Рамка"} value={321} variant={P8P_INDICATOR_VARIANT.OUTLINED} />
+            </Stack>
+            <Divider>Подсказка</Divider>
+            <Stack direction={"row"} spacing={2} p={5}>
+                {/* Индикатор (подсказка без форматирования) */}
+                <P8PIndicator
+                    caption={"Подсказка (без форматирования)"}
+                    value={42}
+                    icon={"desktop_windows"}
+                    hint={"Ответ на главный вопрос жизни, вселенной и всего такого..."}
+                />
+                {/* Индикатор (подсказка с форматирование) */}
+                <P8PIndicator
+                    caption={"Подсказка (с форматированием)"}
+                    value={3.14}
+                    icon={"radio_button_unchecked"}
+                    hint={`Математическая <b>постоянная</b>, равная <b style='color:red'>отношению</b> <b style='color:green'>длины окружности</b> 
+                         к её <b style='color:blue'>диаметру</b>: 
+                         <p style='text-align: center'>&#960; = <span style='color:green'>L</span>/<span style='color:blue'>d</span></p>`}
+                />
+            </Stack>
+            <Divider>Активность</Divider>
+            <Stack direction={"row"} spacing={2} p={5}>
+                {[P8P_INDICATOR_STATE.UNDEFINED, P8P_INDICATOR_STATE.OK, P8P_INDICATOR_STATE.WARN, P8P_INDICATOR_STATE.ERR].map(
+                    (indicatorState, i) => (
+                        <P8PIndicator
+                            key={i}
+                            caption={`Нажми на меня #${i + 1}`}
+                            value={i + 1}
+                            state={indicatorState}
+                            icon={"chat"}
+                            onClick={() => showMsgInfo(`Нажатие на индикатор #${i + 1}`)}
+                            hint={`Подсказка индикатора #${i + 1}`}
+                        />
+                    )
+                )}
+            </Stack>
+            <Divider>Пользовательские цвета</Divider>
+            <Stack direction={"row"} spacing={2} p={5}>
+                {[
+                    ["yellow", "black"],
+                    ["darkred", "yellow"],
+                    ["orange", "darkblue"],
+                    ["magenta", "darkmagenta"]
+                ].map((userColor, i) => (
+                    <P8PIndicator
+                        key={i}
+                        caption={`Текст: ${userColor[0]}, Заливка: ${userColor[1]}`}
+                        value={i + 1}
+                        state={P8P_INDICATOR_STATE.WARN}
+                        icon={"palette"}
+                        color={userColor[0]}
+                        backgroundColor={userColor[1]}
+                    />
+                ))}
+            </Stack>
+        </div>
+    );
+};
+
+//Контроль свойств - Пример: Индикатор "P8PIndicator"
+Indicator.propTypes = {
+    title: PropTypes.string.isRequired
+};
+
+//----------------
+//Интерфейс модуля
+//----------------
+
+export { Indicator };

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 }
 };
 
 //Стили