Elementy sterujące i panele

Na tej stronie dowiesz się, jak łączyć ze sobą wiele wykresów w panelach oraz dawać użytkownikom kontrolę nad danymi, które wyświetlają.

Omówienie

Panele informacyjne to prosty sposób na uporządkowanie wielu wykresów, które korzystają z tych samych bazowych danych, oraz zarządzanie nimi. Korzystając z interfejsów API opisanych na tej stronie, możesz uwolnić się od prac związanych z okablowaniem i koordynowaniem wszystkich wykresów, które są częścią panelu.

Panele są definiowane za pomocą klas google.visualization.Dashboard. Instancje Dashboard otrzymują obiekt DataTable zawierający dane, które umożliwiają wizualizację oraz rysowanie i rozpowszechnianie danych na wszystkich wykresach wchodzących w skład panelu.

Elementy sterujące to widżety interfejsu (np. selektory kategorii, suwaki zakresów, autouzupełnianie itp.), z którymi korzystasz, aby zarządzać danymi zarządzanymi przez panel i zawarte w nim wykresy.

Elementy sterujące definiuje się za pomocą klas google.visualization.ControlWrapper. Do panelu możesz dodać instancje ControlWrapper, które zachowują się jak rury i zawory w systemie hydraulicznym. Zbierają dane wejściowe użytkowników i na podstawie tych informacji decydują, które dane zarządzane przez panel należy udostępnić wykresom, które są ich częścią.

Zapoznaj się z poniższym przykładem, w którym selektor kategorii i suwak zakresu służą do przedstawiania danych zwizualizowanych na wykresie kołowym.

Uwaga: panel jest interaktywny. Wypróbuj elementy sterujące, aby obserwować zmiany wykresu w czasie rzeczywistym.

Korzystanie z ustawień i paneli

Oto kluczowe kroki, które musisz wykonać, aby utworzyć panel i umieścić go na swojej stronie. Poniżej znajdziesz fragment kodu ilustrujący wszystkie poniższe czynności oraz szczegółowe informacje na temat każdego z nich.

  1. Utwórz szkielet HTML panelu. Strona musi zawierać tyle elementów HTML, ile jest potrzebnych do obsługi wszystkich członków panelu. Dotyczy to również samego panelu oraz wszystkich jego elementów sterujących i wykresów. Zwykle dla każdego z nich jest używany tag <div>.
  2. Wczytaj biblioteki Aby umieścić lub wczytać panel na stronie, wystarczy umieścić lub wczytać tylko 2 biblioteki: interfejs Google AJAX API i pakiet controls Wizualizacji Google.
  3. Przygotuj dane. Musisz przygotować dane do wizualizacji. Oznacza to samodzielne określenie danych w kodzie lub wysłanie zapytania do zdalnej witryny.
  4. Utwórz instancję panelu. Utwórz instancję panelu, wywołując jego konstruktor i przekazując odwołanie do elementu <div>, który będzie go przechowywać.
  5. Utwórz dowolną liczbę instancji elementów sterujących i wykresów. Utwórz instancje google.visualization.ChartWrapper i google.visualization.ControlWrapper, aby opisać każdy wykres i określić ustawienia, którymi zarządza panel.
  6. Określ zależności. Wywołaj w panelu bind() i przekaż instancje kontrolne i wykresów, aby poinformować panel, czym ma zarządzać. Po powiązaniu elementu sterującego z wykresem panel aktualizuje wykres, aby dopasować go do ograniczeń nałożonych przez ustawienie na dane.
  7. Narysuj panel Wywołaj w panelu draw() i przekaż dane, aby narysować cały panel na stronie.
  8. Zmiany automatyczne po rysowaniu. Opcjonalnie po pierwszym rysowaniu możesz automatycznie sterować elementami sterującymi, które są częścią panelu, i w związku z tym aktualizować wykresy.

Oto prosty przykład strony, która tworzy prosty panel z suwakiem zakresu, który generuje wykres kołowy. Wynikowy panel jest widoczny pod fragmentem kodu. 

<html>
  <head>
    <!--Load the AJAX API-->
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type="text/javascript">

      // Load the Visualization API and the controls package.
      google.charts.load('current', {'packages':['corechart', 'controls']});

      // Set a callback to run when the Google Visualization API is loaded.
      google.charts.setOnLoadCallback(drawDashboard);

      // Callback that creates and populates a data table,
      // instantiates a dashboard, a range slider and a pie chart,
      // passes in the data and draws it.
      function drawDashboard() {

        // Create our data table.
        var data = google.visualization.arrayToDataTable([
          ['Name', 'Donuts eaten'],
          ['Michael' , 5],
          ['Elisa', 7],
          ['Robert', 3],
          ['John', 2],
          ['Jessica', 6],
          ['Aaron', 1],
          ['Margareth', 8]
        ]);

        // Create a dashboard.
        var dashboard = new google.visualization.Dashboard(
            document.getElementById('dashboard_div'));

        // Create a range slider, passing some options
        var donutRangeSlider = new google.visualization.ControlWrapper({
          'controlType': 'NumberRangeFilter',
          'containerId': 'filter_div',
          'options': {
            'filterColumnLabel': 'Donuts eaten'
          }
        });

        // Create a pie chart, passing some options
        var pieChart = new google.visualization.ChartWrapper({
          'chartType': 'PieChart',
          'containerId': 'chart_div',
          'options': {
            'width': 300,
            'height': 300,
            'pieSliceText': 'value',
            'legend': 'right'
          }
        });

        // Establish dependencies, declaring that 'filter' drives 'pieChart',
        // so that the pie chart will only display entries that are let through
        // given the chosen slider range.
        dashboard.bind(donutRangeSlider, pieChart);

        // Draw the dashboard.
        dashboard.draw(data);
      }
    </script>
  </head>

  <body>
    <!--Div that will hold the dashboard-->
    <div id="dashboard_div">
      <!--Divs that will hold each control and chart-->
      <div id="filter_div"></div>
      <div id="chart_div"></div>
    </div>
  </body>
</html>

Oto panel utworzony przez ten kod.

1. Utwórz szkielet HTML dla pulpitu nawigacyjnego

