Formaty danych

Ten dokument wyjaśnia, jak wysyłać dane wykresów do interfejsu Google Chart API.

Spis treści

Przegląd

Dane niemal wszystkich wykresów są wysyłane za pomocą parametru chd. Dane należy wysyłać w jednym z tych formatów:

• Podstawowy format tekstowy to zasadniczo proste liczby zmiennoprzecinkowe z zakresu od 0 do 100 włącznie. Ten format jest łatwy do odczytania i pisania ręcznie.
• Format tekstowy z funkcją automatycznego skalowania umożliwia skalowanie wykresu w celu dopasowania go do danych.
• Format tekstowy ze skalowaniem niestandardowym jest podobny do podstawowego formatu tekstowego, jednak umożliwia określenie zakresu niestandardowego za pomocą drugiego parametru adresu URL.
• Prosty format kodowania umożliwia określenie wartości całkowitych z zakresu od 0 do 61 włącznie, zakodowanych za pomocą pojedynczego znaku alfanumerycznego. W ten sposób powstaje najkrótszy ciąg danych w dowolnym formacie (jeśli jakiekolwiek wartości są większe niż 9).
• Rozszerzony format kodowania umożliwia określenie wartości liczb całkowitych z zakresu od 0 do 4095 włącznie, kodowanych za pomocą 2 znaków alfanumerycznych. Rozszerzone kodowanie najlepiej sprawdza się w przypadku wykresów z dużą ilością danych i dużym zakresem danych.

Wartości danych są skalowane, aby pasowały do użytego formatu. Wyjaśnienie sposobu manipulowania danymi w celu dopasowania do wykresu znajdziesz w sekcjach Skalowanie danych i skalowanie osi.

Udostępniamy fragment kodu JavaScript do kodowania danych za pomocą prostego lub rozszerzonego formatu kodowania. Kilku członków grupy Chartów Google skorzystało też z innych bibliotek, które pomagają w formatowaniu: przeszukuj archiwa, by je znaleźć.

Podstawowy format tekstu

Podstawowe dane w formacie tekstowym umożliwiają określanie w postaci liczb zmiennoprzecinkowych wartości z zakresu od 0 do 100 włącznie. Wartości poniżej 0 są oznaczane jako brakujące. Wartości powyżej 100 są skracane do 100. Zaletą podstawowego formatu tekstowego jest to, że wartości w adresie URL są czytelne i zrozumiałe, a domyślne etykiety osi dokładnie pokazują wartości danych. Jednak formatowanie tekstu (proste lub z parametrami niestandardowymi) powoduje utworzenie najdłuższego ciągu danych spośród wszystkich formatów.

Jeśli Twoje dane zawierają wartości spoza określonego zakresu formatowania tekstu, możesz je skalować, konwertując je na wartości procentowe największej wartości zawartej w danych. Możesz też użyć formatowania tekstu ze skalowaniem niestandardowym, aby wykonać skalowanie za Ciebie.

Składnia:

chd=t:val,val,val|val,val,val...

<data>

Każda seria zawiera co najmniej jedną wartość rozdzielaną przecinkami. Rozdziel wiele serii pionową kreską (|). Wartości to liczby zmiennoprzecinkowe z zakresu od 0 do 100 włącznie. Wartości mniejsze od zera lub znak podkreślenia ( _ ) są uznawane za wartości null. Wartości powyżej 100 są skracane do 100.

 

Przykład:

Tabela z 5 wartościami. Podkreślenie jest uznawane za wartość null, wartość -30 jest poniżej wartości minimalnej, więc jest usuwana, a wartość 200 jest skracana do 100.

chd=t:_,30,-30,50,80,200

Powrót do góry

Formatowanie tekstu z automatycznym skalowaniem

Niektóre wykresy możesz skonfigurować tak, aby skalowały się automatycznie w celu dopasowania do ich danych. Wykres zostanie przeskalowany w taki sposób, że największa wartość znajduje się na górze, a najmniejsza (lub zero, jeśli wszystkie wartości są większe od zera) – na dole.

Wartości znaczników widoczne na wykresie pokazują wartości rzeczywiste, a nie skalowane.

