Formaty danych

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

Spis treści

Opis

Dane do prawie 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 od 0 do 100 włącznie. Ten format jest łatwy do odczytania i pisania ręcznie.
• Format tekstowy z automatycznym skalowaniem skaluje wykres, aby dopasować go do Twoich danych.
• Format tekstowy ze skalowaniem niestandardowym jest podobny do podstawowego formatu tekstowego, ale umożliwia określenie zakresu niestandardowego za pomocą drugiego parametru adresu URL.
• Prosty format kodowania pozwala określić wartości całkowite od 0 do 61 włącznie, zakodowane jednym znakiem alfanumerycznym. To kodowanie powoduje uzyskanie najkrótszego ciągu danych w dowolnym z formatów (jeśli jakakolwiek wartość jest większa niż 9).
• Rozszerzony format kodowania pozwala określić wartości całkowite z zakresu od 0 do 4095 włącznie i zakodowane przy użyciu 2 znaków alfanumerycznych. Rozszerzone kodowanie sprawdza się najlepiej w przypadku wykresów z dużą ilością danych i szerokim zakresem danych.

Wartości danych są skalowane tak, aby pasowały do użytego formatu. Przeczytaj sekcję Skalowanie danych i skalowanie osi, aby dowiedzieć się, jak manipulować danymi w celu dopasowania do wykresu.

Udostępniamy fragment kodu JavaScript do kodowania danych w prostym lub rozszerzonych formatach kodowania. Kilku członków grupy Wykresów Google przekazało też inne biblioteki, aby ułatwić formatowanie: przeszukuj archiwa, aby je znaleźć.

Podstawowy format tekstowy

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

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 w Twoich danych. Możesz też użyć formatowania tekstu ze skalowaniem niestandardowym, aby zapewnić skalowanie.

Składnia:

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

<data>

Każda seria składa się z co najmniej jednej wartości rozdzielonej przecinkami. Rozdziel wiele serii za pomocą pionowej kreski (|). Wartości to liczby zmiennoprzecinkowe z zakresu od 0 do 100 włącznie. Wartości mniejsze niż 0 lub znak podkreślenia ( _ ) są uznawane za wartości puste. Wartości powyżej 100 są skracane do 100.

 

Przykład:

Tabela z 5 wartościami. Podkreślenie jest uznawane za wartość zerową, wartość -30 jest mniejsza niż wartość minimalna, więc jest usuwana, a wartość 200 jest skracana do 100.

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

Powrót do góry

Format tekstowy z automatycznym skalowaniem

Możesz skonfigurować automatyczne skalowanie niektórych wykresów, aby dopasować je do danych. Wykres zostanie przeskalowany tak, aby najwyższa wartość znajdowała się u góry, a najmniejsza (lub zero, jeśli wszystkie wartości są większe niż 0) – na dole.

Wszystkie wartości znaczników widoczne na wykresie będą zawierały ich rzeczywiste wartości, a nie wartości skalowane.

Ta funkcja działa tylko w przypadku wartości w formacie tekstowym i nie działa w przypadku niektórych typów 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 na wykresach 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

Format tekstowy ze skalowaniem niestandardowym

Format tekstowy ze skalowaniem niestandardowym pozwala określić dowolne dodatnie i ujemne liczby zmiennoprzecinkowe w połączeniu z parametrem skalowania, który umożliwia określenie niestandardowego zakresu wykresu. Ten wykres jest przydatny, gdy nie chcesz ograniczać danych do określonego zakresu lub nie chcesz skalować danych ręcznie, aby pasowały do wykresu. Ten format w razie potrzeby dostosuje linię zerową za Ciebie. Format danych jest taki sam jak w przypadku podstawowego formatu tekstowego.

W przypadku skalowania automatycznego wybierz chds=a.

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

Składnia:

Formatowanie tekstu ze skalowaniem niestandardowym 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>

Taki sam jak w zwykłym formacie danych: co najmniej 1 wartość rozdzielana przecinkami na serię, wiele serii rozdzielonych pionową kreską (|). Zakres dozwolonych wartości w każdej serii jest określany przez parametr chds.

chds

