ایجاد انواع نمودار

در این صفحه نحوه توسعه نوع نمودار خود و در دسترس قرار دادن آن برای کاربران توضیح داده شده است.

حضار

این صفحه فرض می کند که صفحه استفاده از نمودارها را خوانده اید. همچنین فرض می کند که شما با جاوا اسکریپت و برنامه نویسی شی گرا آشنا هستید. بسیاری از آموزش های جاوا اسکریپت در وب وجود دارد.

ایجاد نمودار

نمودارها از طریق کتابخانه جاوا اسکریپتی که شما ایجاد می کنید در معرض دید کاربر قرار می گیرند. در اینجا مراحل ایجاد یک کتابخانه نمودار آمده است:

  1. یک فضای نام برای کد خود انتخاب کنید. صفحات دیگر میزبان کد شما خواهند بود. شما باید سعی کنید از تعارضات نامگذاری خودداری کنید.
  2. شی نمودار خود را پیاده سازی کنید. یک شی جاوا اسکریپت را پیاده سازی کنید که موارد زیر را نشان می دهد:
    • یک سازنده،
    • یک متد draw() برای ترسیم شی شما در داخل عنصر DOM که به سازنده ارسال شده است،
    • هر روش استاندارد اختیاری دیگری برای استفاده از مشتری، مانند getSelection() و
    • هر روش سفارشی که می خواهید در معرض دید مشتریان خود قرار دهید.
  3. [ اختیاری ] هر رویدادی را که می‌خواهید شلیک کنید تا مشتری بگیرد را اجرا کنید .
  4. مستندات نمودار خود را بنویسید. اگر آن را مستند نکنید، مردم احتمالاً نخواهند توانست آن را جاسازی کنند.
  5. نمودار خود را در گالری نمودار ارسال کنید.

نکته

  • برای فعال کردن تکمیل خودکار در IDE (ویرایشگر کد) می توانید تعاریف کلاس و روش API goog.visualization را دانلود کنید. فایل را از http://www.google.com/uds/modules/gviz/gviz-api.js دانلود کرده و در پروژه خود ذخیره کنید. اکثر IDE ها آن را به طور خودکار فهرست می کنند و تکمیل خودکار را فعال می کنند، اگرچه IDE شما ممکن است متفاوت باشد. توجه داشته باشید که ممکن است فایل همیشه به روز نباشد. صفحات مرجع را برای به روزترین مرجع API بررسی کنید.

یک فضای نام را انتخاب کنید

نمودار شما می تواند در صفحه ای جاسازی شود که میزبان نمودارهای دیگر یا جاوا اسکریپت نامرتبط است. برای جلوگیری از تداخل نام‌گذاری با سایر کدها یا نام‌های کلاس CSS، باید یک فضای نام منحصربفرد برای کد نمودار خود انتخاب کنید. یک انتخاب خوب برای فضای نام، آدرس اینترنتی است که برای میزبانی اسکریپت خود استفاده می کنید (منهای WWW و هر پسوندی). بنابراین، برای مثال، اگر نمودار شما در www.example.com پست شود، example به عنوان فضای نام منحصر به فرد خود استفاده می کنید. می توانید پسوندهای اضافی اضافه کنید که با . برای گروه بندی بیشتر نمودار خود را علامت گذاری کنید (همه نمودارهای Google دارای فضای نام google.visualization هستند). از شی فضای نام خود برای ذخیره شی نمودار خود و همچنین هر متغیر جهانی که ممکن است نیاز داشته باشید استفاده کنید.

در اینجا یک مثال از ایجاد یک شی فضای نام برای نگهداری یک کلاس نمودار به نام MyTable و همچنین هر متغیر جهانی مورد نیاز آورده شده است:

// Namespace, implemented as a global variable.
var example = {};

// MyTable class constructor.
example.MyTable = function(container) {
  // ...
}

// MyTable.draw() method.
example.MyTable.prototype.draw = function(data, options) {
  // ...
}

اجتناب از تضادهای CSS

