Tworzenie typów wykresów

Na tej stronie opisano, jak utworzyć własny typ wykresu i udostępnić go użytkownikom.

Odbiorcy

Ta strona zakłada, że znasz stronę Korzystanie z wykresów. Zakładamy też, że znasz się na języku JavaScript i programowaniu zorientowanym na obiekty. W internecie dostępnych jest wiele samouczków JavaScript.

Tworzenie wykresu

Wykresy są udostępniane użytkownikowi za pomocą utworzonej przez Ciebie biblioteki JavaScript. Aby utworzyć bibliotekę wykresów:

1. Wybierz przestrzeń nazw dla kodu. Na innych stronach będzie hostowany Twój kod. Postaraj się unikać konfliktów nazw.
2. Zaimplementuj obiekt wykresu. Zaimplementuj obiekt JavaScript, który ujawnia te elementy:
   • Konstruktor,
   • Metoda draw() narysowania obiektu w elemencie DOM przekazanym do konstruktora,
   • Inne opcjonalne metody standardowe, których może używać klient, np. getSelection() i
   • Wszelkie metody niestandardowe, które chcesz pokazać klientom.
3. [Opcjonalnie] Zaimplementuj wszystkie zdarzenia, które mają być uruchamiane przez klienta.
4. Utwórz dokumentację dotyczącą wykresu. Jeśli tego nie udokumentujesz, użytkownicy prawdopodobnie nie będą mogli go umieścić.
5. Publikuj wykres w Galerii wykresów.

Wybierz przestrzeń nazw

Wykres może być umieszczony na stronie, która zawiera inne wykresy lub inny niepowiązany kod JavaScript. Aby uniknąć konfliktów z nazwami innych kodów lub nazw klas CSS, wybierz unikalną przestrzeń nazw kodu wykresu. Dobrym wyborem w przypadku przestrzeni nazw jest adres URL, którego będziesz używać do hostowania skryptu (bez stron internetowych i rozszerzeń). Jeśli więc na przykład Twój wykres zostanie opublikowany na stronie www.example.com, Twoja unikalna przestrzeń nazw będzie wyglądać tak: example. Możesz dodać więcej sufiksów rozdzielonych znakiem w celu dalszego zgrupowania wykresu (na wszystkich wykresach jest przestrzeń nazw google.visualization). Za pomocą obiektu przestrzeni nazw możesz przechowywać obiekt wykresu oraz wszelkie potrzebne zmienne globalne.

Oto przykład tworzenia obiektu przestrzeni nazw do przechowywania klasy wykresu o nazwie MyTable oraz wszelkich wymaganych zmiennych globalnych:

// 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) {
  // ...
}

Unikanie konfliktów CSS

Jeśli używasz CSS, uważaj, aby nie tworzyć reguł CSS, które mogą mieć wpływ na inne wykresy na stronie. Na przykład zdecydowanie odradzamy stosowanie reguły takiej jak td {color: blue;}, ponieważ ma ona wpływ na wszystkie inne elementy <td> na stronie, nie tylko na wykresie. Jednym ze sposobów rozwiązania tego problemu jest umieszczenie całego wykresu w elemencie <div> z nazwą klasy i stosowanie wszystkich reguł CSS wyłącznie do elementów, które są elementami potomnymi elementu o tej nazwie. Na przykład ta reguła CSS wpłynie tylko na elementy <td>, które mają element o nazwie „example” jako element nadrzędny.

td.example {color: blue;}

Następnie możesz dodać wykres do tabeli <div> za pomocą :

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

Implementacja wykresu

Musisz wdrożyć wykres jako obiekt JavaScript, który udostępnia standardowe metody opisane w sekcji referencyjnej. Dwie wymagane metody to konstruktor i metody pull(). Możesz też wyświetlić użytkownikom dodatkowe metody, które są odpowiednie dla Twojego wykresu. Pamiętaj tylko, że jest łatwiejszy w użyciu.

Konstruktor

Wykres powinien ujawniać jeden konstruktor, który przyjmuje jeden parametr – element DOM, w którym zostanie narysowany wykres. Zwykle wykresy zapisują lokalną kopię tego elementu w konstruktorze do późniejszego wykorzystania:

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

Metoda draw()

Klasa wykresu powinna mieć metodę draw() zdefiniowaną w prototypie klasy wykresu. Metoda draw() akceptuje 2 parametry:

1. DataTable, który zawiera dane do wyświetlenia.
2. Opcjonalna mapa z nazwą lub wartością wykresu. Nazwy i typy wartości opcji definiuje się na potrzeby konkretnego wykresu. Na przykład przykładowego wykresu „Hello” wykres obsługuje opcję o nazwie „showLineNumber” z wartością typu logicznego. Dla każdej opcji należy użyć wartości domyślnej, na wypadek gdyby użytkownik nie podał wartości dla konkretnej opcji. Ten parametr jest opcjonalny, więc jeśli użytkownik nie przekazuje tego parametru, musisz też użyć wszystkich wartości domyślnych (więcej informacji).

example.MyTable.prototype.draw = function(data, options) {
  // Process data and options and render output into the container element.
  ...
}

Dzień dobry,

Oto prosty wykres, który wyświetla dane DataTable jako tabelę HTML:

A oto kod implementacji:

// 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, '"');
}

