Kotchasan PHP Framework

คู่มือการใช้งาน GGraphs อย่างละเอียด สร้างกราฟ SVG แบบไดนามิกได้ง่าย

GGraphs เป็นไลบรารี JavaScript ที่มีน้ำหนักเบา สำหรับสร้างกราฟแบบ SVG ที่มีความหลากหลายและสามารถปรับแต่งได้ง่าย รวมถึงกราฟเส้น (Line Charts), กราฟแท่ง (Bar Charts), กราฟวงกลม (Pie Charts), กราฟโดนัท (Donut Charts) และกราฟเกจ (Gauge Charts) ออกแบบมาเพื่อความเรียบง่ายและความยืดหยุ่น ช่วยให้นักพัฒนาสามารถสร้างการแสดงข้อมูลที่มีปฏิสัมพันธ์และดูดีได้อย่างรวดเร็ว

คุณสมบัติหลัก

  • ประเภทกราฟหลายรูปแบบ: รองรับกราฟเส้น, กราฟแท่ง, กราฟวงกลม, กราฟโดนัท และกราฟเกจ
  • การออกแบบตอบสนอง (Responsive Design): ปรับขนาดอัตโนมัติตามขนาดของ container
  • ปรับแต่งได้ง่าย: ปรับสี, ฟอนต์, ขนาด และอื่นๆ ตามต้องการ
  • องค์ประกอบที่มีปฏิสัมพันธ์: แสดง tooltip, การคลิกบนองค์ประกอบ และ legend
  • แอนิเมชัน: แอนิเมชันที่ราบรื่นในการเรนเดอร์และอัปเดตกราฟ
  • การผูกข้อมูล (Data Binding): โหลดข้อมูลจากอ็อบเจ็กต์ JavaScript หรือจากตาราง HTML
  • การเข้าถึงที่ดีขึ้น (Accessibility): เพิ่ม ARIA attributes เพื่อช่วยในการเข้าถึงข้อมูล

การติดตั้ง

เพื่อใช้งาน GGraphs ในโปรเจ็กต์ของคุณ เพียงแทรกไฟล์ JavaScript ของ GGraphs ลงในไฟล์ HTML ของคุณ

<!DOCTYPE html>
<html lang="th">
<head>
  <meta charset="UTF-8">
  <title>ตัวอย่าง GGraphs</title>
  <style>
    #graph-container {
      width: 800px;
      height: 600px;
      border: 1px solid #ccc;
      background-color: #fff;
    }
  </style>
</head>
<body>
  <div id="graph-container"></div>

  <!-- รวมสคริปต์ GGraphs -->
  <script src="path/to/ggraphs.js"></script>
  <script>
    // โค้ดการตั้งค่าเริ่มต้นของคุณที่นี่
   </script>
</body>
</html>

หมายเหตุ: เปลี่ยน path/to/ggraphs.js ให้เป็นเส้นทางที่ถูกต้องไปยังไฟล์ ggraphs.js ของคุณ

การใช้งานเบื้องต้น

ตัวอย่างพื้นฐาน

สร้าง container สำหรับกราฟและเริ่มต้น GGraphs ด้วยข้อมูลของคุณ

<!DOCTYPE html>
<html lang="th">
<head>
  <meta charset="UTF-8">
  <title>ตัวอย่างกราฟเส้น GGraphs</title>
  <style>
    #line-chart {
      width: 800px;
      height: 600px;
      border: 1px solid #ccc;
      background-color: #fff;
    }
  </style>
</head>
<body>
  <div id="line-chart"></div>

  <script src="path/to/ggraphs.js"></script>
  <script>
    const data = [
      {
        name: 'ยอดขาย',
        color: '#FF6B6B',
        data: [
          { label: 'มกราคม', value: 30 },
          { label: 'กุมภาพันธ์', value: 20 },
          { label: 'มีนาคม', value: 50 },
          // เพิ่มข้อมูลเพิ่มเติม...
         ]
      },
      {
        name: 'ค่าใช้จ่าย',
        color: '#4ECDC4',
        data: [
          { label: 'มกราคม', value: 25 },
          { label: 'กุมภาพันธ์', value: 15 },
          { label: 'มีนาคม', value: 35 },
          // เพิ่มข้อมูลเพิ่มเติม...
         ]
      }
    ];

    const graph = new GGraphs('line-chart', {
      type: 'line',
      data: data,
      showLegend: true,
      legendPosition: 'bottom',
      onClick: (event) => {
        console.log('คุณคลิก:', event);
      }
    });
  </script>
