From d2eab9eda33c56c29610723a34cd5403d0a843d5 Mon Sep 17 00:00:00 2001 From: Hadi Khazaee Asl Date: Tue, 1 Sep 2026 22:26:02 +0330 Subject: [PATCH] last ... --- .../AppexChartOptionsDocumentation.html | 1504 +++++++++++++++++ Documents/Markdown/README.md | 172 ++ Modules/xFrameworkComponentsHolder | 2 +- 3 files changed, 1677 insertions(+), 1 deletion(-) create mode 100644 Documents/Markdown/AppexChartOptionsDocumentation.html create mode 100644 Documents/Markdown/README.md diff --git a/Documents/Markdown/AppexChartOptionsDocumentation.html b/Documents/Markdown/AppexChartOptionsDocumentation.html new file mode 100644 index 0000000..eddc4d2 --- /dev/null +++ b/Documents/Markdown/AppexChartOptionsDocumentation.html @@ -0,0 +1,1504 @@ + + + + + + مستند جامع تحلیل ApexOptions در ApexCharts + + + + + + + +
+ +
+
+

مستند جامع تحلیل ApexOptions در ApexCharts

+

📅 تاریخ تهیه: دوشنبه ۱۱ شهریور ۱۴۰۴

+

📌 موضوع: بررسی تفصیلی فیلدهای ApexOptions

+
+
+ شرکت فن آوران ساحر علم
+ https://saherelm.ir
+ توسعه‌دهنده: هادی خزاعی اصل +
+
+ + +

۱. مقدمه

+

+ مدل ApexOptions قلب تپنده کتابخانه ApexCharts است و تمام تنظیمات نمودار را در بر می‌گیرد. این مدل شامل ۲۵ فیلد اصلی است که هر کدام بخش خاصی از نمودار را کنترل می‌کنند. در این سند، هر فیلد به همراه زیرفیلدها، توضیحات و مثال‌های کاربردی بررسی شده است. +

+ +
+ 📌 نکته: تمام فیلدها اختیاری هستند و در صورت عدم تعریف، از مقادیر پیش‌فرض ApexCharts استفاده می‌شود. +
+ + +

۲. جدول کلی فیلدهای ApexOptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ردیفنام فیلدتوضیح
۱annotationsحاشیه‌نویسی‌ها (خطوط، نقاط، متن‌ها)
۲chartتنظیمات اصلی نمودار (نوع، ابعاد، انیمیشن)
۳colorsرنگ‌های سری‌های داده
۴dataLabelsبرچسب‌های داده روی نقاط
۵drilldownناوبری عمیق (Drilldown)
۶fillپرکننده (رنگ، گرادیانت، الگو)
۷forecastDataPointsنقاط داده پیش‌بینی
۸gridشبکه‌بندی نمودار
۹labelsبرچسب‌های نمودار
۱۰legendراهنمای نمودار
۱۱markersنشانگرهای نقاط
۱۲noDataپیام عدم وجود داده
۱۳pluginsافزونه‌ها (Weave)
۱۴plotOptionsگزینه‌های خاص هر نوع نمودار
۱۵responsiveتنظیمات واکنش‌گرا
۱۶seriesسری‌های داده
۱۷statesحالت‌های مختلف (hover, active)
۱۸strokeخطوط نمودار
۱۹subtitleزیرعنوان
۲۰themeتم (روشن/تاریک)
۲۱titleعنوان نمودار
۲۲tooltipTooltip (راهنمای شناور)
۲۳xaxisمحور X
۲۴yaxisمحور Y
+ + +

۳. بررسی تفصیلی فیلدها

+ + +

۳.۱. فیلد annotations - حاشیه‌نویسی‌ها

+

این فیلد برای اضافه کردن حاشیه‌نویسی‌های سفارشی (خطوط، نقاط، متن‌ها) به نمودار استفاده می‌شود.

+ +

زیرفیلدها:

+ + +

ساختار XAxisAnnotations:

+ 
xaxis?: [
+  {
+    id?: number | string;
+    x?: null | number | string;
+    x2?: null | number | string;
+    strokeDashArray?: number;
+    fillColor?: string;
+    borderColor?: string;
+    borderWidth?: number;
+    opacity?: number;
+    offsetX?: number;
+    offsetY?: number;
+    label?: {
+      text?: string | string[];
+      textAnchor?: string;
+      offsetX?: number;
+      offsetY?: number;
+      style?: {
+        background?: string;
+        color?: string;
+        fontSize?: string;
+        fontFamily?: string;
+        fontWeight?: string | number;
+        padding?: { left?: number; right?: number; top?: number; bottom?: number; };
+      };
+    };
+  }
+]
+ +

مثال کاربردی:

+ 
annotations: {
+  xaxis: [{
+    x: new Date('2024-06-01').getTime(),
+    borderColor: '#FF0000',
+    label: {
+      borderColor: '#FF0000',
+      style: { color: '#fff', background: '#FF0000' },
+      text: 'تاریخ مهم'
+    }
+  }],
+  yaxis: [{
+    y: 50,
+    borderColor: '#00FF00',
+    label: { text: 'خط هدف', style: { color: '#00FF00' } }
+  }],
+  points: [{
+    x: 'فروردین',
+    y: 50,
+    marker: { size: 8, fillColor: '#FF0000' },
+    label: { text: 'نقطه مهم' }
+  }]
+}
+ + +

۳.۲. فیلد chart - تنظیمات اصلی نمودار

+

این فیلد مهم‌ترین بخش تنظیمات است و رفتار کلی نمودار را کنترل می‌کند.

+ +

زیرفیلدهای اصلی:

+ + +

ساختار chart:

+ 
chart: {
+  width?: string | number;
+  height?: string | number;
+  type?: 'line' | 'area' | 'bar' | 'pie' | 'donut' | 'radialBar' | 
+         'scatter' | 'bubble' | 'heatmap' | 'candlestick' | 
+         'boxPlot' | 'violin' | 'histogram' | 'radar' | 
+         'polarArea' | 'rangeBar' | 'rangeArea' | 'treemap' | 
+         'waffle' | 'sunburst' | 'funnel' | 'pyramid' | 'gauge';
+  foreColor?: string;
+  fontFamily?: string;
+  background?: string;
+  offsetX?: number;
+  offsetY?: number;
+  dropShadow?: {
+    enabled?: boolean;
+    top?: number;
+    left?: number;
+    blur?: number;
+    opacity?: number;
+    color?: string | string[];
+  };
+  events?: {
+    animationEnd?(chart: ApexCharts, options?: any): void;
+    beforeMount?(chart: ApexCharts, options?: any): void;
+    mounted?(chart: ApexCharts, options?: any): void;
+    updated?(chart: ApexCharts, options?: any): void;
+    mouseMove?(e: MouseEvent, chart?: ApexCharts, options?: any): void;
+    mouseLeave?(e: MouseEvent, chart?: ApexCharts, options?: any): void;
+    click?(e: MouseEvent, chart?: ApexCharts, options?: any): void;
+    legendClick?(chart: ApexCharts, seriesIndex?: number, options?: any): void;
+    markerClick?(e: MouseEvent, chart?: ApexCharts, options?: any): void;
+    selection?(chart: ApexCharts, options?: any): void;
+    dataPointSelection?(e: MouseEvent, chart?: ApexCharts, options?: any): void;
+    dataPointMouseEnter?(e: MouseEvent, chart?: ApexCharts, options?: any): void;
+    dataPointMouseLeave?(e: MouseEvent, chart?: ApexCharts, options?: any): void;
+    beforeZoom?(chart: ApexCharts, options?: any): boolean | void;
+    beforeResetZoom?(chart: ApexCharts, options?: any): boolean | void;
+    zoomed?(chart: ApexCharts, options?: any): void;
+    scrolled?(chart: ApexCharts, options?: any): void;
+    brushScrolled?(chart: ApexCharts, options?: any): void;
+  };
+  animations?: {
+    enabled?: boolean;
+    easing?: 'linear' | 'easeInSine' | 'easeOutSine' | 'easeInOutSine' | 
+             'easeInQuad' | 'easeOutQuad' | 'easeInOutQuad' | 
+             'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic' | string | 
+             [number, number, number, number] | ((t: number) => number);
+    speed?: number;
+    animateGradually?: { enabled?: boolean; delay?: number; };
+    dynamicAnimation?: { enabled?: boolean; speed?: number; easing?: string; };
+  };
+  toolbar?: {
+    show?: boolean;
+    offsetX?: number;
+    offsetY?: number;
+    tools?: {
+      download?: boolean | string;
+      selection?: boolean | string;
+      zoom?: boolean | string;
+      zoomin?: boolean | string;
+      zoomout?: boolean | string;
+      pan?: boolean | string;
+      reset?: boolean | string;
+      measure?: boolean | string;
+      customIcons?: Array<{
+        icon?: string;
+        title?: string;
+        index?: number;
+        class?: string;
+        click?(chart: ApexCharts, options?: any, e?: MouseEvent): void;
+      }>;
+    };
+    export?: {
+      csv?: { filename?: string; columnDelimiter?: string; headerCategory?: string; headerValue?: string; };
+      svg?: { filename?: string; };
+      png?: { filename?: string; };
+    };
+    autoSelected?: 'zoom' | 'selection' | 'pan' | 'measure';
+  };
+  zoom?: {
+    enabled?: boolean;
+    type?: 'x' | 'y' | 'xy';
+    autoScaleYaxis?: boolean;
+    allowMouseWheelZoom?: boolean | 'auto';
+    pinch?: boolean | 'auto';
+    zoomedArea?: {
+      fill?: { color?: string; opacity?: number; };
+      stroke?: { color?: string; opacity?: number; width?: number; };
+    };
+  };
+  selection?: {
+    enabled?: boolean;
+    type?: string;
+    fill?: { color?: string; opacity?: number; };
+    stroke?: { width?: number; color?: string; opacity?: number; dashArray?: number; };
+    xaxis?: { min?: number; max?: number; };
+    yaxis?: { min?: number; max?: number; };
+  };
+  stacked?: boolean;
+  stackType?: 'normal' | '100%';
+  id?: string;
+  group?: string;
+  locales?: Array<{ name?: string; options?: any; }>;
+  defaultLocale?: string;
+  parentHeightOffset?: number;
+  redrawOnParentResize?: boolean;
+  redrawOnWindowResize?: boolean | ((...args: any[]) => boolean);
+  sparkline?: { enabled?: boolean; };
+}
+ +

مثال کاربردی:

+ 
chart: {
+  type: 'line',
+  height: 350,
+  foreColor: '#333',
+  fontFamily: 'Vazirmatn, sans-serif',
+  animations: {
+    enabled: true,
+    easing: 'easeInOutCubic',
+    speed: 800,
+    animateGradually: { enabled: true, delay: 150 },
+    dynamicAnimation: { enabled: true, speed: 350 }
+  },
+  toolbar: {
+    show: true,
+    tools: {
+      download: true,
+      zoom: true,
+      zoomin: true,
+      zoomout: true,
+      reset: true,
+      customIcons: [{
+        icon: '<svg>...</svg>',
+        title: 'دکمه سفارشی',
+        index: 0,
+        click: (chart, options, e) => { console.log('کلیک شد'); }
+      }]
+    }
+  },
+  zoom: {
+    enabled: true,
+    type: 'x',
+    autoScaleYaxis: false
+  },
+  events: {
+    mounted: (chart, options) => { console.log('نمودار نصب شد'); },
+    dataPointSelection: (e, chart, options) => { console.log('نقطه انتخاب شد'); }
+  }
+}
+ + +

۳.۳. فیلد colors - رنگ‌های سری‌های داده

+

آرایه‌ای از رنگ‌ها برای سری‌های داده. هر سری با یک رنگ متفاوت نمایش داده می‌شود.

+ +

ساختار:

+ 
colors?: Array<string | ((opts: {
+  value: number;
+  seriesIndex: number;
+  dataPointIndex: number;
+  w: any;
+}) => string)>
+ +

مثال کاربردی:

+ 
// رنگ‌های ثابت
+colors: ['#008FFB', '#00E396', '#FEB019', '#FF4560', '#775DD0']
+
+// رنگ‌های داینامیک بر اساس مقدار
+colors: [
+  function({ value, seriesIndex, dataPointIndex }) {
+    return value > 50 ? '#00E396' : '#FF4560';
+  }
+]
+ + +