Strona musi zawierać tyle elementów HTML (zwykle <div>), które mieszczą zarówno panel, jak i wszystkie elementy sterujące i wykresy. Podczas tworzenia instancji panelu, sterowania i wykresu musisz przekazać odwołanie do ich elementu, więc każdemu elementowi HTML należy przypisać identyfikator. 

    <!--Div that will hold the dashboard-->
    <div id="dashboard_div">
      <!--Divs that will hold each control and chart-->
      <div id="filter_div"></div>
      <div id="chart_div"></div>
    </div>

Każdy element HTML możesz umieścić w wybranym przez siebie miejscu.

2. Wczytaj swoje biblioteki

Aby umieścić lub wczytać panel na stronie, wystarczy umieścić lub wczytać tylko 2 biblioteki: interfejs Google AJAX API i pakiet controls Wizualizacji Google. Interfejs API (w szczególności google.visualization.ChartWrapper) automatycznie identyfikuje inne wymagane pakiety (np. gauge, jeśli używasz wykresu wskaźnikowego) i wczytuje je na bieżąco bez Twojej interwencji.

Do pobrania biblioteki elementów sterujących musisz użyć dodatku google.charts.load().

<!--Load the AJAX API-->
<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript">

  // Load the Visualization API and the controls package.
  // Packages for all the other charts you need will be loaded
  // automatically by the system.
  google.charts.load('current', {'packages':['corechart', 'controls']});

  // Set a callback to run when the Google Visualization API is loaded.
  google.charts.setOnLoadCallback(drawDashboard);

  function drawDashboard() {
    // Everything is loaded. Assemble your dashboard...
  }
</script>

3. Przygotowanie danych

Po załadowaniu interfejsu API wizualizacji google.charts.setOnLoadCallback() wywoła funkcję obsługi, dzięki czemu będziesz mieć pewność, że wszystkie wymagane metody pomocnicze i klasy będą gotowe do rozpoczęcia przygotowywania danych.

Panele akceptują dane w tabeli DataTable, tak samo jak wykresy.

4. Tworzenie instancji panelu

Po utworzeniu danych możesz utworzyć wystąpienie obiektu panelu. Konstruktor panelu przyjmuje jeden parametr: odwołanie do elementu DOM, w którym ma się wyświetlać panel. 

  var dashboard = new google.visualization.Dashboard(document.getElementById('dashboard_div'));

Panele są udostępniane jako klasa JavaScriptu. Po utworzeniu instancji panelu możesz wykonać kilka opcjonalnych czynności, takich jak dodanie detektorów zdarzeń (aby na przykład otrzymywać powiadomienia, gdy panel będzie „gotowy”). Panele obsługują zdarzenia w taki sam sposób jak wykresy, więc więcej informacji znajdziesz w sekcjach Obsługa zdarzeń wizualizacji lub Dobre wyświetlanie błędów.

5. Tworzenie instancji elementów sterujących i wykresów

Określ tyle instancji, ile potrzebujesz dla każdego elementu sterującego i wykresu, które będą częścią panelu. Do definiowania wykresów i elementów sterujących służą odpowiednio google.visualization.ChartWrapper i google.visualization.ControlWrapper. 

  // Create a range slider, passing some options
  var donutRangeSlider = new google.visualization.ControlWrapper({
    'controlType': 'NumberRangeFilter',
    'containerId': 'filter_div',
    'options': {
      'filterColumnLabel': 'Donuts eaten'
    }
  });

  // Create a pie chart, passing some options
  var pieChart = new google.visualization.ChartWrapper({
    'chartType': 'PieChart',
    'containerId': 'chart_div',
    'options': {
      'width': 300,
      'height': 300,
      'pieSliceText': 'label'
    }
  });

Podczas tworzenia instancji ChartWrapper i ControlWrapper nie określaj ani parametru dataTable, ani dataSourceUrl. Panel dostarcza do każdego z nich odpowiednie dane. Pamiętaj jednak o określeniu wymaganych parametrów: chartType i containerId w przypadku wykresów oraz controlType i containerId w przypadku elementów sterujących.

Kilka wskazówek dotyczących konfigurowania elementów sterujących i wykresów:

  • Musisz nadać wszystkim elementom sterującym wartość filterColumnIndex (lub filterColumnLabel), aby określić, na której kolumnie w elemencie google.visualization.DataTable działa element sterujący (w powyższym przykładzie element sterujący działa na kolumnie Zjedzone),

  • Użyj opcji konfiguracji state w elementach sterujących, aby zainicjować je za pomocą jawnego stanu przy pierwszym wyświetleniu. Możesz na przykład użyć tego ustawienia, by poprawić początkowe położenie kciuków na suwaku zakresu. 

      var donutRangeSlider = new google.visualization.ControlWrapper({
    'controlType': 'NumberRangeFilter',
    'containerId': 'filter_div',
    'options': {
      'filterColumnLabel': 'Donuts eaten',
      'minValue': 1,
      'maxValue': 10
    },
    // Explicitly positions the thumbs at position 3 and 8,
    // out of the possible range of 1 to 10.
    'state': {'lowValue': 3, 'highValue': 8}
  });

  • Wszystkie wykresy, które są częścią panelu, korzystają z tej samej bazowej tabeli danych, która została przez Ciebie przygotowana w kroku Przygotowanie danych. Jednak wykresy często wymagają określonego rozmieszczenia kolumn, aby prawidłowo wyświetlać się na przykład w przypadku wykresu kołowego. Na przykład wykres kołowy wymaga kolumny z ciągami znaków, po której następuje kolumna z liczbą wartości.

    Podczas konfigurowania poszczególnych instancji ChartWrapper użyj opcji view, aby zadeklarować, które kolumny są odpowiednie dla wykresu, jak w przykładzie poniżej. 

      var data = google.visualization.arrayToDataTable([
    ['Name', 'Gender', 'Age', 'Donuts eaten'],
    ['Michael' , 'Male', 12, 5],
    ['Elisa', 'Female', 20, 7],
    ['Robert', 'Male', 7, 3],
    ['John', 'Male', 54, 2],
    ['Jessica', 'Female', 22, 6],
    ['Aaron', 'Male', 3, 1],
    ['Margareth', 'Female', 42, 8]
  ]);

  var pieChart = new google.visualization.ChartWrapper({
    'chartType': 'PieChart',
    'containerId': 'chart_div',
    'options': {
      'width': 300,
      'height': 300,
      'title': 'Donuts eaten per person'
    },
    // The pie chart will use the columns 'Name' and 'Donuts eaten'
    // out of all the available ones.
    'view': {'columns': [0, 3]}
  });

  // The rest of dashboard configuration follows
  // ...