</body>
</html>

คำอธิบายโค้ด

  1. กำหนด Container: สร้าง <div> ที่จะใช้เป็นพื้นที่สำหรับกราฟ
  2. โหลด GGraphs: รวมไฟล์ ggraphs.js ลงในหน้า HTML
  3. กำหนดข้อมูล: สร้างอาร์เรย์ของอ็อบเจ็กต์ที่แทนข้อมูลแต่ละชุด
  4. เริ่มต้น GGraphs: สร้างอินสแตนซ์ของ GGraphs โดยระบุ ID ของ container และตัวเลือกต่างๆ

การตั้งค่าและปรับแต่ง

GGraphs ให้ความยืดหยุ่นในการปรับแต่งผ่านอ็อบเจ็กต์ options ที่ส่งให้กับคอนสตรัคเตอร์ นี่คือรายละเอียดของตัวเลือกที่สามารถปรับได้

การตั้งค่าพื้นฐาน

  • type (string): ประเภทของกราฟที่ต้องการ ('line', 'bar', 'pie', 'donut', 'gauge')
  • data (Array): อาร์เรย์ของอ็อบเจ็กต์ series ที่มี name, color, และ data points
  • showLegend (boolean): แสดงหรือไม่แสดง legend
  • legendPosition (string): ตำแหน่งของ legend ('top', 'bottom', 'left', 'right')
  • showTooltip (boolean): เปิดหรือปิด tooltip
  • animation (boolean): เปิดหรือปิดแอนิเมชัน
  • onClick (function): ฟังก์ชัน callback สำหรับเหตุการณ์การคลิกบนองค์ประกอบของกราฟ

ตัวเลือกเพิ่มเติม

  • colors (Array<string>): อาร์เรย์ของสีที่ใช้ในกราฟ
  • gridColor (string): สีของเส้นกริด
  • axisColor (string): สีของแกนกราฟ
  • curveType (string): สำหรับกราฟเส้น ('linear' หรือ 'curve')
  • maxGaugeValue (number): ค่าสูงสุดสำหรับกราฟเกจ
  • centerText (string): ข้อความที่จะแสดงตรงกลางกราฟ (เหมาะสำหรับกราฟโดนัทและเกจ)
  • showCenterText (boolean): แสดงหรือไม่แสดงข้อความตรงกลางกราฟ
  • gap (number): ช่องว่างระหว่าง slice ในกราฟวงกลมและโดนัท
  • borderWidth (number): ความหนาของเส้นขอบ
  • borderColor (string): สีของเส้นขอบ
  • pointRadius (number): รัศมีของจุดข้อมูลในกราฟเส้น
  • lineWidth (number): ความหนาของเส้นในกราฟเส้น
  • fillArea (boolean): เติมพื้นที่ใต้เส้นในกราฟเส้น
  • fillOpacity (number): ความโปร่งใสาของพื้นที่ที่เติม
  • fontFamily (string): ฟอนต์ที่ใช้ในกราฟ
  • textColor (string): สีของข้อความในกราฟ
  • fontSize (number): ขนาดฟอนต์พื้นฐาน
  • showAxisLabels (boolean): แสดงหรือไม่แสดงป้ายชื่อบนแกน
  • showAxis (boolean): แสดงหรือไม่แสดงแกนกราฟ
  • animationDuration (number): ระยะเวลาแอนิเมชัน (เป็นมิลลิวินาที)
  • donutThickness (number): ความหนาของรูในกราฟโดนัท
  • gaugeCurveWidth (number): ความหนาของเส้นโค้งในกราฟเกจ
  • showDataLabels (boolean): แสดงหรือไม่แสดงป้ายชื่อข้อมูลบนองค์ประกอบของกราฟ
  • maxDataPoints (number): จำนวนข้อมูลสูงสุดที่จะแสดง (ตั้งเป็น 0 เพื่อไม่จำกัด)
  • table (string): ID ของตาราง HTML ที่จะใช้โหลดข้อมูล
  • และตัวเลือกอื่น ๆ สำหรับการปรับแต่งเพิ่มเติม