Umieszczanie wykresu na stronie internetowej

Aby użyć poprzedniego wykresu, zapisz go w pliku .js dostępnym w przeglądarce. Następnie zapisz ten kod, zmieniając parametr źródłowy <script> tak, by wskazywał plik JavaScript:

<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>

 

Implementacja zdarzeń

Jeśli chcesz, by wykres uruchamiał przydatne zdarzenia (np. zdarzenia licznika lub zdarzenia inicjowane przez użytkownika, takie jak kliknięcia), musisz wywołać funkcję google.visualization.events.trigger z informacjami o Twoim zdarzeniu (nazwa, właściwości do wysłania itd.). Szczegółowe informacje znajdziesz na stronie Zdarzenia. Możesz udostępnić szczegóły zdarzenia klientowi, dodając właściwości do obiektu zdarzenia, lub możesz wyświetlić metodę get...() dowolnego typu na wykresie, a klient może ją wywołać, aby uzyskać szczegóły zdarzenia. W obu przypadkach dobrze udokumentuj metody lub właściwości zdarzenia.

Dokumentowanie wykresu

Jeśli nie udokumentujesz poprawnie swojego wykresu, prawdopodobnie nie uzyskasz wielu użytkowników. Pamiętaj o udokumentowaniu:

• Opisz wszystkie obsługiwane przez Ciebie metody. Metoda draw() jest powszechna w przypadku wszystkich wykresów, ale każdy wykres może obsługiwać własne metody dodatkowe. (Prawdopodobnie nie musisz dokumentować konstruktora, chyba że ma niestandardowe zachowanie). Listę oczekiwanych metod znajdziesz na stronie referencyjnej.
• Opisz wszystkie opcje obsługiwane przez Twoją metodę draw(). Obejmuje to nazwę każdej opcji, oczekiwany typ wartości i wartość domyślną.
• Opisz wszystkie wywoływane zdarzenia. Oznacza to nazwę i właściwości każdego zdarzenia oraz termin jego wywołania.
• Wypisz adres URL biblioteki wykresów, która powinna być używana w instrukcji <script> klienta, i podaj adres URL dokumentacji.
• Podaj pełną nazwę wykresu.
• Utwórz przykładowe strony, które pokazują, jak korzystać z wykresu za pomocą obsługiwanych opcji, zdarzeń i metod niestandardowych.
• Jasno opisz zasady dotyczące danych przedstawione na wykresie. Większość wykresów przetwarza dane w przeglądarce, ale niektóre mogą wysyłać dane na serwer, np. w celu utworzenia obrazu wykresu lub mapy. Jeśli wysyłasz dane na serwer:
  • Wyraźnie określ, które dane mają być wysyłane.
  • Zapisz czas przechowywania danych na serwerze.
  • Sprawdź, które encje będą miały dostęp do danych. Na przykład Firma XYZ itp.
  • Określ, czy dane będą rejestrowane i jak długo.

Dokumentacja będzie przechowywana w tym samym miejscu co kod wykresu (patrz Przesyłanie wykresu do galerii poniżej).

Prześlij wykres do galerii

Po napisaniu wykresu prześlij go do opublikowania w sekcji „Dodatkowe wykresy”. Oznacza to, że musisz podpisać z nami umowę, by nie tworzyć złośliwego oprogramowania ani niewłaściwie używać danych użytkowników. Galeria to tylko lista wskaźników utworzonych przez nas lub sprawdzonych przez nas wykresów. Możesz hostować rzeczywistą bibliotekę JavaScript i jej dokumentację we własnej witrynie lub umieścić ją w Google. Określ, czy mamy wysyłać wykres do galerii.

Rozwiązywanie problemów

Jeśli Twój kod nie działa, oto kilka sposobów, które pomogą Ci rozwiązać problemy:

• Sprawdź, czy nie ma literówek. Pamiętaj, że w języku JavaScript rozróżniana jest wielkość liter.
• Użyj debugera JavaScriptu. W Firefoksie możesz używać konsoli JavaScript, narzędzia Venkman Debugger lub dodatku FireFire. W IE możesz użyć debugera Microsoft Script.
• Przeszukaj grupę dyskusyjną interfejsu Google Chart API. Jeśli nie możesz znaleźć posta z odpowiedzią na swoje pytanie, opublikuj pytanie w grupie wraz z linkiem do strony internetowej, na której widać występujący problem.

Lokalizacja

Jeśli spodziewasz się, że Twój wykres będzie używany przez użytkowników w różnych krajach, możesz go dostosować do różnych języków i kultur. Najprostsza lokalizacja to tłumaczenie standardowych ciągów tekstowych zgodnie z ustawieniami przeglądarki użytkownika. Bardziej zaawansowaną formą lokalizacji będzie zmiana formatu liczb w zależności od lokalizacji, a nawet projektu interfejsu użytkownika. Jeśli zdecydujesz się zlokalizować wykres, wymień języki obsługiwane w Twoim wykresie w dokumentacji i podaj domyślne ustawienie najczęściej używanego języka. Warto również pamiętać o uwzględnieniu w interfejsie przycisku przycisku zmiany języka, na wypadek, gdyby błąd był wynikiem błędu w języku. Częstym sposobem wykrywania języka przeglądarki jest sprawdzenie nagłówka HTML Accept-Language.