6. Określ zależności

Po utworzeniu instancji panelu oraz wszystkich elementów sterujących i wykresów, które będą go częścią, użyj metody bind(), aby poinformować panel o zależnościach między elementami sterującymi a wykresami.

Po powiązaniu elementu sterującego z wykresem panel aktualizuje wykres, aby dopasować go do ograniczeń nałożonych przez tę opcję na dane. W przykładowym panelu, który tworzysz, suwak zakresu i wykres kołowy są ze sobą powiązane, więc za każdym razem, gdy używasz pierwszego panelu, wyświetla się on tylko dane pasujące do wybranego zakresu. 

  // 'pieChart' will update whenever you interact with 'donutRangeSlider'
  // to match the selected range.
  dashboard.bind(donutRangeSlider, pieChart);

Elementy sterujące i wykresy możesz powiązać w wielu różnych konfiguracjach: jeden do jednego, jeden do wielu, wiele do jednego i wiele do wielu. Gdy z wykresem jest powiązanych wiele elementów sterujących, panel aktualizuje wykres, tak aby był zgodny z połączonymi ograniczeniami egzekwowanymi przez wszystkie powiązane elementy sterujące. Element sterujący może jednocześnie prowadzić wiele wykresów. Aby określić wiele powiązań jednocześnie, przekaż do metody bind() tablice, a nie pojedyncze instancje. Możesz też połączyć kilka wywołań funkcji bind() razem. Oto kilka przykładów. 

  // Many-to-one binding where 'ageSelector' and 'salarySelector' concurrently
  // participate in selecting which data 'ageVsSalaryScatterPlot' visualizes.
  dashboard.bind([agePicker, salaryPicker], ageVsSalaryScatterPlot);

  // One-to-many binding where 'ageSelector' drives two charts.
  dashboard.bind(agePicker, [ageVsSalaryScatterPlot, ageBarChart]);

  // bind() chaining where each control drives its own chart.
  dashboard.bind(agePicker, ageBarChart).bind(salaryRangePicker, salaryPieChart);

W przypadku zastosowań zaawansowanych możesz też powiązać ustawienia z innymi ustawieniami, aby utworzyć łańcuchy zależności . 

  dashboard.bind(countryPicker, regionPicker).bind(regionPicker, cityPicker);

7. Narysuj swój pulpit

Wywołaj metodę draw() w instancji panelu, aby wyrenderować cały panel. Metoda draw() przyjmuje tylko 1 parametr: DataTable (lub DataView), który zasila panel.

Wywołuj funkcję draw() za każdym razem, gdy zmienisz strukturę panelu (np. dodasz do niego nowe elementy sterujące lub wykresy) lub zmienisz ogólną DataTable, która go obsługuje.

Instancja panelu uruchamia zdarzenie ready za każdym razem, gdy draw() zakończy rysowanie wszystkich jej elementów sterujących i wykresów. Jeśli nie uda się wygenerować żadnego z zarządzanych elementów sterujących lub wykresu, wywoływane jest zdarzenie error. Więcej informacji o obsłudze zdarzeń znajdziesz w artykule o obsłudze zdarzeń.

Uwaga: zanim spróbujesz zmienić kompozycję panelu lub ponownie go narysować, poczekaj na zdarzenie ready.

8. Zmiany automatyczne po losowaniu

Gdy ukończysz początkowy draw(), panel stanie się opublikowany i będzie automatycznie reagować na wszystkie wykonywane na nim działania (np. zmianę wybranego zakresu suwaka sterującego w panelu).

Jeśli chcesz automatycznie zmienić stan panelu, możesz to zrobić bezpośrednio w instancjach ControlWrapper i ChartWrapper, które są jego częścią. Ogólną zasadą jest wprowadzanie każdej potrzebnej zmiany bezpośrednio w określonej instancji ControlWrapper (lub ChartWrapper). Możesz na przykład zmienić opcję sterowania lub stan odpowiednio za pomocą setOption() i setState(), a następnie wywołać jej metodę draw(). Panel zostanie zaktualizowany odpowiednio do żądanych zmian.

Oto przykład.
Cała strona internetowa
<html>
  <head>
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type="text/javascript">
      google.charts.load('current', {'packages':['corechart', 'controls']});
      google.charts.setOnLoadCallback(drawStuff);

      function drawStuff() {

        var dashboard = new google.visualization.Dashboard(
          document.getElementById('programmatic_dashboard_div'));

        // We omit "var" so that programmaticSlider is visible to changeRange.
        var programmaticSlider = new google.visualization.ControlWrapper({
          'controlType': 'NumberRangeFilter',
          'containerId': 'programmatic_control_div',
          'options': {
            'filterColumnLabel': 'Donuts eaten',
            'ui': {'labelStacking': 'vertical'}
          }
        });

        var programmaticChart  = new google.visualization.ChartWrapper({
          'chartType': 'PieChart',
          'containerId': 'programmatic_chart_div',
          'options': {
            'width': 300,
            'height': 300,
            'legend': 'none',
            'chartArea': {'left': 15, 'top': 15, 'right': 0, 'bottom': 0},
            'pieSliceText': 'value'
          }
        });

        var data = google.visualization.arrayToDataTable([
          ['Name', 'Donuts eaten'],
          ['Michael' , 5],
          ['Elisa', 7],
          ['Robert', 3],
          ['John', 2],
          ['Jessica', 6],
          ['Aaron', 1],
          ['Margareth', 8]
        ]);

        dashboard.bind(programmaticSlider, programmaticChart);
        dashboard.draw(data);

        changeRange = function() {
          programmaticSlider.setState({'lowValue': 2, 'highValue': 5});
          programmaticSlider.draw();
        };

        changeOptions = function() {
          programmaticChart.setOption('is3D', true);
          programmaticChart.draw();
        };
      }

    </script>
  </head>
  <body>
    <div id="programmatic_dashboard_div" style="border: 1px solid #ccc">
      <table class="columns">
        <tr>
          <td>
            <div id="programmatic_control_div" style="padding-left: 2em; min-width: 250px"></div>
            <div>
              <button style="margin: 1em 1em 1em 2em" onclick="changeRange();">
                Select range [2, 5]
              </button><br />
              <button style="margin: 1em 1em 1em 2em" onclick="changeOptions();">
                Make the pie chart 3D
              </button>
            </div>
          </td>
          <td>
            <div id="programmatic_chart_div"></div>
          </td>
        </tr>
      </table>
    </div>
  </body>
