Wykresy

Interfejs API Arkuszy Google umożliwia tworzenie i aktualizowanie w razie potrzeby wykresów w arkuszach kalkulacyjnych. Przykłady na tej stronie pokazują, jak za pomocą interfejsu Sheets API wykonać niektóre typowe operacje na wykresach.

Mają one postać żądań HTTP, które mają być neutralne pod względem języka. Aby dowiedzieć się, jak wdrożyć aktualizację zbiorczą w różnych językach przy użyciu bibliotek klienta interfejsu API Google, przeczytaj artykuł Aktualizowanie arkuszy kalkulacyjnych.

W tych przykładach obiekty zastępcze SPREADSHEET_ID i SHEET_ID wskazują, gdzie należy je umieścić. Identyfikator arkusza kalkulacyjnego znajdziesz w adresie URL arkusza kalkulacyjnego. Identyfikator arkusza możesz uzyskać, korzystając z metody spreadsheets.get. Zakresy są określane w notacji A1. Przykładowy zakres to Arkusz1!A1:D5.

Dodatkowo symbol zastępczy CHART_ID wskazuje identyfikator danego wykresu. Możesz ustawić ten identyfikator podczas tworzenia wykresu za pomocą interfejsu Sheets API lub zezwolić na wygenerowanie go za pomocą interfejsu API Arkuszy. Identyfikatory istniejących wykresów możesz uzyskać za pomocą metody spreadsheets.get.

Obiekt zastępczy SOURCE_SHEET_ID wskazuje też arkusz z danymi źródłowymi. W tych przykładach jest to tabela wymieniona w sekcji Dane źródłowe wykresu.

Dane źródłowe wykresu

Załóżmy, że w pierwszym arkuszu używany arkusz kalkulacyjny („Arkusz1”) zawiera te dane źródłowe. Ciągi w pierwszym wierszu to etykiety poszczególnych kolumn. Przykłady odczytów z innych arkuszy w arkuszu kalkulacyjnym znajdziesz w sekcji notacja A1.

O B C D E
1 Numer modelu Dział sprzedaży – styczeń Dział sprzedaży – luty Dział sprzedaży – mar Łączna sprzedaż
2 D-01X 68 74 60 202
3 FR-0B1 97 76 88 261
4 P-034 27 49 32 108
5 P-105 46 44 67 157
6 W-11 75 68 87 230
7 W-24 74 52 62 188

Dodaj wykres kolumnowy

Poniższy przykładowy kod spreadsheets.batchUpdate pokazuje, jak za pomocą AddChartRequest utworzyć wykres kolumnowy na podstawie danych źródłowych i umieścić go w nowym arkuszu. Aby skonfigurować wykres, żądanie wykonuje te działania:

  • Ustawia typ wykresu jako wykres kolumnowy.
  • Dodaje legendę na dole wykresu.
  • Określa tytuły wykresu i osi.
  • Konfiguruje 3 serie danych reprezentujące sprzedaż w 3 różnych miesiącach z użyciem domyślnego formatowania i kolorów.

Protokół żądania jest pokazany poniżej.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "addChart": {
        "chart": {
          "spec": {
            "title": "Model Q1 Sales",
            "basicChart": {
              "chartType": "COLUMN",
              "legendPosition": "BOTTOM_LEGEND",
              "axis": [
                {
                  "position": "BOTTOM_AXIS",
                  "title": "Model Numbers"
                },
                {
                  "position": "LEFT_AXIS",
                  "title": "Sales"
                }
              ],
              "domains": [
                {
                  "domain": {
                    "sourceRange": {
                      "sources": [
                        {
                          "sheetId": SOURCE_SHEET_ID,
                          "startRowIndex": 0,
                          "endRowIndex": 7,
                          "startColumnIndex": 0,
                          "endColumnIndex": 1
                        }
                      ]
                    }
                  }
                }
              ],
              "series": [
                {
                  "series": {
                    "sourceRange": {
                      "sources": [
                        {
                          "sheetId": SOURCE_SHEET_ID,
                          "startRowIndex": 0,
                          "endRowIndex": 7,
                          "startColumnIndex": 1,
                          "endColumnIndex": 2
                        }
                      ]
                    }
                  },
                  "targetAxis": "LEFT_AXIS"
                },
                {
                  "series": {
                    "sourceRange": {
                      "sources": [
                        {
                          "sheetId": SOURCE_SHEET_ID,
                          "startRowIndex": 0,
                          "endRowIndex": 7,
                          "startColumnIndex": 2,
                          "endColumnIndex": 3
                        }
                      ]
                    }
                  },
                  "targetAxis": "LEFT_AXIS"
                },
                {
                  "series": {
                    "sourceRange": {
                      "sources": [
                        {
                          "sheetId": SOURCE_SHEET_ID,
                          "startRowIndex": 0,
                          "endRowIndex": 7,
                          "startColumnIndex": 3,
                          "endColumnIndex": 4
                        }
                      ]
                    }
                  },
                  "targetAxis": "LEFT_AXIS"
                }
              ],
              "headerCount": 1
            }
          },
          "position": {
            "newSheet": true
          }
        }
      }
    }
  ]
}