۳.۴. فیلد dataLabels - برچسب‌های داده

+

برچسب‌هایی که روی نقاط داده نمایش داده می‌شوند.

+ +

ساختار:

+ 
dataLabels?: {
+  enabled?: boolean;
+  enabledOnSeries?: number[];
+  formatter?(val: string | number | number[], opts?: any): string | number | (string | number)[];
+  textAnchor?: 'start' | 'middle' | 'end';
+  distributed?: boolean;
+  offsetX?: number;
+  offsetY?: number;
+  style?: {
+    fontSize?: string;
+    fontFamily?: string;
+    fontWeight?: string | number;
+    colors?: string[];
+  };
+  background?: {
+    enabled?: boolean;
+    foreColor?: string;
+    borderRadius?: number;
+    padding?: number;
+    opacity?: number;
+    borderWidth?: number;
+    borderColor?: string;
+    dropShadow?: { enabled?: boolean; top?: number; left?: number; blur?: number; opacity?: number; color?: string | string[]; };
+  };
+  dropShadow?: { enabled?: boolean; top?: number; left?: number; blur?: number; opacity?: number; color?: string | string[]; };
+}
+ +

مثال کاربردی:

+ 
dataLabels: {
+  enabled: true,
+  formatter: (val) => val + '%',
+  style: {
+    fontSize: '12px',
+    fontFamily: 'Vazirmatn',
+    colors: ['#fff']
+  },
+  background: {
+    enabled: true,
+    foreColor: '#fff',
+    borderRadius: 4,
+    padding: 4,
+    borderColor: '#000',
+    borderWidth: 1
+  }
+}
+ + +

۳.۵. فیلد fill - پرکننده

+

تنظیمات پرکننده (رنگ، گرادیانت، الگو، تصویر).

+ +

ساختار:

+ 
fill?: {
+  colors?: string[];
+  opacity?: number | number[];
+  type?: string | string[];
+  gradient?: {
+    shade?: string;
+    type?: string;
+    shadeIntensity?: number;
+    gradientToColors?: string[];
+    inverseColors?: boolean;
+    opacityFrom?: number | number[];
+    opacityTo?: number | number[];
+    stops?: number[];
+    colorStops?: Array<{ offset: number; color: string; opacity: number; }> | Array<Array<{ offset: number; color: string; opacity: number; }>>;
+  };
+  image?: {
+    src?: string | string[];
+    width?: number;
+    height?: number;
+  };
+  pattern?: {
+    style?: string | string[];
+    width?: number;
+    height?: number;
+    strokeWidth?: number;
+  };
+}
+ +

مثال کاربردی:

+ 
fill: {
+  type: 'gradient',
+  gradient: {
+    shade: 'light',
+    type: 'vertical',
+    shadeIntensity: 0.5,
+    gradientToColors: ['#008FFB', '#00E396'],
+    opacityFrom: 1,
+    opacityTo: 0.5,
+    stops: [0, 50, 100]
+  }
+}
+ + +

۳.۶. فیلد grid - شبکه‌بندی

+

تنظیمات شبکه‌بندی نمودار.

+ +

ساختار:

+ 
grid?: {
+  show?: boolean;
+  borderColor?: string;
+  strokeDashArray?: number;
+  position?: 'front' | 'back';
+  xaxis?: { lines?: { show?: boolean; offsetX?: number; offsetY?: number; }; };
+  yaxis?: { lines?: { show?: boolean; offsetX?: number; offsetY?: number; }; };
+  row?: { colors?: string[]; opacity?: number; };
+  column?: { colors?: string[]; opacity?: number; };
+  padding?: { top?: number; right?: number; bottom?: number; left?: number; };
+}
+ +

مثال کاربردی:

+ 
grid: {
+  show: true,
+  borderColor: '#e0e0e0',
+  strokeDashArray: 4,
+  position: 'back',
+  row: { colors: ['#f3f3f3', 'transparent'], opacity: 0.5 },
+  padding: { top: 0, right: 10, bottom: 0, left: 10 }
+}
+ + +

۳.۷. فیلد legend - راهنمای نمودار

+

تنظیمات راهنمای نمودار (Legend).

+ +

ساختار:

+ 
legend?: {
+  show?: boolean;
+  showForSingleSeries?: boolean;
+  showForNullSeries?: boolean;
+  showForZeroSeries?: boolean;
+  floating?: boolean;
+  inverseOrder?: boolean;
+  position?: 'top' | 'right' | 'bottom' | 'left';
+  horizontalAlign?: 'left' | 'center' | 'right';
+  fontSize?: string;
+  fontFamily?: string;
+  fontWeight?: string | number;
+  width?: number;
+  height?: number;
+  formatter?(legendName: string, opts?: { seriesIndex: number; w: any; }): string;
+  tooltipHoverFormatter?(legendName: string, opts?: { seriesIndex: number; w: any; }): string;
+  customLegendItems?: string[];
+  labels?: { colors?: string | string[]; useSeriesColors?: boolean; };
+  markers?: {
+    width?: number;
+    height?: number;
+    strokeColor?: string;
+    strokeWidth?: number;
+    radius?: number;
+    customHTML?(): any;
+    onClick?(): void;
+    offsetX?: number;
+    offsetY?: number;
+  };
+  itemMargin?: { horizontal?: number; vertical?: number; };
+  onItemClick?: { toggleDataSeries?: boolean; };
+  onItemHover?: { highlightDataSeries?: boolean; };
+}
+ +

مثال کاربردی:

+ 
legend: {
+  show: true,
+  position: 'top',
+  horizontalAlign: 'center',
+  fontSize: '14px',
+  fontFamily: 'Vazirmatn',
+  markers: { width: 12, height: 12, radius: 6 },
+  onItemClick: { toggleDataSeries: true },
+  onItemHover: { highlightDataSeries: true }
+}
+ + +

۳.۸. فیلد markers - نشانگرها

+

تنظیمات نشانگرهای نقاط داده.

+ +

ساختار:

+ 
markers?: {
+  size?: number | number[];
+  colors?: string | string[];
+  strokeColors?: string | string[];
+  strokeWidth?: number | number[];
+  strokeOpacity?: number | number[];
+  strokeDashArray?: number | number[];
+  fillOpacity?: number | number[];
+  discrete?: Array<{
+    seriesIndex?: number;
+    dataPointIndex?: number;
+    fillColor?: string;
+    strokeColor?: string;
+    size?: number;
+  }>;
+  shape?: 'circle' | 'square' | 'rect';
+  offsetX?: number;
+  offsetY?: number;
+  hover?: { size?: number; sizeOffset?: number; };
+  onClick?(e?: any): void;
+  onDblClick?(e?: any): void;
+  showNullDataPoints?: boolean;
+}
+ +

مثال کاربردی:

+ 
markers: {
+  size: 6,
+  colors: ['#008FFB'],
+  strokeColors: '#fff',
+  strokeWidth: 2,
+  hover: { size: 8, sizeOffset: 3 },
+  discrete: [{
+    seriesIndex: 0,
+    dataPointIndex: 3,
+    fillColor: '#FF0000',
+    size: 10
+  }]
+}
+ + +

۳.۹. فیلد plotOptions - گزینه‌های خاص هر نوع نمودار

+

این فیلد تنظیمات خاص هر نوع نمودار را شامل می‌شود.

+ +

ساختار (خلاصه):

+ 
plotOptions?: {
+  bar?: {
+    horizontal?: boolean;
+    columnWidth?: string | number;
+    barHeight?: string | number;
+    distributed?: boolean;
+    borderRadius?: number;
+    borderRadiusApplication?: 'around' | 'end';
+    borderRadiusWhenStacked?: 'all' | 'last';
+    hideZeroBarsWhenGrouped?: boolean;
+    rangeBarOverlap?: boolean;
+    rangeBarGroupRows?: boolean;
+    isDumbbell?: boolean;
+    dumbbellColors?: string[][];
+    colors?: {
+      ranges?: Array<{ from?: number; to?: number; color?: string; }>;
+      backgroundBarColors?: string[];
+      backgroundBarOpacity?: number;
+      backgroundBarRadius?: number;
+    };
+    dataLabels?: {
+      maxItems?: number;
+      hideOverflowingLabels?: boolean;
+      position?: string;
+      orientation?: 'horizontal' | 'vertical';
+      total?: {
+        enabled?: boolean;
+        formatter?(val?: string, opts?: any): string;
+        offsetX?: number;
+        offsetY?: number;
+        style?: { color?: string; fontSize?: string; fontFamily?: string; fontWeight?: string | number; };
+      };
+    };
+  };
+  bubble?: { minBubbleRadius?: number; maxBubbleRadius?: number; };
+  candlestick?: {
+    colors?: { upward?: string | string[]; downward?: string | string[]; };
+    wick?: { useFillColor?: boolean; };
+  };
+  boxPlot?: {
+    colors?: { upper?: string | string[]; lower?: string | string[]; };
+  };
+  heatmap?: {
+    radius?: number;
+    enableShades?: boolean;
+    shadeIntensity?: number;
+    reverseNegativeShade?: boolean;
+    distributed?: boolean;
+    useFillColorAsStroke?: boolean;
+    colorScale?: {
+      ranges?: Array<{ from?: number; to?: number; color?: string; foreColor?: string; name?: string; }>;
+      inverse?: boolean;
+      min?: number;
+      max?: number;
+    };
+  };
+  treemap?: {
+    enableShades?: boolean;
+    shadeIntensity?: number;
+    distributed?: boolean;
+    reverseNegativeShade?: boolean;
+    useFillColorAsStroke?: boolean;
+    dataLabels?: { format?: 'scale' | 'truncate'; };
+    borderRadius?: number;
+    colorScale?: {
+      inverse?: boolean;
+      ranges?: Array<{ from?: number; to?: number; color?: string; foreColor?: string; name?: string; }>;
+      min?: number;
+      max?: number;
+    };
+  };
+  pie?: {
+    startAngle?: number;
+    endAngle?: number;
+    customScale?: number;
+    offsetX?: number;
+    offsetY?: number;
+    expandOnClick?: boolean;
+    expandOffset?: number;
+    dataLabels?: { offset?: number; };
+  };
+  donut?: {
+    size?: string;
+    background?: string;
+    labels?: {
+      show?: boolean;
+      name?: { show?: boolean; fontSize?: string; fontFamily?: string; fontWeight?: string | number; offsetY?: number; color?: string; formatter?(val: string): string; };
+      value?: { show?: boolean; fontSize?: string; fontFamily?: string; fontWeight?: string | number; offsetY?: number; color?: string; formatter?(val: number | string): string; };
+      total?: { show?: boolean; showAlways?: boolean; label?: string; color?: string; fontFamily?: string; fontWeight?: string | number; fontSize?: string; formatter?(w: any): string; };
+    };
+  };
+  radialBar?: {
+    inverseOrder?: boolean;
+    startAngle?: number;
+    endAngle?: number;
+    offsetX?: number;
+    offsetY?: number;
+    hollow?: {
+      margin?: number;
+      size?: string;
+      background?: string;
+      image?: string;
+      imageWidth?: number;
+      imageHeight?: number;
+      imageOffsetX?: number;
+      imageOffsetY?: number;
+      imageClipped?: boolean;
+      position?: 'front' | 'back';
+      dropShadow?: { enabled?: boolean; top?: number; left?: number; blur?: number; opacity?: number; color?: string | string[]; };
+    };
+    track?: {
+      show?: boolean;
+      startAngle?: number;
+      endAngle?: number;
+      background?: string | string[];
+      strokeWidth?: string;
+      opacity?: number;
+      margin?: number;
+      dropShadow?: { enabled?: boolean; top?: number; left?: number; blur?: number; opacity?: number; color?: string | string[]; };
+    };
+    dataLabels?: {
+      show?: boolean;
+      name?: { show?: boolean; fontSize?: string; fontFamily?: string; fontWeight?: string | number; offsetY?: number; color?: string; };
+      value?: { show?: boolean; fontSize?: string; fontFamily?: string; fontWeight?: string | number; offsetY?: number; color?: string; formatter?(val: number): string; };
+      total?: { show?: boolean; label?: string; color?: string; fontFamily?: string; fontWeight?: string | number; fontSize?: string; formatter?(w: any): string; };
+    };
+  };
+  radar?: {
+    size?: number;
+    offsetX?: number;
+    offsetY?: number;
+    polygons?: {
+      strokeColors?: string | string[];
+      strokeWidth?: string | number[];
+      connectorColors?: string | string[];
+      fill?: { colors?: string[]; };
+    };
+  };
+  polarArea?: {
+    rings?: { strokeColor?: string; strokeWidth?: number; };
+    spokes?: { connectorColors?: string | string[]; strokeWidth?: number; };
+  };
+}
+ +