Ta funkcja działa tylko w przypadku wartości w formacie tekstowym i nie działa na wszystkich typach wykresów. Eksperymentuj z typem wykresu, aby sprawdzić, czy jest on obsługiwany.

Składnia

cht=t:val,val,val...
chds=a

Przykłady:

chd=t:5,30,50,80,200 chds=a Pamiętaj, że w przypadku wykresów kołowych nie należy używać wartości < 0.

chd=t:-5,30,-30,50,80,200 chds=a

Powrót do góry

Formatowanie tekstu ze skalowaniem niestandardowym

Format tekstowy ze skalowaniem niestandardowym umożliwia określenie dowolnych dodatnich lub ujemnych liczb zmiennoprzecinkowych w połączeniu z parametrem skalowania, który umożliwia określenie niestandardowego zakresu dla wykresu. Ten wykres jest przydatny, gdy nie chcesz ograniczać danych do określonego zakresu lub nie chcesz skalować danych ręcznie, aby dobrze pasowały do wykresu. Ten format w razie potrzeby dostosuje linię zerową. Format danych jest taki sam jak w przypadku podstawowego formatu tekstowego.

W przypadku automatycznego skalowania wpisz chds=a.

Formatowanie tekstu (proste lub z parametrami niestandardowymi) powoduje utworzenie najdłuższego ciągu danych we wszystkich formatach.

Składnia:

Formatowanie tekstu za pomocą skalowania niestandardowego wymaga 2 parametrów:

chd=t:val,val,val|val,val,val
chds=<series_1_min>,<series_1_max>,...,<series_n_min>,<series_n_max>

chd=t:<data>

Tak samo jak w zwykłym formacie danych: co najmniej 1 wartość rozdzielana przecinkami na serię, kilka serii rozdzielonych pionową kreską (|). Zakres dozwolonych wartości w każdej serii jest określany za pomocą parametru chds.

chds

Zestaw zawierający co najmniej 1 minimalną i maksymalną dozwoloną wartość dla każdej serii danych rozdzielonych przecinkami. Musisz podać zarówno wartość maksymalną, jak i minimalną. Jeśli podasz mniej par niż jest serii danych, do wszystkich pozostałych serii danych zostanie zastosowana ostatnia para. Pamiętaj, że nie zmieni to zakresu osi. Aby zmienić zakres osi, musisz ustawić parametr chxr. Prawidłowe wartości to (+/-)9,999e(+/-)199. Możesz podać wartości w standardowym lub notacji E.

<series_1_min>

Minimalna dozwolona wartość w pierwszej serii. Mniejsze wartości są oznaczane jako brakujące.

<series_1_max>

Maksymalna dozwolona wartość w pierwszej serii. Wyższe wartości są obcinane do tej wartości.

 

Przykład:

Wykres słupkowy ze skalą min./maks. -80–140. Wartości 30, -60, 50, 140 i 80 mieszczą się w skali, więc nie są obcinane. Pamiętaj, że linia zero jest dostosowana do Ciebie: 80/(140 + 80) = 0,36 odchylenia osi Y w górę. Pomimo parametru chds domyślny zakres na osi Y nadal wynosi 0–100, więc wartości etykiet nie odzwierciedlają rzeczywistych wartości danych.

chd=t:30,-60,50,140,80,-90 chds=-80,140

Powrót do góry

Prosty format kodowania

Prosty format kodowania pozwala określić wartości całkowite z zakresu od 0 do 61 włącznie, zakodowane pojedynczym znakiem alfanumerycznym. W ten sposób powstaje najkrótszy URL ciągu danych spośród wszystkich formatów danych. Jeśli jednak masz wykres liniowy lub słupkowy dłuższy niż 100 pikseli wzdłuż osi danych, możesz użyć innego formatu. Dzieje się tak, ponieważ przy obsługiwanych tylko 62 wartościach danych szczegółowość danych jest znacznie większa niż szczegółowość wyświetlania, a wartości będą nieco inne (niewiele, ale będzie widoczne na większych wykresach).

Pamiętaj, że jeśli użyjesz parametru chds z prostym kodowaniem, nie będzie to miało wpływu na rozmiar elementu danych na wykresie, ale zmienią się wszystkie wartości znacznika punktu danych.