Żądanie utworzy w nowym arkuszu wykres podobny do tego:

Dodaj wynik przepisu na wykresie kolumnowym

Dodawanie wykresu kołowego

Poniższy przykładowy kod spreadsheets.batchUpdate pokazuje, jak użyć komponentu AddChartRequest do utworzenia wykresu kołowego 3D na podstawie danych źródłowych. Żądanie powoduje skonfigurowanie wykresu:

  • Określa tytuł wykresu.
  • Dodaje legendę z prawej strony wykresu.
  • Ustawia wykres jako kołowy 3D. Pamiętaj, że na wykresach kołowych 3D nie może się znajdować „otwór w pierścieniu” (tak jak w przypadku płaskich wykresów kołowych).
  • Ustawia serię danych wykresu jako łączną sprzedaż dla każdego numeru modelu.
  • Zakotwicza wykres w komórce C3 arkusza wskazanej przez atrybut SHEET_ID, z przesunięciem o 50 pikseli w kierunkach X i Y.

Protokół żądania jest pokazany poniżej.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "addChart": {
        "chart": {
          "spec": {
            "title": "Model Q1 Total Sales",
            "pieChart": {
              "legendPosition": "RIGHT_LEGEND",
              "threeDimensional": true,
              "domain": {
                "sourceRange": {
                  "sources": [
                    {
                      "sheetId": SOURCE_SHEET_ID,
                      "startRowIndex": 0,
                      "endRowIndex": 7,
                      "startColumnIndex": 0,
                      "endColumnIndex": 1
                    }
                  ]
                }
              },
              "series": {
                "sourceRange": {
                  "sources": [
                    {
                      "sheetId": SOURCE_SHEET_ID,
                      "startRowIndex": 0,
                      "endRowIndex": 7,
                      "startColumnIndex": 4,
                      "endColumnIndex": 5
                    }
                  ]
                }
              },
            }
          },
          "position": {
            "overlayPosition": {
              "anchorCell": {
                "sheetId": SHEET_ID,
                "rowIndex": 2,
                "columnIndex": 2
              },
              "offsetXPixels": 50,
              "offsetYPixels": 50
            }
          }
        }
      }
    }
  ]
}

Żądanie tworzy taki wykres:

Dodaj wynik przepisu na wykresie kołowym

Możesz też w żądaniu zaktualizować wartość legendPosition z RIGHT_LEGEND na LABELED_LEGEND, aby połączyć wartości z legendy z wycinkami na wykresie kołowym.

'legendPosition': 'LABELED_LEGEND',

Zaktualizowane żądanie tworzy wykres podobny do tego:

Dodaj wynik przepisu na wykresie kołowym

Dodawanie wykresu liniowego z wieloma zakresami, które nie sąsiadują ze sobą

Poniższy przykładowy kod spreadsheets.batchUpdate pokazuje, jak za pomocą AddChartRequest utworzyć wykres liniowy na podstawie danych źródłowych i umieścić go w arkuszu źródłowym. Wybranie zakresów, które nie sąsiadują ze sobą, może posłużyć do wykluczenia wierszy z ChartSourceRange.

Żądanie powoduje skonfigurowanie wykresu:

  • Ustawia typ wykresu jako wykres liniowy.
  • Określa tytuł poziomej osi X.
  • Konfiguruje serię danych reprezentującą sprzedaż. Ustawia wartość A1:A3 i A6:A7 jako domain, a B1:B3 i B6:B7 jako series, korzystając z domyślnego formatowania i kolorów. Zakresy są określane za pomocą notacji A1 w adresie URL żądania.
  • Zakotwicza wykres w komórce H8 w arkuszu określonym przez funkcję SHEET_ID.