مثال کاربردی (Bar):

+ 
plotOptions: {
+  bar: {
+    horizontal: false,
+    columnWidth: '70%',
+    borderRadius: 4,
+    borderRadiusApplication: 'end',
+    distributed: false,
+    dataLabels: {
+      position: 'top',
+      maxItems: 100,
+      hideOverflowingLabels: true
+    }
+  }
+}
+ +

مثال کاربردی (Pie):

+ 
plotOptions: {
+  pie: {
+    startAngle: 0,
+    endAngle: 360,
+    expandOnClick: true,
+    expandOffset: 10,
+    dataLabels: { offset: 0 }
+  }
+}
+ + +

۳.۱۰. فیلد responsive - تنظیمات واکنش‌گرا

+

تنظیمات واکنش‌گرا برای اندازه‌های مختلف صفحه.

+ +

ساختار:

+ 
responsive?: Array<{
+  breakpoint?: number;
+  options?: ApexOptions;
+}>
+ +

مثال کاربردی:

+ 
responsive: [
+  {
+    breakpoint: 480,
+    options: {
+      chart: { width: '100%', height: 250 },
+      legend: { position: 'bottom' }
+    }
+  },
+  {
+    breakpoint: 768,
+    options: {
+      chart: { width: '100%', height: 300 },
+      legend: { position: 'bottom' }
+    }
+  }
+]
+ + +

۳.۱۱. فیلد states - حالت‌های مختلف

+

تنظیمات حالت‌های مختلف (hover, active).

+ +

ساختار:

+ 
states?: {
+  hover?: {
+    filter?: {
+      type?: 'none' | 'lighten' | 'darken';
+      value?: number;
+    };
+  };
+  active?: {
+    allowMultipleDataPointsSelection?: boolean;
+    filter?: {
+      type?: 'none' | 'lighten' | 'darken';
+      value?: number;
+    };
+  };
+}
+ +

مثال کاربردی:

+ 
states: {
+  hover: {
+    filter: { type: 'darken', value: 0.15 }
+  },
+  active: {
+    allowMultipleDataPointsSelection: false,
+    filter: { type: 'darken', value: 0.35 }
+  }
+}
+ + +

۳.۱۲. فیلد stroke - خطوط نمودار

+

تنظیمات خطوط نمودار.

+ +

ساختار:

+ 
stroke?: {
+  show?: boolean;
+  curve?: 'smooth' | 'straight' | 'stepline' | 'linestep' | 'monotoneCubic' | 
+          ('smooth' | 'straight' | 'stepline' | 'linestep' | 'monotoneCubic')[];
+  lineCap?: 'butt' | 'square' | 'round';
+  colors?: string[];
+  width?: number | number[];
+  dashArray?: number | number[];
+}
+ +

مثال کاربردی:

+ 
stroke: {
+  show: true,
+  curve: 'smooth',
+  lineCap: 'round',
+  colors: ['#008FFB'],
+  width: 3,
+  dashArray: 0
+}
+ + +

۳.۱۳. فیلد theme - تم

+

تنظیمات تم (روشن/تاریک).

+ +

ساختار:

+ 
theme?: {
+  mode?: 'light' | 'dark' | '';
+  palette?: string;
+  monochrome?: {
+    enabled?: boolean;
+    color?: string;
+    shadeTo?: 'light' | 'dark';
+    shadeIntensity?: number;
+  };
+}
+ +

مثال کاربردی:

+ 
theme: {
+  mode: 'light',
+  palette: 'palette1',
+  monochrome: {
+    enabled: false,
+    color: '#008FFB',
+    shadeTo: 'light',
+    shadeIntensity: 0.65
+  }
+}
+ + +

۳.۱۴. فیلدهای title و subtitle - عنوان و زیرعنوان

+

تنظیمات عنوان و زیرعنوان نمودار.

+ +

ساختار:

+ 
title?: {
+  text?: string;
+  align?: 'left' | 'center' | 'right';
+  margin?: number;
+  offsetX?: number;
+  offsetY?: number;
+  floating?: boolean;
+  style?: {
+    fontSize?: string;
+    fontFamily?: string;
+    fontWeight?: string | number;
+    color?: string;
+  };
+}
+
+subtitle?: {
+  text?: string;
+  align?: 'left' | 'center' | 'right';
+  margin?: number;
+  offsetX?: number;
+  offsetY?: number;
+  floating?: boolean;
+  style?: {
+    fontSize?: string;
+    fontFamily?: string;
+    fontWeight?: string | number;
+    color?: string;
+  };
+}
+ +

مثال کاربردی:

+ 
title: {
+  text: 'نمودار فروش ماهانه',
+  align: 'center',
+  margin: 10,
+  style: {
+    fontSize: '18px',
+    fontFamily: 'Vazirmatn',
+    fontWeight: 'bold',
+    color: '#333'
+  }
+},
+subtitle: {
+  text: 'آمار فروش سال ۱۴۰۳',
+  align: 'center',
+  style: {
+    fontSize: '14px',
+    color: '#666'
+  }
+}
+ + +

۳.۱۵. فیلد tooltip - Tooltip

+

تنظیمات Tooltip (راهنمای شناور).

+ +

ساختار:

+ 
tooltip?: {
+  enabled?: boolean;
+  enabledOnSeries?: number[];
+  shared?: boolean;
+  followCursor?: boolean;
+  intersect?: boolean;
+  inverseOrder?: boolean;
+  arrow?: boolean;
+  custom?: Array<(opts: {
+    series: number[][];
+    seriesIndex: number;
+    dataPointIndex: number;
+    y1?: number;
+    y2?: number;
+    w: any;
+  }) => string>;
+  fillSeriesColor?: boolean;
+  theme?: 'light' | 'dark';
+  style?: {
+    fontSize?: string;
+    fontFamily?: string;
+  };
+  onDatasetHover?: { highlightDataSeries?: boolean; };
+  x?: {
+    show?: boolean;
+    format?: string;
+    formatter?(value: string | number, opts?: any): string;
+  };
+  y?: Array<{
+    title?: { title?: string; formatter?(seriesName: string, opts?: any): string; };
+    formatter?(value: number, opts?: any): string;
+  }>;
+  marker?: { show?: boolean; fillColors?: string[]; };
+  items?: { display?: string; };
+  fixed?: {
+    enabled?: boolean;
+    position?: string;
+    offsetX?: number;
+    offsetY?: number;
+  };
+}
+ +