Składnia:

chd=s:
  <series_1>
    ,...,
  <series_n>

<seria_1>

Ciąg, w którym każdy znak to pojedynczy punkt danych, a serie są rozdzielone przecinkami. Poszczególne wartości w serii nie są rozdzielane. Oto obsługiwane znaki danych i odpowiadające im wartości:

• A—Z, gdzie A = 0, B = 1 itd., do Z = 25
• a—z, gdzie a = 26, b = 27 itd., do z = 51
• 0(zero)—9, gdzie 0 = 52, a 9 = 61
• Znak podkreślenia (_) wskazuje brakującą wartość

Możesz użyć tego narzędzia do kodowania pojedynczej wartości lub kodu JavaScript do skalowania i kodowania całego ciągu adresu URL.

Przykład:

Odpowiednik ciągu zakodowanego w tekście chd=t:1,19,27,53,61,-1|12,39,57,45,51,27

<title="chs=320x200&cht=bvs&chd=s:btb19_,mn5tzb&chco=ffcc33,ffe9a4&chxr=0,0,61,5&chxt=y" alt="Skumulowany wykres słupkowy z dwiema seriami i 6 wartościami, po 6 wartościach:Simple/chart=chff.png19&hl=pl" src="/static. chd=s:BTb19_,Mn5tzb

Powrót do góry

Rozszerzony format kodowania

Rozszerzony format kodowania pozwala określić wartości całkowite z zakresu 0–4095 włącznie, zakodowane za pomocą dwóch znaków alfanumerycznych. Korzysta on z nieco innej składni niż proste kodowanie.

Pamiętaj, że jeśli użyjesz parametru chds z prostym kodowaniem, nie będzie to miało wpływu na rozmiar elementu danych na wykresie, ale zmienią się wartości znaczników punktu danych.

Składnia:

chd=e:
  <series_1>
    ,...,
  <series_n>

<seria_1>

Ciąg, w którym każde 2 znaki to pojedynczy punkt danych, a serie są rozdzielone przecinkami. Poszczególne wartości w serii nie są rozdzielane. Oto obsługiwane znaki kodowania:

• A—Z
• a—z
• 0—9
• okres (.)
• łącznik (-)
• Brakujące wartości są oznaczone podwójnym podkreśleniem (__).

Oto skrócony opis zakodowanych wartości:

• AA = 0, AB = 1 itd. do AZ = 25
• Aa = 26, Ab = 27 i tak dalej do Az = 51
• A0 = 52, A1 = 53 i tak dalej do A9 = 61
• A- = 62, A. = 63
• BA = 64, BB = 65 i tak dalej do BZ = 89
• Ba = 90, Bb = 91 i tak dalej do Bz = 115
• B0 = 116, B1 = 117 i tak dalej do B9 = 125
• B- = 126, B. = 127
• 9A = 3904, 9B = 3905 i tak dalej na 9Z = 3929
• 9a = 3930, 9b = 3931 i tak dalej na 9z = 3955
• 90 = 3956, 91 = 3957 i tak dalej na 99 = 3965
• 9- = 3966, 9. = 3967
• -A = 3968, -B = 3969 i tak dalej na -Z = 3993
• -a = 3994, -b = 3995 i tak dalej na -z = 4019
• -0 = 4020, -1 = 4021 i tak dalej na -9 = 4029
• -- = 4030, -. = 4031
• .A = 4032, .B = 4033 i tak dalej do .Z = 4057
• .a = 4058, .b = 4059 i tak dalej na .z = 4083
• .0 = 4084, .1 = 4085 i tak dalej na .9 = 4093
• .- = 4094, .. = 4095

Możesz użyć tego narzędzia do kodowania pojedynczej wartości lub kodu JavaScript do skalowania i kodowania całego ciągu adresu URL.

Przykład:

Odpowiednik ciągu zakodowanego w tekście chd=t:90,1000,2700,3500|3968,-1,1100,250

chd=e:BaPoqM2s,-A__RMD6

Powrót do góry

Skalowanie danych i skalowanie osi