اگر از CSS استفاده می کنید، مطمئن شوید که قوانین CSS را که می تواند بر نمودارهای دیگر صفحه تأثیر بگذارد، ننویسید. برای مثال، قاعده‌ای مانند td {color: blue;} به شدت ممنوع است، زیرا بر هر عنصر <td> دیگر در صفحه تأثیر می‌گذارد، نه تنها در نمودار شما. یک راه برای غلبه بر این مشکل این است که کل نمودار خود را در یک <div> با نام کلاس محصور کنید و تمام قوانین CSS شما فقط برای عناصری اعمال شود که از فرزندان عنصری با نام کلاس هستند. به عنوان مثال، قانون CSS زیر فقط بر عناصر <td> تأثیر می گذارد که عنصری با نام کلاس "example" به عنوان جد دارند.

td.example {color: blue;}

سپس می توانید نمودار خود را در یک <div> با :

<div class="example">
  ...
</div>

نمودار خود را پیاده سازی کنید

شما باید نمودار خود را به عنوان یک شی جاوا اسکریپت پیاده سازی کنید که روش های استاندارد شرح داده شده در بخش مرجع را نشان می دهد. دو متد مورد نیاز عبارتند از: constructor و draw(). شما همچنین می توانید هر روش اضافی را که برای نمودار شما مناسب است در معرض دید کاربر خود قرار دهید. فقط به یاد داشته باشید که استفاده راحت تر بهتر است.

سازنده

نمودار شما باید یک سازنده واحد را نشان دهد که یک پارامتر واحد را می گیرد، یک عنصر DOM که نمودار خود را در آن ترسیم می کنید. به طور معمول، نمودارها یک کپی محلی از این عنصر را برای استفاده بعدی در سازنده ذخیره می کنند:

function example.MyTable(container) {
  this.container = container
}

روش draw()

کلاس نمودار شما باید دارای یک متد draw() باشد که در نمونه اولیه کلاس نمودار شما تعریف شده است. متد draw() دو پارامتر را می پذیرد:

  1. یک DataTable که داده ها را برای نمایش نگه می دارد.
  2. نقشه اختیاری از گزینه های نام/مقدار برای نمودار شما. نام و انواع مقادیر گزینه ها توسط شما برای نمودار خاص شما تعریف شده است. به عنوان مثال، در مثال Hello Chart زیر، نمودار از گزینه ای به نام "showLineNumber" با مقداری از نوع Boolean پشتیبانی می کند. شما باید یک مقدار پیش فرض برای هر گزینه پشتیبانی کنید، در صورتی که کاربر مقداری را برای یک گزینه خاص ارسال نکند. این پارامتر اختیاری است، بنابراین اگر کاربر از این پارامتر عبور نکرد، باید آماده استفاده از تمام مقادیر پیش فرض باشید ( اطلاعات بیشتر ).
example.MyTable.prototype.draw = function(data, options) {
  // Process data and options and render output into the container element.
  ...
}

سلام نمودار!

در اینجا یک نمودار ساده است که داده های DataTable را به عنوان یک جدول HTML نمایش می دهد:

و این هم کد پیاده سازی:

// Declare a unique namespace.
var example = {};

// Class constructor. Parameter container is a DOM elementon the client that
// that will contain the chart.
example.MyTable = function(container) {
  this.containerElement = container;
}

// Main drawing logic.
// Parameters:
//   data is data to display, type google.visualization.DataTable.
//   options is a name/value map of options. Our example takes one option.
example.MyTable.prototype.draw = function(data, options) {

  // Create an HTML table
  var showLineNumber = options.showLineNumber; // Boolean configuration option.

  var html = [];
  html.push('<table border="1">');

  // Header row
  html.push('<tr>');
  if (showLineNumber) {
    html.push('<th>Seq</th>');
  }
  for (var col = 0; col < data.getNumberOfColumns(); col++) {
    html.push('<th>' + this.escapeHtml(data.getColumnLabel(col)) + '</th>');
  }
  html.push('</tr>');

  for (var row = 0; row < data.getNumberOfRows(); row++) {
    html.push('<tr>');
    if (showLineNumber) {
      html.push('<td align="right">', (row + 1), '</td>');
    }

    for (var col = 0; col < data.getNumberOfColumns(); col++) {
      html.push(data.getColumnType(col) == 'number' ? '<td align="right">' : '<td>');
      html.push(this.escapeHtml(data.getFormattedValue(row, col)));
      html.push('</td>');
    }
    html.push('</tr>');
  }
  html.push('</table>');

  this.containerElement.innerHTML = html.join('');
}