مثال کاربردی:

+ 
tooltip: {
+  enabled: true,
+  shared: true,
+  followCursor: false,
+  intersect: false,
+  theme: 'light',
+  style: { fontSize: '12px', fontFamily: 'Vazirmatn' },
+  x: { show: true, format: 'dd MMM' },
+  y: [{
+    title: { title: 'فروش: ' },
+    formatter: (val) => val.toLocaleString('fa-IR') + ' تومان'
+  }],
+  marker: { show: true }
+}
+ + +

۳.۱۶. فیلد xaxis - محور X

+

تنظیمات محور X.

+ +

ساختار:

+ 
xaxis?: {
+  type?: 'category' | 'datetime' | 'numeric';
+  categories?: Array<string | number> | Array<Array<string | number>>;
+  overwriteCategories?: number[] | string[];
+  offsetX?: number;
+  offsetY?: number;
+  sorted?: boolean;
+  labels?: {
+    show?: boolean;
+    rotate?: number;
+    rotateAlways?: boolean;
+    hideOverlappingLabels?: boolean;
+    showDuplicates?: boolean;
+    trim?: boolean;
+    minHeight?: number;
+    maxHeight?: number;
+    style?: {
+      colors?: string | string[];
+      fontSize?: string;
+      fontFamily?: string;
+      fontWeight?: string | number;
+      cssClass?: string;
+    };
+    offsetX?: number;
+    offsetY?: number;
+    format?: string;
+    formatter?(value: string | number, timestamp?: number, opts?: any): string | string[];
+    datetimeUTC?: boolean;
+    datetimeFormatter?: {
+      year?: string;
+      month?: string;
+      day?: string;
+      hour?: string;
+      minute?: string;
+      second?: string;
+    };
+  };
+  group?: {
+    groups?: Array<{ title: string; cols: number }>;
+    style?: {
+      colors?: string | string[];
+      fontSize?: string;
+      fontFamily?: string;
+      fontWeight?: string | number;
+      cssClass?: string;
+    };
+  };
+  axisBorder?: {
+    show?: boolean;
+    color?: string;
+    width?: string | number;
+    height?: number;
+    offsetX?: number;
+    offsetY?: number;
+  };
+  axisTicks?: {
+    show?: boolean;
+    borderType?: 'solid' | 'dotted';
+    color?: string;
+    width?: number;
+    offsetX?: number;
+    offsetY?: number;
+  };
+  tickPlacement?: string;
+  tickAmount?: number | 'dataPoints';
+  stepSize?: number;
+  min?: number;
+  max?: number;
+  range?: number;
+  floating?: boolean;
+  position?: string;
+  title?: {
+    text?: string;
+    offsetX?: number;
+    offsetY?: number;
+    style?: {
+      color?: string;
+      fontFamily?: string;
+      fontWeight?: string | number;
+      fontSize?: string;
+      cssClass?: string;
+    };
+  };
+  crosshairs?: {
+    show?: boolean;
+    width?: number | string;
+    position?: string;
+    opacity?: number;
+    stroke?: { color?: string; width?: number; dashArray?: number; };
+    fill?: {
+      type?: string;
+      color?: string;
+      gradient?: {
+        colorFrom?: string;
+        colorTo?: string;
+        stops?: number[];
+        opacityFrom?: number;
+        opacityTo?: number;
+      };
+    };
+    dropShadow?: { enabled?: boolean; top?: number; left?: number; blur?: number; opacity?: number; color?: string | string[]; };
+  };
+  tooltip?: {
+    enabled?: boolean;
+    offsetY?: number;
+    formatter?(value: string | number, opts?: any): string;
+    style?: { fontSize?: string; fontFamily?: string; };
+  };
+}
+ +

مثال کاربردی:

+ 
xaxis: {
+  type: 'category',
+  categories: ['فروردین', 'اردیبهشت', 'خرداد', 'تیر', 'مرداد', 'شهریور', 'مهر'],
+  labels: {
+    show: true,
+    rotate: -45,
+    style: {
+      fontSize: '12px',
+      fontFamily: 'Vazirmatn',
+      colors: ['#333']
+    }
+  },
+  title: {
+    text: 'ماه',
+    style: { fontSize: '14px', fontWeight: 'bold' }
+  },
+  crosshairs: {
+    show: true,
+    stroke: { color: '#000', width: 1, dashArray: 0 }
+  }
+}
+ + +

۳.۱۷. فیلد yaxis - محور Y

+

تنظیمات محور Y.

+ +

ساختار:

+ 
yaxis?: {
+  show?: boolean;
+  showAlways?: boolean;
+  showForNullSeries?: boolean;
+  seriesName?: string | string[];
+  opposite?: boolean;
+  reversed?: boolean;
+  logarithmic?: boolean;
+  logBase?: number;
+  tickAmount?: number;
+  stepSize?: number;
+  forceNiceScale?: boolean;
+  min?: number | ((min: number) => number);
+  max?: number | ((max: number) => number);
+  floating?: boolean;
+  decimalsInFloat?: number;
+  labels?: {
+    show?: boolean;
+    showDuplicates?: boolean;
+    minWidth?: number;
+    maxWidth?: number;
+    style?: {
+      colors?: string | string[];
+      fontSize?: string;
+      fontWeight?: string | number;
+      fontFamily?: string;
+      cssClass?: string;
+    };
+    offsetX?: number;
+    offsetY?: number;
+    rotate?: number;
+    align?: 'left' | 'center' | 'right';
+    padding?: number;
+    formatter?(value: number, opts?: any): string | string[];
+  };
+  axisBorder?: {
+    show?: boolean;
+    color?: string;
+    width?: number;
+    offsetX?: number;
+    offsetY?: number;
+  };
+  axisTicks?: {
+    show?: boolean;
+    borderType?: 'solid' | 'dotted';
+    color?: string;
+    width?: number;
+    offsetX?: number;
+    offsetY?: number;
+  };
+  title?: {
+    text?: string;
+    rotate?: number;
+    offsetX?: number;
+    offsetY?: number;
+    style?: {
+      color?: string;
+      fontFamily?: string;
+      fontWeight?: string | number;
+      fontSize?: string;
+      cssClass?: string;
+    };
+  };
+  crosshairs?: {
+    show?: boolean;
+    position?: string;
+    stroke?: { color?: string; width?: number; dashArray?: number; };
+  };
+  tooltip?: {
+    enabled?: boolean;
+    offsetX?: number;
+  };
+}
+ +