</html>

Dokumentacja API

W tej sekcji wymienione są obiekty udostępniane przez interfejsy Controls and Dashboards API, a także standardowe metody udostępniane przez wszystkie elementy sterujące.

Panel

Reprezentuje zbiór współpracujących ze sobą elementów sterujących i wykresów, które korzystają z tych samych danych bazowych.

Zespół

Dashboard(containerRef)
containerRef
Odwołanie do prawidłowego elementu kontenera na stronie, w którym będzie przechowywana zawartość panelu.

Metody

Panel udostępnia te metody:

Metoda Typ zwracanej wartości Opis
bind(controls, charts) google.visualization.Dashboard

Łączy co najmniej jeden element sterujący z co najmniej jednym innym użytkownikiem panelu (wykresem lub innym elementem sterującym), dzięki czemu wszystkie te elementy będą ponownie rysowane za każdym razem, gdy pierwszy z nich będzie rejestrował interakcję użytkownika lub użytkowników mających wpływ na dane zarządzane przez panel. Zwraca samą instancję panelu w celu połączenia wielu wywołań funkcji bind().

  • controls – jedna lub tablica instancji google.visualization.ControlWrapper definiujących ustawienia, które chcesz powiązać.
  • wykresy – pojedynczy pojedynczy wiersz lub tablica google.visualization.ChartWrapper instancji definiujących wykresy, które będą wywoływane przez elementy sterujące.
draw(dataTable) Brak

Rysuje panel.
getSelection() Tablica obiektów

Zwraca tablicę wybranych encji wizualnych wykresów w panelu. Wywoływana w panelu metoda getSelection() zwraca agregację wszystkich wybranych przez Ciebie wykresów na wszystkich wykresach. Umożliwia to korzystanie z jednego odwołania podczas pracy z wyborami na wykresie.

Uwaga: do każdego wykresu, który chcesz nasłuchiwać, musisz dołączyć detektory zdarzeń wybranego zdarzenia.

Rozszerzony opis

Wydarzenia

Obiekt Dashboard zgłasza poniższe zdarzenia. Pamiętaj, że musisz wywołać funkcję Dashboard.draw() przed zgłoszeniem zdarzeń.

Nazwa Opis Właściwości
error Uruchamiane, gdy podczas próby wyrenderowania panelu wystąpi błąd. Co najmniej 1 z elementów sterujących i wykresów, które są częścią panelu, mogły nie zostać wyrenderowane. identyfikator, wiadomość
ready

Pulpit nawigacyjny zakończył rysowanie i jest gotowy do zaakceptowania zmian. Wszystkie elementy sterujące i wykresy, które są częścią panelu, są gotowe do wywołania metody zewnętrznej i interakcji użytkownika. Jeśli po narysowaniu zdarzenia chcesz zmienić panel (lub wyświetlane w nim dane), skonfiguruj detektor tego zdarzenia, zanim wywołasz metodę draw, a potem zastosuj zmiany dopiero po wywołaniu zdarzenia.

Zdarzenie ready wywoła też:

  • po zakończeniu odświeżenia panelu wywołanego przez użytkownika lub automatyczną interakcję z jednym z elementów sterujących,
  • po automatycznym wywołaniu metody draw() w dowolnej części wykresu panelu.
Brak

ControlWrapper

Obiekt ControlWrapper to otoka otaczająca reprezentację JSON skonfigurowanej instancji sterującej. Klasa udostępnia wygodne metody definiowania elementu sterującego panelu, rysowania go i programowej zmiany jego stanu.

Zespół

ControlWrapper(opt_spec)
opt_spec
[Opcjonalnie] – obiekt JSON definiujący kontrolkę lub zserializowana wersja ciągu znaków tego obiektu. Obsługiwane właściwości obiektu JSON przedstawiono w tabeli poniżej. Jeśli nie podasz tych właściwości, musisz ustawić wszystkie odpowiednie właściwości za pomocą metod set... dostępnych dla elementu ControlWrapper.
Właściwość Typ Wymagane Domyślne Opis
controlType Ciąg znaków Wymagane brak Nazwa klasy elementu sterującego. W ustawieniach Google można pominąć nazwę pakietu google.visualization. Przykłady: CategoryFilter, NumberRangeFilter.
containerId Ciąg znaków Wymagane brak Identyfikator elementu DOM na stronie, który będzie hostować element sterujący.
Opcje Obiekt Opcjonalnie brak Obiekt opisujący opcje elementu sterującego. Możesz użyć notacji literału JavaScript lub podać uchwyt obiektu. Przykład: "options": {"filterColumnLabel": "Age", "minValue": 10, "maxValue": 80}
state Obiekt Opcjonalnie brak Obiekt opisujący stan elementu sterującego. Stan zbiera wszystkie zmienne, na które może mieć wpływ użytkownik korzystający z elementu sterującego. Na przykład stan suwaka zakresu można opisać pozycjami, na których znajduje się dolny i górny kciuk suwaka. Możesz użyć zapisu literału JavaScript lub podać uchwyt obiektu.Przykład: "state": {"lowValue": 20, "highValue": 50}

Metody

Element ControlWrapper udostępnia następujące dodatkowe metody:

Metoda Typ zwracanej wartości Opis
draw() Brak

Rysuje element sterujący. Normalnie rysowanie odbywa się przez pulpit nawigacyjny trzymający element sterujący. Wywołaj polecenie draw(), aby wymusić automatyczne ponowne pobieranie elementu sterującego po zmianie innych ustawień, takich jak opcje czy stan.