Zbiór co najmniej 1 minimalnej i maksymalnej dozwolonej wartości 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, ostatnia para zostanie zastosowana do wszystkich pozostałych ciągów danych. Pamiętaj, że nie zmienia to zakresu osi. Aby zmienić zakres osi, ustaw parametr chxr. Prawidłowy zakres wartości mieści się w zakresie od (+/-)9,999e(+/-)199. Wartości możesz podawać w notacji standardowej lub E.

<series_1_min>

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

<series_1_max>

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

 

Przykład:

Wykres słupkowy ze skalą min./maksymalną od -80 do 140. Wartości 30, -60, 50, 140 i 80 należą do skali, więc nie są obcinane. Pamiętaj, że linia zerowa jest dostosowana do Ciebie – 80/(140 + 80) = 0,36 od góry osi Y. Pamiętaj też, że domyślny zakres osi Y nadal wynosi od 0 do 100 pomimo parametru chds, 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 jednym znakiem alfanumerycznym. To daje najkrótszy adres URL ciągu danych we wszystkich formatach 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 szczegółowość danych jest znacznie większa niż wielkość wyświetlania, a wartości będą raczej niewielkie (niewielkie, ale widoczne na większych wykresach).

Pamiętaj, że jeśli użyjesz parametru chds w prostym kodowaniu, nie wpłynie to na rozmiar elementu danych na wykresie, ale wszystkie wartości znaczników punktów danych.

Składnia:

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

<series_1>

Ciąg, w którym każdy znak jest pojedynczym punktem danych, a serie są rozdzielone przecinkami. Poszczególne wartości w serii nie są rozdzielone. 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., gdzie z = 51
• 0(zero)—9, gdzie 0 = 52, a 9 = 61
• Podkreślenie (_) oznacza brakującą wartość

Za pomocą tego narzędzia możesz zakodować pojedynczą wartość. Możesz też skalować i zakodować cały ciąg za pomocą kodu JavaScript.

Przykład:

Odpowiednik ciągu zakodowanego tekstowego 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 serią i sześcioma wartościami serie, każda z sześcioma wartościami." src="/static/wykres." src="/static/wykres. chd=s:BTb19_,Mn5tzb

Powrót do góry

Rozszerzony format kodowania

Rozszerzony format kodowania pozwala określić wartości całkowite z zakresu od 0 do 4095 włącznie i zakodowane przy użyciu 2 znaków alfanumerycznych. Ma ona nieco inną składnię niż proste kodowanie.

Pamiętaj, że jeśli użyjesz parametru chds w prostym kodowaniu, nie wpłynie to na rozmiar elementu danych na wykresie, ale wszystkie wartości znaczników punktów danych.

Składnia:

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

<seria_1>

Ciąg, w którym każdy 2 znaki jest 1 punktem danych, a serie są rozdzielone przecinkami. Poszczególne wartości w serii nie są rozdzielone. 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 i tak dalej, 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 itd. dla B9 = 125
• B- = 126, B. = 127
• 9A = 3904, 9B = 3905 itd. dla 9Z = 3929
• 9a = 3930, 9b = 3931 itd. dla 9z = 3955
• 90 = 3956, 91 = 3957 itd. dla 99 = 3965
• 9- = 3966, 9. = 3967
• -A = 3968, -B = 3969 itd. dla -Z = 3993
• -a = 3994, -b = 3995 itd. dla -z = 4019
• -0 = 4020, -1 = 4021 itd. do -9 = 4029
• -- = 4030, -. = 4031
• .A = 4032, .B = 4033 itd. do .Z = 4057
• .a = 4058, .b = 4059 itd. dla .z = 4083
• .0 = 4084, .1 = 4085 itd. dla .9 = 4093
• .- = 4094, .. = 4095

Za pomocą tego narzędzia możesz zakodować pojedynczą wartość. Możesz też skalować i zakodować cały ciąg za pomocą kodu JavaScript.

Przykład:

Odpowiednik ciągu zakodowanego tekstowego 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 tak, by pasowały do wykresu – bezpośrednio (w przypadku formatu tekstowego ze skalowaniem niestandardowym) lub pośrednio (w przypadku wszystkich innych typów). Oznacza to, że każdy wykres jest skalowany tak, aby pasować do dostępnego zakresu formatu, a nie do rzeczywistego zakresu przesłanych przez Ciebie danych.