مثال کاربردی:

+ 
yaxis: {
+  show: true,
+  title: {
+    text: 'مبلغ (تومان)',
+    style: { fontSize: '14px', fontWeight: 'bold' }
+  },
+  labels: {
+    show: true,
+    formatter: (val) => val.toLocaleString('fa-IR'),
+    style: { fontSize: '12px', fontFamily: 'Vazirmatn' }
+  },
+  min: 0,
+  max: 100,
+  tickAmount: 5
+}
+ + +

۳.۱۸. فیلد noData - پیام عدم وجود داده

+

تنظیمات پیام نمایش داده شده در صورت عدم وجود داده.

+ +

ساختار:

+ 
noData?: {
+  text?: string;
+  align?: 'left' | 'center' | 'right';
+  verticalAlign?: 'top' | 'middle' | 'bottom';
+  offsetX?: number;
+  offsetY?: number;
+  style?: {
+    color?: string;
+    fontSize?: string;
+    fontFamily?: string;
+  };
+}
+ +

مثال کاربردی:

+ 
noData: {
+  text: 'داده‌ای برای نمایش وجود ندارد',
+  align: 'center',
+  verticalAlign: 'middle',
+  style: {
+    color: '#999',
+    fontSize: '16px',
+    fontFamily: 'Vazirmatn'
+  }
+}
+ + +

۴. خلاصه و جمع‌بندی

+

+ مدل ApexOptions با ۲۵ فیلد اصلی، کنترل کاملی بر تمام جنبه‌های نمودار ارائه می‌دهد. با استفاده از این فیلدها می‌توانید نمودارهای کاملاً سفارشی و حرفه‌ای ایجاد کنید. +

+ +
+ 💡 نکته مهم: برای استفاده بهینه، همیشه از مستندات رسمی ApexCharts (apexcharts.com/docs/options) استفاده کنید و مقادیر پیش‌فرض را بررسی کنید. +
+ +
+ ⚠️ هشدار: برخی فیلدها فقط برای انواع خاصی از نمودار کاربرد دارند. قبل از استفاده، مطمئن شوید که فیلد مورد نظر با نوع نمودار شما سازگار است. +
+ + +
+

© کلیه حقوق این مستند متعلق به شرکت فن آوران ساحر علم می‌باشد.

+

طراحی و توسعه: هادی خزاعی اصل | وب‌سایت: https://saherelm.ir

+

📅 تاریخ تهیه: دوشنبه ۱۱ شهریور ۱۴۰۴