toJSON() Ciąg znaków Zwraca wersję w postaci ciągu znaków reprezentacji elementu sterującego w formacie JSON.
clone() ControlWrapper Zwraca głęboką kopię kodu sterującego.
getControlType() Ciąg znaków Nazwa klasy elementu sterującego. Jeśli jest to element sterujący Google, nazwa nie będzie kwalifikowana z elementem google.visualization. Jeśli na przykład jest to kontrolka CategoryFilter, zwróciłaby wartość „CategoryFilter”, a nie „google.visualization.CategoryFilter”.
getControlName() Ciąg znaków Zwraca nazwę elementu sterującego przypisaną przez funkcję setControlName().
getControl() Dokumentacja obiektów sterujących Zwraca odwołanie do elementu sterującego utworzonego przez ten kod elementu ControlWrapper. To będzie zwracało wartość null do czasu wywołania draw() w obiekcie ControlWrapper (lub w panelu, w którym jest on przechowywany) i zgłoszenie gotowego zdarzenia. Zwrócony obiekt udostępnia tylko jedną metodę: resetControl(), która resetuje stan sterowania do wartości użytej do zainicjowania (np. zresetowanie elementu formularza HTML).
getContainerId() Ciąg znaków Identyfikator elementu kontenera DOM elementu sterującego.
getOption(key, opt_default_val) Dowolny typ

Zwraca określoną wartość opcji sterowania

  • klucz – nazwa opcji do pobrania. Może to być prawidłowa nazwa, np. 'vAxis.title'.
  • opt_default_value [opcjonalny] – jeśli określona wartość jest niezdefiniowana lub ma wartość null, zostanie ona zwrócona.
getOptions() Obiekt Zwraca obiekt opcji dla tego elementu sterującego.
getState() Obiekt Zwraca stan kontrolny.
setControlType(type) Brak Ustawia typ elementu sterującego. Przekaż nazwę klasy elementu sterującego, aby utworzyć instancję. Jeśli jest to element sterujący Google, nie kwalifikuj go za pomocą funkcji google.visualization. Na przykład w przypadku suwaka zakresu nad kolumną liczbową przekaż „NumberRangeFilter”.
setControlName(name) Brak Ustawia dowolną nazwę elementu sterującego. Nie jest widoczny nigdzie na elemencie sterującym, a jedynie do Twojej dyspozycji.
setContainerId(id) Brak Ustawia identyfikator elementu DOM zawierającego element DOM dla elementu sterującego.
setOption(key, value) Brak Ustawia jedną wartość opcji sterującej, gdzie klucz to nazwa opcji, a wartość to wartość. Aby cofnąć ustawienie opcji, dla wartości podaj wartość null. Pamiętaj, że klucz może być kwalifikowaną nazwą, taką jak 'vAxis.title'.
setOptions(options_obj) Brak Ustawia pełny obiekt opcji dla elementu sterującego.
setState(state_obj) Brak Ustawia stan elementu sterującego. Stan zbiera wszystkie zmienne, na które może mieć wpływ użytkownik korzystający z elementu sterującego. Na przykład stan suwaka zakresu można opisać pozycje, które zajmuje dolny i górny kciuk suwaka.

Wydarzenia

Obiekt ControlWrapper generuje poniższe zdarzenia. Pamiętaj, że przed wywołaniem zdarzeń musisz wywołać funkcję ControlWrapper.draw() (lub narysować panel, przy użyciu którego element sterujący jest wyświetlany).

Nazwa Opis Właściwości
error Uruchamiane, gdy podczas próby wyrenderowania elementu sterującego wystąpi błąd. identyfikator, wiadomość
ready Element sterujący jest gotowy do przyjmowania interakcji użytkownika i wywołań metod zewnętrznych. Jeśli chcesz korzystać z elementu sterującego i metod wywoływania po jego utworzeniu, skonfiguruj detektor tego zdarzenia przed wywołaniem metody draw i wywołuj je dopiero po wywołaniu zdarzenia. Możesz też nasłuchiwać zdarzenia ready w panelu z opcjami kontroli i wywołaniami dopiero po wywołaniu zdarzenia. Brak
statechange Uruchamiane, gdy użytkownik wejdzie w interakcję z elementem sterującym, co wpływa na jego stan. Na przykład zdarzenie statechange będzie uruchamiane, gdy przesuniesz kciukami suwaka zakresu. Aby pobrać zaktualizowany stan kontrolny po wywołaniu zdarzenia, wywołaj ControlWrapper.getState(). Brak

ChartWrapper

Zapoznaj się z dokumentacją google.visualization.ChartWrapper w sekcji dokumentacji API dotyczącej wizualizacji.

Jeśli w panelu używasz elementu ChartWrapper, pamiętaj o tych uwagach:

  • Nie ustawiaj bezpośrednio atrybutów dataTable, query, dataSourceUrl i refreshInterval. Panel, w którym znajduje się wykres, dostarcza mu potrzebne dane.
  • Ustaw atrybut view, aby zadeklarować, które kolumny spośród wszystkich dostępnych w tabeli dataTable podanej w panelu są odpowiednie dla wykresu, jak pokazano w sekcji Tworzenie instancji elementów sterujących i wykresu.

Filtry to elementy graficzne, za pomocą których użytkownicy mogą interaktywnie wybierać dane wyświetlane na wykresie. W tej sekcji opisujemy filtry wykresu Google: CategoryFilter, ChartRangeFilter, DateRangeFilter, NumberRangeFilter i StringFilter.

Możesz używać dowolnego z nich jako parametru funkcji ControlWrapper.setControlType().

Uwaga: w opisach opcji do opisywania atrybutów zagnieżdżonych służy zapis kropkowy. Na przykład opcja o nazwie 'ui.label' powinna być zadeklarowana w obiekcie options jako var options = {"ui": {"label": "someLabelValue"} };

CategoryFilter

Selektor do wybierania co najmniej jednej ze zdefiniowanych wartości.

Stan

Nazwa Typ Domyślne Opis
selectedValues Tablica obiektów lub typów podstawowych brak Obecnie wybrany zbiór wartości. Wybrane wartości muszą być zbiorem ogólnych wartości, które można wybrać, zdefiniowanych przez opcję values (wszystkie zbędne wartości zostaną zignorowane). Jeśli CategoryFilter nie zezwala na wybór jednokrotnego wyboru, zapisywana jest tylko pierwsza wartość tablicy.