ตัวอย่างการตั้งค่าเพิ่มเติม

const graph = new GGraphs('graph-container', {
  type: 'bar',
  data: data,
  showLegend: true,
  legendPosition: 'right',
  showGrid: true,
  gridColor: '#E0E0E0',
  axisColor: '#333333',
  colors: ['#FF6B6B', '#4ECDC4'],
  borderWidth: 2,
  borderColor: '#000000',
  animationDuration: 1500,
  onClick: (event) => {
    console.log(`คุณคลิกบน ${event.type} ใน series "${event.series.name}" มี label "${event.data.label}" และ value "${event.data.value}"`);
  }
});

การจัดการเหตุการณ์ (Event Handling)

GGraphs ให้ความสามารถในการจัดการเหตุการณ์ต่าง ๆ ผ่านตัวเลือก onClick ซึ่งเป็นฟังก์ชัน callback ที่จะถูกเรียกเมื่อผู้ใช้คลิกบนองค์ประกอบของกราฟ เช่น บาร์, จุดข้อมูล, slice ของวงกลม เป็นต้น

การใช้งาน onClick

const graph = new GGraphs('graph-container', {
  type: 'pie',
  data: pieData,
  onClick: (event) => {
    if (event.type === 'pie') {
      alert(`คุณคลิกบน ${event.data.label} ที่มีค่า ${event.data.value}`);
    }
  }
});

รายละเอียดของ Event Object

  • type (string): ประเภทขององค์ประกอบที่ถูกคลิก ('line', 'bar', 'point', 'pie', 'gauge')
  • series (Object): อ็อบเจ็กต์ series ที่เกี่ยวข้องกับองค์ประกอบที่ถูกคลิก
  • data (Object): อ็อบเจ็กต์ข้อมูลที่เกี่ยวข้องกับองค์ประกอบที่ถูกคลิก

การปรับแต่งเพิ่มเติม

GGraphs ให้ความยืดหยุ่นในการปรับแต่งกราฟของคุณได้อย่างเต็มที่

  • การกำหนดสี: ปรับสีของแต่ละ series หรือองค์ประกอบในกราฟ
  • ฟอนต์และขนาด: ปรับเปลี่ยนฟอนต์และขนาดของข้อความให้เหมาะสมกับการออกแบบ
  • ตำแหน่ง Legend: เลือกตำแหน่งของ legend ได้หลายแบบ เช่น ด้านบน ด้านล่าง ซ้าย ขวา
  • Tooltips: ปรับแต่งเนื้อหาของ tooltip ผ่านฟังก์ชัน formatter
  • แอนิเมชัน: เปิดหรือปิดแอนิเมชัน และกำหนดระยะเวลาแอนิเมชัน
  • การออกแบบตอบสนอง: ให้กราฟปรับขนาดได้ตามขนาดของ container โดยอัตโนมัติ
  • ป้ายชื่อข้อมูล: เปิดหรือปิดการแสดงป้ายชื่อข้อมูลบนองค์ประกอบของกราฟ

ตัวอย่างการใช้งาน

กราฟเส้น (Line Chart)

<div id="line-chart" style="width: 800px; height: 600px;"></div>

<script src="path/to/ggraphs.js"></script>
<script>
  const data = [
    {
      name: 'ยอดขาย',
      color: '#FF6B6B',
      data: [
        { label: 'มกราคม', value: 100 },
        { label: 'กุมภาพันธ์', value: 150 },
        { label: 'มีนาคม', value: 200 },
        // ข้อมูลเพิ่มเติม...
       ]
    },
    {
      name: 'กำไร',
      color: '#4ECDC4',
      data: [
        { label: 'มกราคม', value: 50 },
        { label: 'กุมภาพันธ์', value: 70 },
        { label: 'มีนาคม', value: 90 },
        // ข้อมูลเพิ่มเติม...
       ]
    }
  ];

  const lineChart = new GGraphs('line-chart', {
    type: 'line',
    data: data,
    showLegend: true,
    legendPosition: 'bottom',
    fillArea: true,
    fillOpacity: 0.2,
    onClick: (event) => {
      console.log('คุณคลิกบน:', event);
    }
  });