Protokół żądania jest pokazany poniżej.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "addChart": {
        "chart": {
          "spec": {
            "basicChart": {
              "chartType": "LINE",
              "domains": [
                {
                  "domain": {
                    "sourceRange": {
                      "sources": [
                        {
                          "startRowIndex": 0,
                          "endRowIndex": 3,
                          "startColumnIndex": 0,
                          "endColumnIndex": 1,
                          "sheetId": SOURCE_SHEET_ID
                        },
                        {
                          "startRowIndex": 5,
                          "endRowIndex": 7,
                          "startColumnIndex": 0,
                          "endColumnIndex": 1,
                          "sheetId": SOURCE_SHEET_ID
                        }
                      ]
                    }
                  }
                }
              ],
              "series": [
                {
                  "series": {
                    "sourceRange": {
                      "sources": [
                        {
                          "startRowIndex": 0,
                          "endRowIndex": 3,
                          "startColumnIndex": 1,
                          "endColumnIndex": 2,
                          "sheetId": SOURCE_SHEET_ID
                        },
                        {
                          "startRowIndex": 5,
                          "endRowIndex": 7,
                          "startColumnIndex": 1,
                          "endColumnIndex": 2,
                          "sheetId": SOURCE_SHEET_ID
                        }
                      ]
                    }
                  }
                }
              ]
            }
          },
          "position": {
            "overlayPosition": {
              "anchorCell": {
                "sheetId": SOURCE_SHEET_ID,
                "rowIndex": 8,
                "columnIndex": 8
              }
            }
          }
        }
      }
    }
  ]
}

Żądanie utworzy w nowym arkuszu wykres podobny do tego:

Dodaj przepis na wykres liniowy zakresu, który nie sąsiaduje ze sobą

Usuwanie wykresu

Poniższy przykładowy kod spreadsheets.batchUpdate pokazuje, jak użyć DeleteEmbeddedObjectRequest do usunięcia wykresu wskazanego przez CHART_ID.

Protokół żądania jest pokazany poniżej.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "deleteEmbeddedObject": {
        "objectId": CHART_ID
      }
    }
  ]
}

Edytowanie właściwości wykresu

Ten przykładowy kod spreadsheets.batchUpdate pokazuje, jak za pomocą UpdateChartSpecRequest edytować wykres utworzony w przepisie Dodaj wykres kolumnowy, zmieniając jego dane, typ i wygląd. Podzbiorów właściwości wykresu nie można zmieniać pojedynczo. Aby wprowadzić zmiany, w całym polu spec musisz podać właściwość UpdateChartSpecRequest. Ogólnie rzecz biorąc, edytowanie specyfikacji wykresu wymaga zastąpienia jej nowym.

To żądanie aktualizuje oryginalny wykres (określony przez CHART_ID):

  • Ustawia typ wykresu na BAR.
  • Przenosi legendę na prawą stronę wykresu.
  • Odwraca osie, tak aby „Sprzedaż” znajdowała się na dolnej osi, a „Numery modeli” na lewej osi.
  • Ustawia format tytułu osi na 24-punktową czcionkę, pogrubienie i kursywę.
  • Usuwa z wykresu dane „W-24” (wiersz 7 w danych źródłowych wykresu).

Protokół żądania jest pokazany poniżej.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "updateChartSpec": {
        "chartId": CHART_ID,
        "spec": {
          "title": "Model Q1 Sales",
          "basicChart": {
            "chartType": "BAR",
            "legendPosition": "RIGHT_LEGEND",
            "axis": [
              {
                "format": {
                  "bold": true,
                  "italic": true,
                  "fontSize": 24
                },
                "position": "BOTTOM_AXIS",
                "title": "Sales"
              },
              {
                "format": {
                  "bold": true,
                  "italic": true,
                  "fontSize": 24
                },
                "position": "LEFT_AXIS",
                "title": "Model Numbers"
              }
            ],
            "domains": [
              {
                "domain": {
                  "sourceRange": {
                    "sources": [
                      {
                        "sheetId": SOURCE_SHEET_ID,
                        "startRowIndex": 0,
                        "endRowIndex": 6,
                        "startColumnIndex": 0,
                        "endColumnIndex": 1
                      }
                    ]
                  }
                }
              }
            ],
            "series": [
              {
                "series": {
                  "sourceRange": {
                    "sources": [
                      {
                        "sheetId": SOURCE_SHEET_ID,
                        "startRowIndex": 0,
                        "endRowIndex": 6,
                        "startColumnIndex": 1,
                        "endColumnIndex": 2
                      }
                    ]
                  }
                },
                "targetAxis": "BOTTOM_AXIS"
              },
              {
                "series": {
                  "sourceRange": {
                    "sources": [
                      {
                        "sheetId": SOURCE_SHEET_ID,
                        "startRowIndex": 0,
                        "endRowIndex": 6,
                        "startColumnIndex": 2,
                        "endColumnIndex": 3
                      }
                    ]
                  }
                },
                "targetAxis": "BOTTOM_AXIS"
              },
              {
                "series": {
                  "sourceRange": {
                    "sources": [
                      {
                        "sheetId": SOURCE_SHEET_ID,
                        "startRowIndex": 0,
                        "endRowIndex": 6,
                        "startColumnIndex": 3,
                        "endColumnIndex": 4
                      }
                    ]
                  }
                },
                "targetAxis": "BOTTOM_AXIS"
              }
            ],
            "headerCount": 1
          }
        }
      }
    }
  ]
}