Opcje

Nazwa Typ Domyślne Opis
filterColumnIndex Liczba brak Kolumna tabeli danych, na której ma działać filtr. Musisz podać tę opcję lub pole filterColumnLabel. Jeśli występują obie opcje, pierwszeństwo ma ta opcja.
filterColumnLabel string, brak Etykieta kolumny, na której ma działać filtr. Musisz podać tę opcję lub pole filterColumnIndex. Jeśli występują oba, pierwszeństwo ma filterColumnIndex.
wartości Tablica automatycznie Lista wartości do wyboru. Jeśli używana jest tablica obiektów, powinny one mieć odpowiednią reprezentację toString() do wyświetlenia użytkownikowi. Jeśli ma wartość null lub nie jest określona, lista wartości zostanie automatycznie obliczona na podstawie wartości znajdujących się w kolumnie DataTable, na których działa ten element sterujący.
useFormattedValue boolean false Podczas automatycznego wypełniania listy wartości do wyboru w kolumnie DataTable, na których działa ten filtr, stosowane są wartości rzeczywiste lub sformatowane.
ui Obiekt brak Obiekt z elementami do konfigurowania różnych aspektów interfejsu użytkownika kontroli. Aby określić właściwości tego obiektu, możesz użyć notacji literału obiektu w następujący sposób: 
{label: 'Metric', labelSeparator: ':'}
ui.caption string, „Wybierz wartość...” Podpis wyświetlany w widżecie selektora wartości, gdy nie zostanie wybrany żaden element.
ui.sortValues boolean prawda Określa, czy wartości do wyboru mają być sortowane.
ui.selectedValuesLayout string, „z boku” Jak wyświetlać wybrane wartości, gdy dozwolony jest wybór wielokrotny. Możliwe wartości:
  • 'aside': wybrane wartości będą wyświetlane w pojedynczym wierszu tekstowym obok widżetu selektora wartości,
  • 'below': wybrane wartości będą wyświetlane w pojedynczym wierszu tekstowym pod widżetem,
  • 'belowWrapping': podobny do below, ale wpisy, które nie mieszczą się w selektorze, zostaną zawijane do nowego wiersza,
  • 'belowStacked': wybrane wartości będą wyświetlane w kolumnie pod widżetem.
ui.allowNone boolean prawda Określa, czy użytkownik może nie wybrać żadnej wartości. W przypadku ustawienia false użytkownik musi wybrać co najmniej 1 z dostępnych wartości. Jeśli podczas inicjowania elementu sterującego, jeśli opcja jest ustawiona na false i nie jest określony stan selectedValues, pierwsza wartość z dostępnych dostępnych wartości jest automatycznie wybierana.
ui.allowMultiple boolean prawda Określa, czy można wybrać wiele wartości, a nie tylko jedną.
ui.allowTyping boolean prawda Określa, czy użytkownik może wpisać tekst w polu tekstowym, aby zawęzić listę możliwych opcji (za pomocą autouzupełniania).
ui.label string, automatycznie Etykieta, która ma być wyświetlana obok selektora kategorii. Jeśli nie określono inaczej, zostanie użyta etykieta kolumny, na której działa element sterujący.
ui.labelSeparator string, brak Ciąg znaków separatora dołączonego do etykiety, który pozwala wizualnie oddzielić etykietę od selektora kategorii.
ui.labelStacking string, „poziomo” Określa, czy etykieta ma być wyświetlana nad selektorem kategorii (układanie w pionie) czy obok (układanie w poziomie). Użyj 'vertical' lub 'horizontal'.
ui.cssClass string, 'google-visualization-controls-categoryfilter' Klasa CSS, która ma zostać przypisana do elementu sterującego na potrzeby niestandardowego stylu.

ChartRangeFilter

Suwak z dwoma kciukami nałożonymi na wykres do wyboru zakresu wartości na ciągłej osi wykresu.

Stan

Nazwa Typ Domyślne Opis
range.start liczba, data, data i godzina lub godzina Wartość początkowa zakresu Początek wybranego zakresu (włącznie).
range.end liczba, data, data i godzina lub godzina Wartość końcowa zakresu Koniec wybranego zakresu (włącznie).

Opcje

Nazwa Typ Domyślne Opis
filterColumnIndex Liczba brak Indeks kolumny w tabeli danych, na której działa filtr. Musisz podać tę opcję lub filterColumnLabel. Jeśli występują obie opcje, ta opcja ma pierwszeństwo.

Pamiętaj, że ma sens tylko określenie indeksu kolumny domain znajdującej się w ciągłej osi wykresu narysowanego w elemencie sterującym.

filterColumnLabel string, brak Etykieta kolumny tabeli danych, na której działa filtr. Musisz podać tę opcję lub pole filterColumnIndex. Jeśli występują oba, pierwszeństwo ma filterColumnIndex.

Pamiętaj, że warto określić etykietę tylko kolumny domena zawartej w ciągłej osi wykresu narysowanego w elemencie sterującym.

ui Obiekt brak Obiekt z elementami do konfigurowania różnych aspektów interfejsu użytkownika kontroli. Aby określić właściwości tego obiektu, możesz użyć notacji literału obiektu w następujący sposób: 
{chartType: 'ScatterChart', chartOptions: {pointSize: 10}}
ui.chartType string, Wykres mieszany Typ wykresu narysowanego w elemencie sterującym.
Możliwe wartości: „Wykres warstwowy”, „Wykres liniowy”, „Wykres mieszany” lub „Wykres punktowy”.
ui.chartOptions Obiekt 
{
 'enableInteractivity': false,
 'chartArea': {'height': '100%'},
 'legend': {'position': 'none'},
 'hAxis': {'textPosition': 'in'},
 'vAxis': {
  'textPosition': 'none',
  'gridlines': {'color': 'none'}
 }
}
Opcje konfiguracji wykresu utworzonego w elemencie sterującym. Umożliwia korzystanie z tego samego poziomu konfiguracji co każdy wykres w panelu i jest zgodny z formatem akceptowanym w ChartWrapper.setOptions().

Możesz określić dodatkowe opcje lub zastąpić te domyślne (pamiętaj jednak, że ustawienia domyślne zostały starannie wybrane, by zapewnić optymalny wygląd strony).