Możesz skalować dane tak, aby obejmowały pełny zakres wartości dozwolonych przez Twój format, aby różnice były bardziej oczywiste. Możesz skalować dane, skalując je w celu dopasowania do używanego formatu lub bezpośrednio określając zakres danych (tzn. stosując format tekstowy 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 danymi, ale użyj domyślnego zakresu 0–100. Możesz jednak zmienić ten zakres.

W tej sekcji opisujemy oba te problemy.

Dane są przeskalowane, by dopasować je do zakresu formatu [Wszystkie wykresy oprócz wykresu kołowego i Venna]

Różne formaty obsługują różne zakresy wartości. Dane są skalowane do zakresu formatu, tak aby maksymalna wartość obsługiwana w danym formacie była renderowana u góry tej osi, a minimalna wartość formatu – na dole. W poniższych przykładach ta sama wartość (100) jest wyświetlana przy użyciu podstawowego formatu tekstu (zakres 0–100), tekstu ze skalowaniem niestandardowym (zakres niestandardowy 0–200) i rozszerzonym formatem kodowania (zakres 0–4095).

Podstawowy format tekstowy	Format tekstowy ze skalowaniem niestandardowym	Rozszerzony format kodowania
Wartość: 100 (chd=t:100) Zakres formatów: 0–100 Wartość 100 jest renderowana jako wartość 100/100 w górę.	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 formatów: 0–4095 Wartość 100 jest renderowana jako 100/4095 w górę na skali.

Łatwym sposobem na skalowanie danych, aby dopasować je do wykresu, jest użycie formatu tekstowego ze skalowaniem. Łatwiejszym sposobem jest ręczne skalowanie danych w celu dopasowania ich do zakresu obsługiwanego przez Twój format.

Wykresy kołowe i Venna: w przypadku wykresów kołowych i Venna wszystkie wartości są przedstawiane 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]

Wartości osi możesz wyświetlać, korzystając z parametru chxt. Pamiętaj jednak, że etykiety osi nie są obliczane w taki sposób, aby odzwierciedlać dane na wykresie. Są obliczane niezależnie przez interfejs API lub bezpośrednio określone przez Ciebie.

Domyślny zakres osi to 0–100, niezależnie od wartości danych i skalowania danych. Jeśli na przykład wyświetlasz oś Y z użyciem domyślnych etykiet osi na wykresie z rozszerzonym kodowaniem (zakres 0–4095), etykiety osi Y nadal będą odczytywać wartości 0–100, chyba że wyraźnie to zmienisz, zgodnie z opisem poniżej. Ten przykład przedstawia domyślne etykiety osi Y na rozszerzonym wykresie słupkowym kodowania z wartością danych 100:

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

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

Proste kodowanie, bez skalowania osi	Proste kodowanie, skalowana oś	Podstawowy tekst, bez skalowania osi
chd=s:Paz9   Prosty zakres wartości kodowania: 0–61 Domyślny zakres osi (0–100) Zakres kodowania jest mniejszy niż zakres osi etykiety, dlatego słupki nie odpowiadają rzeczywistej wartości na etykiecie osi. Słupki są jednak odpowiednie proporcjonalne do siebie.	chd=s:Paz9     chxr=0,0,61,10 Prosty zakres wartości kodowania: 0–61 Zakres osi ustawiony bezpośrednio na 0–61 Zakres kodowania i zakres osi są równe, więc słupki odpowiadają prawidłowej wartości na osi.	chd=t:15,26,51,61   Zakres wartości podstawowego 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 formatów tekstu jest większy niż w przypadku prostego zakresu formatów kodowania (100 jednostek a 61 jednostek), dlatego słupki są tutaj mniejsze niż na innych wykresach, ale wszystkie wykresy są do siebie proporcjonalne.

Powrót do góry

Skrypt kodowania JavaScript

W rzeczywistych zastosowaniach prawdopodobnie łatwiej jest kodować dane automatycznie niż ręcznie.

Poniższy fragment kodu JavaScript koduje pojedynczą serię w kodowanie proste lub extended i skaluje wartości danych w celu dopasowania do pełnego zakresu tego kodowania. Dane należy podać w postaci tablicy liczb dodatnich. Każda wartość, która nie jest liczbą dodatnią, jest kodowana jako brakująca wartość z użyciem 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) oraz maksymalną wartość danych (maxValue). Aby utworzyć odstęp między najwyższą wartością a górną częścią wykresu, ustaw wartość maxValue na większą od największej liczby w tablicy danych w ten 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