Dane są skalowane, aby dopasować je do wykresu – jawnie (w przypadku korzystania z formatu tekstowego ze skalowaniem niestandardowym) lub niejawnie (w przypadku wszystkich innych typów). Oznacza to, że każdy wykres jest skalowany tak, by pasował do dostępnego zakresu formatu, a nie do rzeczywistego zakresu dostarczonych przez Ciebie danych.

Możesz przeskalować dane tak, aby obejmowały pełny zakres wartości dozwolonych w danym formacie, aby były bardziej widoczne. Możesz skalować dane, skalując je zgodnie z używanym formatem lub bezpośrednio określając zakres danych (czyli używając formatu tekstowego ze skalowaniem niestandardowym).

Pamiętaj, że wartości etykiet osi są obliczane w całkowicie niezależnej skali i nie mają nic wspólnego z wartościami danych, ale użyjemy domyślnego zakresu 0–100. Możesz go jednak zmienić.

W tej sekcji opisano oba te problemy.

Dane są przeskalowane, aby pasowały do zakresu formatów [Wszystkie wykresy oprócz wykresów Kołowych i Venna]

Różne formaty obsługują różne zakresy wartości. Dane są skalowane do zakresu formatów, dzięki czemu maksymalna wartość obsługiwana przez format jest renderowana na górze tej osi, a minimalna wartość dla formatu – na dole. Poniższe przykłady pokazują tę samą wartość (100) w podstawowym formacie tekstowym (zakres 0–100), tekstu ze skalowaniem niestandardowym (zakres niestandardowy od 0 do 200) i rozszerzonym formatem kodowania (zakres 0–4095).

Podstawowy format tekstu	Format tekstowy z niestandardowym skalowaniem	Rozszerzony format kodowania
Wartość: 100 (chd=t:100) Zakres formatów: 0–100 Wartość 100 jest renderowana jako 100/100 w górnej skali.	Wartość 100 (chd=t:100, chds=0,200) Zakres formatów: 0–200 Wartość 100 jest renderowana 100/200 w górę skali.	Wartość: 100 (chd=e:Bk) Zakres formatu: 0–4095 Wartość 100 jest renderowana jako 100/4095 w górnej skali.

Łatwym sposobem skalowania danych, aby dopasować je do wykresu, jest użycie formatu tekstowego ze skalowaniem. Bardziej wymagająca metoda to ręczne skalowanie danych, by mieściły się w zakresie obsługiwanym przez Twój format.

Wykresy Kołowe i Venna: w przypadku wykresów kołowych i Venna wszystkie wartości są względem siebie, a nie do całkowitej skali wykresu.

chd=e:BkDIEs	chd=t:100,200,300 chds=0,300

Zakres etykiet osi jest obliczany niezależnie [słupkowy, liniowy, radarowy, punktowy i świecowy]

Aby wyświetlić wartości osi, użyj parametru chxt. Pamiętaj jednak, że etykiety osi nie są obliczane w celu odzwierciedlenia danych wykresu, ale są obliczane niezależnie przez interfejs API lub są określane bezpośrednio przez Ciebie.

Domyślny zakres osi wynosi 0–100, niezależnie od wartości danych czy skalowania danych. Jeśli więc na przykład wyświetlasz oś Y przy użyciu domyślnych etykiet osi na wykresie z rozszerzonym kodowaniem (zakres od 0 do 4095), etykiety na osi Y nadal będą odczytywać 0–100, chyba że wyraźnie zmienisz to ustawienie, jak opisano poniżej. Oto przykład domyślnych etykiet osi Y na rozszerzonym wykresie słupkowym kodowania z wartością danych 100:

chd=e:Bk (odpowiednik chd=t:100)

Zakres osi możesz jednak określić za pomocą parametru chxr. Jeśli chcesz, by wartości na osi odzwierciedlały rzeczywiste wartości danych, musisz określić minimalne i maksymalne wartości na osi, które pasują do zakresu formatów. Pamiętaj, że podstawowy format tekstowy ma już skalę od 0 do 100, więc jeśli używasz podstawowego formatowania tekstu (bez skalowania niestandardowego), wartości na osi będą domyślnie pasować do wartości danych. Przeanalizujmy to na kilku przykładach. Oto 3 wykresy z tymi samymi danymi (15,26,51,61), ale różnymi formatami i różnymi skalami osi:

Proste kodowanie, brak skalowania osi	Proste kodowanie, skalowana oś	Tekst podstawowy, bez skalowania osi
chd=s:Paz9   Zakres wartości prostego kodowania: 0–61 Domyślny zakres osi (0–100) Zakres kodowania jest mniejszy niż zakres osi etykiety, więc słupki nie odpowiadają rzeczywistej wartości na etykiecie osi. Słupki są jednak proporcjonalne do siebie.	chd=s:Paz9     chxr=0,0,61,10 Zakres wartości prostego kodowania: 0–61 Zakres osi ustawiony na 0–61 Zakres kodowania i zakres osi są równe, więc słupki odpowiadają ich poprawnej wartości na osi.	chd=t:15,26,51,61   Podstawowy zakres wartości formatu tekstowego: 0–100 Domyślny zakres osi (0–100) Zakres kodowania i zakres osi są ponownie takie same, więc dokładne wartości danych są domyślnie wyświetlane na osi. Zakres formatu tekstu jest większy niż zakres prostego formatu kodowania (100 a 61), dlatego słupki są na tym poziomie mniejsze niż na innych wykresach, ale wszystkie wykresy pozostają do siebie proporcjonalnie.

Powrót do góry

Skrypt kodowania JavaScript

W przypadku zastosowań w świecie rzeczywistym łatwiej jest zakodować dane programowo niż ręcznie.

Ten fragment kodu JavaScript koduje jedną serię na kodowanie proste lub extended oraz skaluje wartości danych tak, by mieściły się w pełnym zakresie tego kodowania. Dane należy podawać w postaci tablicy liczb dodatnich. Każda podana wartość, która nie jest liczbą dodatnią, jest kodowana jako brakująca wartość za pomocą znaku podkreślenia (_).

var simpleEncoding =
  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';

// This function scales the submitted values so that
// maxVal becomes the highest value.
function simpleEncode(valueArray,maxValue) {
  var chartData = ['s:'];
  for (var i = 0; i < valueArray.length; i++) {
    var currentValue = valueArray[i];
    if (!isNaN(currentValue) && currentValue >= 0) {
    chartData.push(simpleEncoding.charAt(Math.round((simpleEncoding.length-1) *
      currentValue / maxValue)));
    }
      else {
      chartData.push('_');
      }
  }
  return chartData.join('');
}

// Same as simple encoding, but for extended encoding.
var EXTENDED_MAP=
  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-.';
var EXTENDED_MAP_LENGTH = EXTENDED_MAP.length;
function extendedEncode(arrVals, maxVal) {
  var chartData = 'e:';

  for(i = 0, len = arrVals.length; i < len; i++) {
    // In case the array vals were translated to strings.
    var numericVal = new Number(arrVals[i]);
    // Scale the value to maxVal.
    var scaledVal = Math.floor(EXTENDED_MAP_LENGTH *
        EXTENDED_MAP_LENGTH * numericVal / maxVal);

    if(scaledVal > (EXTENDED_MAP_LENGTH * EXTENDED_MAP_LENGTH) - 1) {
      chartData += "..";
    } else if (scaledVal < 0) {
      chartData += '__';
    } else {
      // Calculate first and second digits and add them to the output.
      var quotient = Math.floor(scaledVal / EXTENDED_MAP_LENGTH);
      var remainder = scaledVal - EXTENDED_MAP_LENGTH * quotient;
      chartData += EXTENDED_MAP.charAt(quotient) + EXTENDED_MAP.charAt(remainder);
    }
  }

  return chartData;
}

Aby zakodować dane, wywołaj funkcję simpleEncode lub extendedEncode, przekazując tablicę zawierającą Twoje dane (valueArray) i maksymalną wartość danych (maxValue). Aby utworzyć odstęp między najwyższą wartością a górną krawędzią wykresu, ustaw maxValue na wartość większą od największej liczby w tablicy danych w następujący sposób:

var valueArray = new Array(0,1,4,4,6,11,14,17,23,28,33,36,43,59,65);
var maxValue = 70;
simpleEncode(valueArray, maxValue);

Powrót do góry