ui.chartView Obiekt lub ciąg znaków (obiekt zserializowany) brak Specyfikacja widoku, który ma zostać zastosowany do tabeli danych używanej do rysowania wykresu w elemencie sterującym. Umożliwia korzystanie z tego samego poziomu konfiguracji co każdy wykres w panelu i jest zgodny z formatem akceptowanym przez funkcję ChartWrapper.setView(). Jeśli nie określono tego ustawienia, wykres jest tworzony za pomocą tabeli danych.

Pamiętaj, że oś pozioma utworzonego wykresu musi być ciągła, więc pamiętaj, by odpowiednio określić ui.chartView.

ui.minRangeSize Liczba Różnica w wartości danych interpretowana jako 1 piksel Minimalny rozmiar zakresu do wyboru (range.end - range.start) określony w jednostkach wartości danych. W przypadku osi liczbowej jest to liczba (niekoniecznie liczba całkowita). W przypadku osi daty, daty i godziny lub godziny jest to liczba całkowita, która określa różnicę w milisekundach.
ui.snapToData boolean false Jeśli ma wartość Prawda, kciuki zakresu są przypinane do najbliższych punktów danych. W tym przypadku punkty końcowe zakresu zwróconego przez funkcję getState() są koniecznie wartościami w tabeli danych.

Wydarzenia

Rozszerzenia do zdarzeń ControlWrapper:

Nazwa Opis Właściwości
statechange Tak jak w przypadku każdego elementu ControlWrapper, ma tylko dodatkową właściwość logiczną inProgress, która określa, czy stan zmienia się w tej chwili (jeden z kciuków lub sam zakres jest przeciągany). inProgress

DateRangeFilter

Dwuwartościowy suwak do wybierania zakresów dat.

Przesuń suwak, by wybrać wiersze widoczne w tabeli poniżej.

Stan

Nazwa Typ Domyślne Opis
lowValue Liczba brak Dolny zakres wybranego zakresu (włącznie).
highValue Liczba brak Większy zakres wybranego zakresu (włącznie).
lowThumbAtMinimum boolean brak Określa, czy dolny kciuk suwaka jest zablokowany w minimalnym dozwolonym zakresie. Jeśli jest ustawione, zastępuje ustawienie lowValue.
highThumbAtMaximum boolean brak Określa, czy górny kciuk suwaka jest zablokowany w maksymalnym dozwolonym zakresie. Jeśli jest ustawione, zastępuje ustawienie highValue.

Opcje

Nazwa Typ Domyślne Opis
filterColumnIndex Liczba brak Kolumna tabeli danych, na której ma działać filtr. Musisz podać tę opcję lub pole filterColumnLabel. Jeśli występują obie opcje, pierwszeństwo ma ta opcja. Musi wskazywać kolumnę typu number.
filterColumnLabel string, brak Etykieta kolumny, na której ma działać filtr. Musisz podać tę opcję lub pole filterColumnIndex. Jeśli występują oba, pierwszeństwo ma filterColumnIndex. Musi wskazywać kolumnę typu number.
minValue Data automatycznie Minimalna dozwolona wartość dla dolnego zakresu. Jeśli wartość nie zostanie określona, zostanie pobrana z zawartości tabeli DataTable zarządzanej przez ustawienie.
maxValue Data automatycznie Maksymalna dozwolona wartość dla wyższego zakresu. Jeśli wartość nie zostanie określona, zostanie pobrana z zawartości tabeli DataTable zarządzanej przez ustawienie.
ui Obiekt brak Obiekt z elementami do konfigurowania różnych aspektów interfejsu użytkownika kontroli. Aby określić właściwości tego obiektu, możesz użyć notacji literału obiektu w następujący sposób: 
{label: 'Age', labelSeparator: ':'}
ui.format Obiekt brak Jak zapisać datę w postaci ciągu znaków. Akceptuje każdy prawidłowy format daty .
ui.step string, dzień Minimalna możliwa zmiana przy przeciąganiu kciuków suwaka: może to być dowolna jednostka czasu nieprzekraczająca „dnia”. (wartości „miesiąc” i „rok” nie są jeszcze obsługiwane).
ui.ticks Liczba automatycznie Liczba taktów (stała pozycja na pasku zakresu), jaką mogą zajmować kciuki suwaka.
ui.unitIncrement string, 1 Kwota, która ma być zwiększana o przyrosty jednostki zakresu zakresu. Zwiększanie jednostki odpowiada przesuwaniu kciuka suwaka za pomocą klawiszy strzałek.
ui.blockIncrement Liczba 10 Kwota, która ma być zwiększana o przyrosty bloków zakresu zakresu. Zwiększenie blokowej pozycji jest równoważne użycie klawiszy pgUp i pgDown do przesuwania kciuków suwaka.
ui.showRangeValues boolean prawda Określa, czy obok suwaka mają być wyświetlane etykiety wybranego zakresu.
ui.orientation string, „poziomo” Orientacja suwaka. Może to być 'horizontal' lub 'vertical'.
ui.label string, automatycznie Etykieta wyświetlana obok suwaka. Jeśli nie określono inaczej, zostanie użyta etykieta kolumny, na której działa element sterujący.
ui.labelSeparator string, brak Ciąg znaków separatora dołączonego do etykiety, który pozwala wizualnie oddzielić etykietę od suwaka.
ui.labelStacking string, „poziomo” Pozwala określić, czy etykieta ma być wyświetlana powyżej (ułożenie w pionie) czy obok (układanie w poziomie) za pomocą suwaka. Użyj 'vertical' lub 'horizontal'.
ui.cssClass string, 'google-visualization-controls-rangefilter' Klasa CSS, która ma zostać przypisana do elementu sterującego na potrzeby niestandardowego stylu.

NumberRangeFilter

Dwuwartościowy suwak do wybierania zakresów wartości liczbowych.

Stan