</script>

กราฟวงกลม (Pie Chart)

<div id="pie-chart" style="width: 800px; height: 600px;"></div>

<script src="path/to/ggraphs.js"></script>
<script>
  const pieData = [
    {
      name: 'ส่วนแบ่งตลาด',
      color: '#FF6B6B',
      data: [
        { label: 'ผลิตภัณฑ์ A', value: 40 },
        { label: 'ผลิตภัณฑ์ B', value: 25 },
        { label: 'ผลิตภัณฑ์ C', value: 35 }
      ]
    }
  ];

  const pieChart = new GGraphs('pie-chart', {
    type: 'pie',
    data: pieData,
    showLegend: true,
    legendPosition: 'right',
    showDataLabels: true,
    onClick: (event) => {
      alert(`คุณคลิกบน ${event.data.label} ที่มีค่า ${event.data.value}`);
    }
  });
</script>

กราฟเกจ (Gauge Chart)

<div id="gauge-chart" style="width: 800px; height: 600px;"></div>

<script src="path/to/ggraphs.js"></script>
<script>
  const gaugeData = [
    {
      name: 'ประสิทธิภาพ',
      color: '#4ECDC4',
      data: [
        { label: 'ประสิทธิภาพ', value: 75 }
      ]
    }
  ];

  const gaugeChart = new GGraphs('gauge-chart', {
    type: 'gauge',
    data: gaugeData,
    maxGaugeValue: 100,
    centerText: '75%',
    showLegend: false,
    onClick: (event) => {
      console.log('คุณคลิกบนเกจ:', event);
    }
  });
</script>

คำถามที่พบบ่อย

1. ทำไมกราฟไม่แสดงผล?

ตรวจสอบให้แน่ใจว่า

  • ได้รวมไฟล์ ggraphs.js อย่างถูกต้อง
  • กำหนด ID ของ container ให้ตรงกับที่ระบุในคอนสตรัคเตอร์
  • ข้อมูลที่ส่งให้มีรูปแบบที่ถูกต้อง

2. สามารถปรับแต่งสีของกราฟได้อย่างไร?

กำหนดสีสำหรับแต่ละ series ในอ็อบเจ็กต์ data หรือใช้ตัวเลือก colors ใน options

const graph = new GGraphs('graph-container', {
  data: data,
  colors: ['#FF6B6B', '#4ECDC4'],
  // ตัวเลือกอื่น ๆ...
 });

3. ฉันสามารถเพิ่มข้อมูลแบบไดนามิกได้หรือไม่?

ได้ คุณสามารถใช้เมธอด addDataPoint หรือ addDataPoints เพื่อเพิ่มข้อมูลใหม่หลังจากที่กราฟถูกสร้างขึ้นแล้ว

// เพิ่มจุดข้อมูลใหม่ไปยัง series แรก
 graph.addDataPoint({ label: 'มิถุนายน', value: 60 }, 0);

// เพิ่มหลายจุดข้อมูลพร้อมกัน
 graph.addDataPoints([
  { seriesIndex: 0, data: { label: 'กรกฎาคม', value: 70 } },
  { seriesIndex: 1, data: { label: 'กรกฎาคม', value: 45 } }
]);

การสนับสนุนและการมีส่วนร่วม

หากคุณพบปัญหาหรือมีข้อเสนอแนะเกี่ยวกับ GGraphs สามารถสอบถามได้ที่เว็บไซต์ Kotchasan.com ได้ตลอดเวลา

ใบอนุญาต

GGraphs เปิดให้ใช้งานภายใต้ MIT License

ตัวอย่าง

https://goragodwiriya.github.io/ggraphs/

ดาวน์โหลดโค้ดได้จาก Github