+
+
+ + + \ No newline at end of file diff --git a/Documents/Markdown/README.md b/Documents/Markdown/README.md new file mode 100644 index 0000000..88ab5ec --- /dev/null +++ b/Documents/Markdown/README.md @@ -0,0 +1,172 @@ +# ‫برنامه کاربردی RpkRem2Fo + +## ‫خلاصه اجرایی و معرفی + +‫برنامه کاربردی RpkRem2Fo یک نمونه عملی (Proof of Concept) از پیاده‌سازی یک API Gateway پویا در بستر ASP.NET Core است که با استفاده از ماژول RpkProxyPkg ساخته شده است. این برنامه به عنوان یک Reverse Proxy هوشمند عمل می‌کند که درخواست‌های ورودی از کلاینت‌ها (معمولاً Frontend های مبتنی بر React/Vue) را دریافت کرده و بر اساس پیکربندی‌های تعریف شده، آن‌ها را به سرویس‌های Backend مناسب مسیریابی می‌کند. + +## RpkProxyPkg + +‫ماژول RpkProxyPkg به عنوان یک کتابخانه قابل استفاده مجدد (Reusable Library) طراحی شده است که منطق پیچیده مسیریابی، مدیریت توکن، استخراج پارامترها و ارتباط با Service Broker را در خود جای داده است. برنامه‌های کاربردی مانند RpkRem2Fo صرفاً با تنظیم پیکربندی و ثبت سرویس‌ها، می‌توانند از تمام قابلیت‌های این ماژول بهره‌مند شوند. + +## اهداف برنامه + +1. ‫یکپارچه‌سازی API ها + ‫ارائه یک نقطه ورود واحد برای تمام سرویس‌های Backend و ساده‌سازی ارتباط Frontend با Backend. + +2. ‫مدیریت احراز هویت + ‫استخراج و اعتبارسنجی توکن JWT و انتقال امن اطلاعات کاربر به سرویس‌های مقصد. + +3. ‫مسیریابی پویا + ‫امکان تعریف مسیرهای جدید بدون نیاز به تغییر کد، صرفاً با ویرایش فایل تنظیمات. + +4. ‫مدیریت CORS + ‫کنترل کامل بر هدرهای Cross-Origin برای ارتباط امن با Frontend های مختلف. + +## معماری کلی برنامه + +‫برنامه RpkRem2Fo از یک معماری لایه‌ای استاندارد پیروی می‌کند که در آن ماژول RpkProxyPkg به عنوان یک لایه میانجی (Middleware Layer) بین کلاینت و سرویس‌های Backend قرار می‌گیرد. + +```md +┌─────────────────────────────────────────────────────────────────┐ +│ Frontend (React/Vue) │ +│ (Browser Client) │ +└────────────────────────────┬────────────────────────────────────┘ + │ HTTP Requests + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ RpkRem2Fo (ASP.NET Core Application) │ +│ ┌───────────────────────────────────────────────────────────┐ │ +│ │ RpkProxyPkg Module (Reusable) │ │ +│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ +│ │ │ Middleware │→ │ Services │→ │ Extensions │ │ │ +│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ +│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ +│ │ │ Configurations│ │ Contracts │→ │ Constants │ │ │ +│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ +│ └───────────────────────────────────────────────────────────┘ │ +│ appsettings.json │ +└──────────┬──────────────────────────────────┬───────────────────┘ + │ │ + ▼ ▼ +┌──────────────────────┐ ┌──────────────────────┐ +│ Direct Targets │ │ Service Broker │ +│ (BoardManagementApi,│ │ (7 Architectural │ +│ ..., │ │ Layers) │ +│ ) │ │ ┌────────────────┐ │ +│ │ │ │ Rem2 Module │ │ +└──────────────────────┘ │ │ (Layer 6) │ │ + │ └────────────────┘ │ + └──────────────────────┘ +``` + +‫یکی از مهم‌ترین جنبه‌های طراحی این سیستم، جداسازی کامل بین ماژول و برنامه کاربردی است. این طراحی بر اساس اصل "Separation of Concerns" و "Reusability" انجام شده است. + +| جنبه | ماژول RpkProxyPkg | برنامه RpkRem2Fo | +|------|------------------------------------------|-----------------------------------------| +| نقش | ارائه‌دهنده قابلیت‌های پروکسی | مصرف‌کننده قابلیت‌های ماژول | +| مسئولیت | منطق مسیریابی، مدیریت توکن، CORS | راه‌اندازی، پیکربندی، تنظیمات خاص دامنه | +| قابلیت استفاده مجدد | کاملاً مستقل و قابل استفاده در پروژه‌های مختلف | مختص دامنه Rem2 (مدیریت برد) | +| تغییرات | تغییرات نادر (فقط برای افزودن قابلیت جدید) | تغییرات مکرر (افزودن مسیر، Target جدید) | +| وابستگی | مستقل از دامنه تجاری | وابسته به ماژول + Framework های شرکت | + +### مزیت این طراحی + +‫با این رویکرد، برای ساخت یک برنامه کاربردی جدید (مثلاً RpkHrFo برای منابع انسانی یا RpkFinanceFo برای مالی)، کافی است یک پروژه جدید ASP.NET Core ایجاد کرده، ماژول RpkProxyPkg را به آن اضافه کرده و پیکربندی خاص آن دامنه را در appsettings.json تعریف کنیم. هیچ خط کدی در ماژول نیاز به تغییر ندارد! + +### وابستگی فنی + +‫این ماژول به ماژول rpk.fwk وابستگی فنی دارد. + +```xml + + + + enable + net8.0 + enable + 1.0.0 + + + + + + + +``` + +## مراحل گام‌به‌گام استفاده از ماژول + +‫در این بخش، مراحل کامل ایجاد یک برنامه کاربردی جدید با استفاده از ماژول RpkProxyPkg تشریح می‌شود. این مراحل بر اساس پیاده‌سازی موفق RpkRem2Fo استخراج شده‌اند. + +1. ‫ایجاد پروژه ASP.NET Core Web API + ‫ابتدا یک پروژه جدید از نوع ASP.NET Core Web API با حداقل نسخه .NET 8 ایجاد کنید. این پروژه نقطه ورود برنامه کاربردی شما خواهد بود. + +2. ‫افزودن مرجع به ماژول RpkProxyPkg + ‫ماژول RpkProxyPkg را به عنوان یک Project Reference یا NuGet Package به پروژه خود اضافه کنید. + +3. ‫پیکربندی برنامه بر اساس نیازمندی های موجود + ‫با توجه به این مهم که ماژول RpkProxyPkg داری نیازمندی به rpk.fwk است و همهخ پروژه ها در سازمان داری نیازمندی فنی به rpk.fwk هستند، لازم نیست ارجاع مستقیم به rpk.fwk صورت بگیر. تنها در این گام لازم است سرویس های فریمورک را بر اساس استاندارد درج کنید. + +```cs +// Initialize Configuration ... +ConfigurationHelper.Initialize(builder.Configuration); + +// Register Data Service ... +var connectionStringDict = new Dictionary() { }; + +// Framework Registration ... +var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; +var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFilename); +builder.AddServicesFwk(connectionStringDict, xmlFilePath); +... +// Register Services ... +builder.Services.AddRpkProxyConfiguration(); +builder.Services.AddHttpClient(RpkProxyParams.ProxyHttpClient); +builder.Services.AddRpkProxy(); +... +// Using RpkProxy ... +app.UseRpkProxy(); +app.AddMiddelwareFwk(); +... +``` + +‫نکته مهم: حتما میان UseRpkProxy را قبل از AddMiddlewareFwk فراخوانی کنید. + +4. ‫تعریف پیکربندی الگوی مسیرها در appsettings.json + ‫مهم‌ترین مرحله: تعریف Targets، Templates و Requests در فایل تنظیمات. این بخش قلب تپنده برنامه است. + +```json +{ + "ProxyConfiguration": { + "Targets": [ + { "Name": "MyApi", "Url": "http://localhost:5000" } + ], + "Templates": [ + { + "Name": "GuidId", + "Template": "{id}", + "PathVariable": "ID", + "RegularExpression": "[0-9a-fA-F]{8}-...", + "ExtractionType": "GUID" + } + ], + "Requests": [ + { + "Name": "GetItem", + "Type": "Proxy", + "HttpMethod": "GET", + "Path": "/api/items/{id}", + "Templates": ["GuidId"], + "ServiceBrokerInfo": { + "Layer": 6, + "Module": "MyModule", + "Method": "GetItem" + } + } + ] + } +} +``` + +5. ‫اجرا و تست برنامه + ‫برنامه را اجرا کرده و مسیرهای تعریف شده را تست کنید. لاگ‌های برنامه اطلاعات کاملی از پردازش هر درخواست ارائه می‌دهند. diff --git a/Modules/xFrameworkComponentsHolder b/Modules/xFrameworkComponentsHolder index 576136d..f7b3cc6 160000 --- a/Modules/xFrameworkComponentsHolder +++ b/Modules/xFrameworkComponentsHolder @@ -1 +1 @@ -Subproject commit 576136dbd300f7a1791f0e60c2272223d3067dbc +Subproject commit f7b3cc65a3813d5c70ecbdf0d410a1871defe45f