Nazwa Typ Domyślne Opis
lowValue Liczba brak Dolny zakres wybranego zakresu (włącznie).
highValue Liczba brak Większy zakres wybranego zakresu (włącznie).
lowThumbAtMinimum boolean brak Określa, czy dolny kciuk suwaka jest zablokowany w minimalnym dozwolonym zakresie. Jeśli jest ustawione, zastępuje ustawienie lowValue.
highThumbAtMaximum boolean brak Określa, czy górny kciuk suwaka jest zablokowany w maksymalnym dozwolonym zakresie. Jeśli jest ustawione, zastępuje ustawienie highValue.

Opcje

Nazwa Typ Domyślne Opis
filterColumnIndex Liczba brak Kolumna tabeli danych, na której ma działać filtr. Musisz podać tę opcję lub pole filterColumnLabel. Jeśli występują obie opcje, pierwszeństwo ma ta opcja. Musi wskazywać kolumnę typu number.
filterColumnLabel string, brak Etykieta kolumny, na której ma działać filtr. Musisz podać tę opcję lub pole filterColumnIndex. Jeśli występują oba, pierwszeństwo ma filterColumnIndex. Musi wskazywać kolumnę typu number.
minValue Liczba automatycznie Minimalna dozwolona wartość dla dolnego zakresu. Jeśli wartość nie zostanie określona, zostanie pobrana z zawartości tabeli DataTable zarządzanej przez ustawienie.
maxValue Liczba automatycznie Maksymalna dozwolona wartość dla wyższego zakresu. Jeśli wartość nie zostanie określona, zostanie pobrana z zawartości tabeli DataTable zarządzanej przez ustawienie.
ui Obiekt brak Obiekt z elementami do konfigurowania różnych aspektów interfejsu użytkownika kontroli. Aby określić właściwości tego obiektu, możesz użyć notacji literału obiektu w następujący sposób: 
{label: 'Age', labelSeparator: ':'}
ui.format Obiekt brak Jak zapisać liczbę jako ciąg znaków. Akceptuje każdy prawidłowy format liczb .
ui.step Liczba 1 lub obliczona na podstawie ticks, jeśli został określony Minimalna możliwa zmiana przy przeciąganiu kciuków suwaka.
ui.ticks Liczba automatycznie Liczba taktów (stała pozycja na pasku zakresu), jaką mogą zajmować kciuki suwaka.
ui.unitIncrement Liczba 1 Kwota, która ma być zwiększana o przyrosty jednostki zakresu zakresu. Zwiększanie jednostki odpowiada przesuwaniu kciuka suwaka za pomocą klawiszy strzałek.
ui.blockIncrement Liczba 10 Kwota, która ma być zwiększana o przyrosty bloków zakresu zakresu. Zwiększenie blokowej pozycji jest równoważne użycie klawiszy pgUp i pgDown do przesuwania kciuków suwaka.
ui.showRangeValues boolean prawda Określa, czy obok suwaka mają być wyświetlane etykiety wybranego zakresu.
ui.orientation string, „poziomo” Orientacja suwaka. Może to być 'horizontal' lub 'vertical'.
ui.label string, automatycznie Etykieta wyświetlana obok suwaka. Jeśli nie określono inaczej, zostanie użyta etykieta kolumny, na której działa element sterujący.
ui.labelSeparator string, brak Ciąg znaków separatora dołączonego do etykiety, który pozwala wizualnie oddzielić etykietę od suwaka.
ui.labelStacking string, „poziomo” Pozwala określić, czy etykieta ma być wyświetlana powyżej (ułożenie w pionie) czy obok (układanie w poziomie) za pomocą suwaka. Użyj 'vertical' lub 'horizontal'.
ui.cssClass string, 'google-visualization-controls-rangefilter' Klasa CSS, która ma zostać przypisana do elementu sterującego na potrzeby niestandardowego stylu.

StringFilter

Proste pole do wprowadzania tekstu, które umożliwia filtrowanie danych za pomocą dopasowywania ciągów znaków. Aktualizuje się po każdym naciśnięciu klawisza: wpisz j, aby zawęzić tabelę do Jana i Jessicy.

Stan

Nazwa Typ Domyślne Opis
value ciąg lub obiekt brak Tekst wpisany obecnie w polu do wprowadzania danych.

Opcje

Nazwa Typ Domyślne Opis
filterColumnIndex Liczba brak Kolumna tabeli danych, na której ma działać filtr. Musisz podać tę opcję lub pole filterColumnLabel. Jeśli występują obie opcje, pierwszeństwo ma ta opcja.
filterColumnLabel string, brak Etykieta kolumny, na której ma działać filtr. Musisz podać tę opcję lub pole filterColumnIndex. Jeśli występują oba, pierwszeństwo ma filterColumnIndex.
matchType string, „prefiks” Określa, czy element sterujący powinien pasować tylko do dokładnych wartości ('exact'), prefiksów zaczynających się od początku wartości ('prefix') czy dowolnego podłańcucha ('any').
caseSensitive boolean false Określa, czy w dopasowywaniu ma być rozróżniana wielkość liter.
useFormattedValue boolean false Określa, czy element sterujący powinien pasować do wartości w formacie komórek czy ponownie do wartości rzeczywistych.
ui Obiekt brak Obiekt z elementami do konfigurowania różnych aspektów interfejsu użytkownika kontroli. Aby określić właściwości tego obiektu, możesz użyć notacji literału obiektu w następujący sposób: 
{label: 'Name', labelSeparator: ':'}
ui.realtimeTrigger boolean prawda Określa, czy element sterujący powinien być dopasowany po każdym naciśnięciu klawisza czy tylko wtedy, gdy pole wprowadzania „zmienia się” (utratę ostrości lub naciśnięcie klawisza Enter).
ui.label string, automatycznie Etykieta wyświetlana obok pola do wprowadzania danych. Jeśli nie określono inaczej, zostanie użyta etykieta kolumny, na której działa element sterujący.
ui.labelSeparator string, brak Ciąg znaków separatora dołączany do etykiety, który pozwala wizualnie oddzielić etykietę od pola do wprowadzania danych.
ui.labelStacking string, „poziomo” Określa, czy etykieta ma być wyświetlana nad polem do wprowadzania danych (układanie w pionie) czy obok (układanie w poziomie). Użyj 'vertical' lub 'horizontal'.
ui.cssClass string, 'google-visualization-controls-stringfilter' Klasa CSS, która ma zostać przypisana do elementu sterującego na potrzeby niestandardowego stylu.