// Utility function to escape HTML special characters
example.MyTable.prototype.escapeHtml = function(text) {
  if (text == null)
    return '';
  return text.replace(/&/g, '&').replace(/</g, '<')
      .replace(/>/g, '>').replace(/"/g, '"');
}

از جمله نمودار شما در یک صفحه وب

برای استفاده از نمودار قبلی، آن را در یک فایل js. قابل دسترسی از مرورگر خود ذخیره کنید. سپس کد زیر را ذخیره کنید و پارامتر منبع <script> را تغییر دهید تا به فایل جاوا اسکریپت شما اشاره کند:

<html>
  <head>
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type="text/javascript" src="mytablevis.js"></script>
    <script type="text/javascript">
      google.charts.load("current");

      // Set callback to run when API is loaded
      google.charts.setOnLoadCallback(drawVisualization);

      // Called when the Chart API is loaded.
      function drawVisualization() {

        // Create and populate a data table.
        var data = new google.visualization.DataTable();
        data.addColumn('string', 'Task');
        data.addColumn('number', 'Daily Hours');
        data.addRows(5);
        data.setCell(0, 0, 'Work');
        data.setCell(0, 1, 11);
        // Add more data rows and cells here

        // Instantiate our table object.
        var vis = new example.MyTable(document.getElementById('mydiv'));

        // Draw our table with the data we created locally.
        vis.draw(data, {showLineNumber: true});
       }
   </script>
  <title>MyTable example page</title></head>
  <body>
    <div id="mydiv"></div>
    <p>This page demonstrates hosting a table visualization.</p>
  </body>
</html>

رویدادهای خود را اجرا کنید

اگر می‌خواهید نمودار شما رویدادهای مفیدی را فعال کند (مثلاً رویدادهای تایمر یا رویدادهای آغاز شده توسط کاربر مانند کلیک‌ها)، باید تابع google.visualization.events.trigger را با جزئیات رویداد خود (نام، خواص برای ارسال و غیره). می توانید جزئیات را در صفحه رویدادها پیدا کنید. می‌توانید جزئیات رویداد خود را با افزودن ویژگی‌ها به شی رویداد در معرض دید مشتری قرار دهید، یا می‌توانید یک متد get...() از نوعی را در نمودار خود در معرض دید قرار دهید، و مشتری می‌تواند آن متد را برای دریافت جزئیات رویداد فراخوانی کند. در هر صورت، روش ها یا ویژگی های رویداد خود را به خوبی مستند کنید.

نمودار خود را مستند کنید

اگر نمودار خود را به درستی مستند نکنید، احتمالاً کاربران زیادی نخواهید داشت. حتما موارد زیر را مستند کنید:

  • تمام روش هایی که پشتیبانی می کنید را شرح دهید. متد draw() برای همه نمودارها مشترک است، اما هر نمودار می تواند متدهای اضافی خود را پشتیبانی کند. (شما احتمالاً نیازی به مستندسازی سازنده خود ندارید، مگر اینکه رفتار غیر استانداردی داشته باشد.) می توانید لیستی از روش های مورد انتظار را در صفحه مرجع پیدا کنید.
  • تمام گزینه هایی که متد draw() شما پشتیبانی می کند را شرح دهید. این شامل نام هر گزینه، نوع مقدار مورد انتظار و مقدار پیش فرض آن است.
  • تمام وقایعی را که باعث می‌شوید توصیف کنید. این به معنی نام و ویژگی های هر رویداد و زمانی است که هر رویداد راه اندازی می شود.
  • URL کتابخانه نمودار خود را که باید در عبارت <script> کلاینت مورد استفاده قرار گیرد فهرست کنید و URL را برای مستندات خود ارائه دهید.
  • نام کامل نمودار خود را بنویسید.
  • صفحات نمونه ای ایجاد کنید که نحوه استفاده از نمودار خود را با گزینه هایی که پشتیبانی می کند، رویدادهای آن و روش های سفارشی را نشان می دهد.
  • خط مشی داده نمودار خود را به وضوح شرح دهید. اکثر نمودارها داده ها را در مرورگر پردازش می کنند، اما برخی ممکن است داده ها را به سرور ارسال کنند، به عنوان مثال برای ایجاد تصویری از نمودار یا نقشه. اگر داده ها را به سرور ارسال می کنید:
    • به وضوح مشخص کنید که کدام داده ارسال می شود.
    • توجه داشته باشید که چه مدت داده ها در سرور ذخیره می شوند.
    • اسنادی که نهادها به داده ها دسترسی خواهند داشت. به عنوان مثال، شرکت XYZ و غیره.
    • مشخص کنید که آیا داده ها ثبت می شوند و برای چه مدت.

اسناد شما در همان مکان کد نمودار شما میزبانی می شود ( به ارسال نمودار خود به گالری زیر مراجعه کنید).

پس از اینکه نمودار خود را نوشتید، آن را برای ارسال در بخش "نمودارهای اضافی" گالری ما ارسال کنید . ارسال نمودار به این معنی است که شما باید با ما توافق نامه ای امضا کنید که در آن نرم افزار مخرب ایجاد نکنید یا از داده های کاربر سوء استفاده نکنید. گالری فقط فهرستی از اشاره گرها به نمودارهایی است که ایجاد کرده ایم یا آنها را بررسی کرده ایم. می‌توانید انتخاب کنید که کتابخانه و اسناد جاوا اسکریپت واقعی را در سایت خود میزبانی کنید ، یا می‌توانید از Google میزبانی کتابخانه و اسناد را برای شما داشته باشید. مشخص کنید که آیا می خواهید نمودار شما را هنگام ارسال آن به گالری میزبانی کنیم یا خیر.

عیب یابی

اگر به نظر می رسد کد شما کار نمی کند، در اینجا چند روش وجود دارد که ممکن است به شما در حل مشکلات کمک کند:

  • به دنبال اشتباهات تایپی باشید به یاد داشته باشید که جاوا اسکریپت یک زبان حساس به حروف بزرگ و کوچک است.
  • از یک دیباگر جاوا اسکریپت استفاده کنید. در فایرفاکس، می‌توانید از کنسول جاوا اسکریپت، Venkman Debugger یا افزونه Firebug استفاده کنید. در اینترنت اکسپلورر، می توانید از Microsoft Script Debugger استفاده کنید.
  • گروه بحث Google Chart API را جستجو کنید. اگر نمی توانید پستی را پیدا کنید که به سؤال شما پاسخ دهد، سؤال خود را به همراه پیوندی به یک صفحه وب که مشکل را نشان می دهد به گروه ارسال کنید.

بومی سازی

اگر انتظار دارید نمودار شما توسط افراد در کشورهای مختلف مورد استفاده قرار گیرد، ممکن است بخواهید نمودار خود را طوری طراحی کنید که برای زبان ها و فرهنگ های مختلف بومی سازی شود. ابتدایی‌ترین محلی‌سازی ترجمه رشته‌های متن استاندارد در UI با توجه به تنظیمات مرورگر کاربر است. یک شکل پیشرفته‌تر محلی‌سازی، تغییر قالب‌های اعداد بسته به محلی‌سازی یا احتمالاً حتی طراحی UI است. اگر تصمیم دارید نمودار خود را بومی سازی کنید، زبان هایی را که نمودار شما از آنها پشتیبانی می کند در اسناد خود فهرست کنید و یک تنظیم پیش فرض برای یک زبان رایج ارائه دهید. همچنین مفید است که دکمه "تغییر زبان" را در رابط کاربری نمودار خود قرار دهید، در صورتی که زبان را اشتباه متوجه شوید. روش رایج برای تشخیص زبان مرورگر، نگاه کردن به هدر Accept-Language HTML است.