Po przesłaniu prośby wykres będzie wyglądał tak:

Edytuj wynik przepisu na wykresie

Przenoszenie wykresu i zmienianie jego rozmiaru

Poniższy przykładowy kod spreadsheets.batchUpdate pokazuje, jak za pomocą UpdateEmbeddedObjectPositionRequest przenosić i zmieniać rozmiar wykresu. Po przesłaniu żądania wykres określony przez CHART_ID to:

  • Zakotwiczone do komórki A5 oryginalnego arkusza.
  • Przesunięcie w kierunku X o 100 pikseli.
  • Zmieniono rozmiar na 1200 x 742 piksele (domyślny rozmiar wykresu to 600 x 371 pikseli).

W żądaniu zmieni się tylko właściwości określone za pomocą parametru fields. Inne właściwości (np. offsetYPixels) zachowują pierwotne wartości.

Protokół żądania jest pokazany poniżej.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "updateEmbeddedObjectPosition": {
        "objectId": CHART_ID,
        "newPosition": {
          "overlayPosition": {
            "anchorCell": {
              "rowIndex": 4,
              "columnIndex": 0
            },
            "offsetXPixels": 100,
            "widthPixels": 1200,
            "heightPixels": 742
          }
        },
        "fields": "anchorCell(rowIndex,columnIndex),offsetXPixels,widthPixels,heightPixels"
      }
    }
  ]
}

Odczytywanie danych z wykresu

Poniższy przykładowy kod spreadsheets.get pokazuje, jak pobrać dane wykresu z arkusza kalkulacyjnego. Parametr zapytania fields określa, że powinny być zwracane tylko dane wykresu.

Odpowiedź na to wywołanie metody to obiekt spreadsheet, który zawiera tablicę obiektów sheet. Wszystkie wykresy widoczne w arkuszu są reprezentowane przez obiekt sheet. Jeśli pole odpowiedzi ma wartość domyślną, jest ono pomijane w odpowiedzi.

W tym przykładzie pierwszy arkusz (SOURCE_SHEET_ID) nie zawiera żadnych wykresów, dlatego zwracana jest pusta para nawiasów klamrowych. Na drugim arkuszu znajduje się tylko wykres utworzony za pomocą opcji Dodaj wykres kolumnowy.

Protokół żądania jest pokazany poniżej.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?fields=sheets(charts)
{
  "sheets": [
    {},
    {
      "charts": [
        {
          "chartId": CHART_ID,
          "position": {
            "sheetId": SHEET_ID
          },
          "spec": {
            "basicChart": {
              "axis": [
                {
                  "format": {
                    "bold": false,
                    "italic": false
                  },
                  "position": "BOTTOM_AXIS",
                  "title": "Model Numbers"
                },
                {
                  "format": {
                    "bold": false,
                    "italic": false
                  },
                  "position": "LEFT_AXIS",
                  "title": "Sales"
                }
              ],
              "chartType": "COLUMN",
              "domains": [
                {
                  "domain": {
                    "sourceRange": {
                      "sources": [
                        {
                          "endColumnIndex": 1
                          "endRowIndex": 7,
                          "sheetId": SOURCE_SHEET_ID,
                          "startColumnIndex": 0,
                          "startRowIndex": 0,
                        }
                      ]
                    }
                  }
                }
              ],
              "legendPosition": "BOTTOM_LEGEND",
              "series": [
                {
                  "series": {
                    "sourceRange": {
                      "sources": [
                        {
                          "endColumnIndex": 2,
                          "endRowIndex": 7,
                          "sheetId": SOURCE_SHEET_ID,
                          "startColumnIndex": 1,
                          "startRowIndex": 0,
                        }
                      ]
                    }
                  },
                  "targetAxis": "LEFT_AXIS"
                },
                {
                  "series": {
                    "sourceRange": {
                      "sources": [
                        {
                          "endColumnIndex": 3,
                          "endRowIndex": 7,
                          "sheetId": SOURCE_SHEET_ID,
                          "startColumnIndex": 2,
                          "startRowIndex": 0,
                        }
                      ]
                    }
                  },
                  "targetAxis": "LEFT_AXIS"
                },
                {
                  "series": {
                    "sourceRange": {
                      "sources": [
                        {
                          "endColumnIndex": 4,
                          "endRowIndex": 7,
                          "sheetId": SOURCE_SHEET_ID,
                          "startColumnIndex": 3,
                          "startRowIndex": 0,
                        }
                      ]
                    }
                  },
                  "targetAxis": "LEFT_AXIS"
                }
              ]
            },
            "hiddenDimensionStrategy": "SKIP_HIDDEN_ROWS_AND_COLUMNS",
            "title": "Model Q1 Sales",
          },
        }
      ]
    }
  ]
}