註解圖表

簡介

註解圖表是支援註解的互動式時間序列折線圖。請注意,註解時間軸現在會自動使用「註解圖表」。

融合快訊:目前,Google 註解圖表與其他 Google 圖表 (目前區域、長條圖、資料欄、組合、線段和散佈) 支援的註解不同。在這些圖表中,這些註解是在獨立的資料表中資料欄指定,並以簡短文字顯示,讓使用者可以將滑鼠遊標懸停在遊標上,查看完整的註解文字。相較之下,「註解圖表」則會在右側顯示完整註解,如下所示。

範例

<html>
  <head>
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type='text/javascript'>
      google.charts.load('current', {'packages':['annotationchart']});
      google.charts.setOnLoadCallback(drawChart);

      function drawChart() {
        var data = new google.visualization.DataTable();
        data.addColumn('date', 'Date');
        data.addColumn('number', 'Kepler-22b mission');
        data.addColumn('string', 'Kepler title');
        data.addColumn('string', 'Kepler text');
        data.addColumn('number', 'Gliese 163 mission');
        data.addColumn('string', 'Gliese title');
        data.addColumn('string', 'Gliese text');
        data.addRows([
          [new Date(2314, 2, 15), 12400, undefined, undefined,
                                  10645, undefined, undefined],
          [new Date(2314, 2, 16), 24045, 'Lalibertines', 'First encounter',
                                  12374, undefined, undefined],
          [new Date(2314, 2, 17), 35022, 'Lalibertines', 'They are very tall',
                                  15766, 'Gallantors', 'First Encounter'],
          [new Date(2314, 2, 18), 12284, 'Lalibertines', 'Attack on our crew!',
                                  34334, 'Gallantors', 'Statement of shared principles'],
          [new Date(2314, 2, 19), 8476, 'Lalibertines', 'Heavy casualties',
                                  66467, 'Gallantors', 'Mysteries revealed'],
          [new Date(2314, 2, 20), 0, 'Lalibertines', 'All crew lost',
                                  79463, 'Gallantors', 'Omniscience achieved']
        ]);

        var chart = new google.visualization.AnnotationChart(document.getElementById('chart_div'));

        var options = {
          displayAnnotations: true
        };

        chart.draw(data, options);
      }
    </script>
  </head>

  <body>
    <div id='chart_div' style='width: 900px; height: 600px;'></div>
  </body>
</html>

載入中

google.charts.load 套件名稱為 "annotationchart"

  google.charts.load("current", {packages: ['annotationchart']});

視覺化的類別名稱是 google.visualization.AnnotationChart

  var visualization = new google.visualization.AnnotationChart(container);

資料格式

您可以在圖表中顯示一或多行。每列代表一個圖表上的 X 位置,也就是特定時間;每行由一到三欄說明。

  • 第一欄的類型是 datedatetime,並指定圖表上點的 X 值。如果此欄的類型是 date (而非 datetime),則 X 軸上的最短時間解析度為一天。
  • 接著,系統會依一或三個額外的資料欄來說明每個資料行,說明如下:
    • Y 值 - [必要,數字] 每組第一欄用來說明第一欄內相應時間的行數值。圖表標籤會顯示在該圖表的標題中。
    • 註解標題 - [選填,字串] 如果字串資料欄跟在值欄之後,且 displayAnnotations 選項為 true,這個資料欄會保留描述這個點的簡短標題。舉例來說,如果這一行代表巴西的溫度,而這個分數極高,標題就可能是「紀錄日最激烈的日子」。
    • 註解文字 - [選填字串] 如果這個序列存在第二個字串欄,系統會使用儲存格值做為此點的額外說明文字。您必須將 displayAnnotations 選項設為 true,才能使用這個資料欄。如果將 allowHtml 設為 true,則可以使用 HTML 標記;基本上沒有大小限制,但請注意,如果項目過長,可能會導致顯示區段溢位。即使您在這個時間點中有註解標題欄,也不一定要使用此欄。圖表未使用資料欄標籤。舉例來說,如果這是記錄點最熱的一天,您可以說出「下一次的天氣是最冷的 10 度!」。

設定選項

名稱
allowHtml

如果設為 true,任何包含 HTML 標記的註解文字都會以 HTML 的形式呈現。

類型:布林值
預設值:false
allValuesSuffix

要新增至圖例和值 (垂直軸) 中所有值的後置字串。

類型:字串
預設:
註解寬度

註解區域的寬度 (以百分比表示),也就是整個圖表區域。必須為介於 5 至 80 之間的數字。

類型:數字
預設:25
顏色

圖表線標題和標籤的顏色。字串陣列。每個元素都是採用有效 HTML 顏色格式的字串。例如「red」或「#00cc00」。

類型:字串陣列
預設:預設顏色
日期格式

在右上角顯示日期資訊的格式。這個欄位的格式由 java SimpleDateFormat 類別指定。

類型:字串
預設值:「MMMM dd, yyyy」或「HH:mm MMMM dd, yyyy」,視第一欄類型而定 (分別為日期或日期)。
顯示註解

如果設為 False,圖表會隱藏註解表格,且註解和 AnnotationText 都不會顯示 (如果資料中沒有註解,則不會顯示註解表格)。將這個選項設為 true 時,每個數值欄後方可新增兩個選用註解字串欄,一個用於註解標題,另一個用於註解文字。

類型:布林值
預設:
顯示註解篩選器

如果設為 True,圖表就會顯示篩選器控制項以篩選註解。如果有多個註解,請使用這個選項。

類型:布林值
預設值:false
顯示日期列分隔符

是否在序列值和圖例中的日期之間顯示小型長條分隔符 ( | ),其中 True 代表「是」。

類型:布林值
預設:
顯示確切值

為了節省空間,是否要在圖表頂端顯示經過簡化的圓角值,則代表 False。舉例來說,如果設為 false,56123.45 可能會顯示為 56.12k。

類型:布林值
預設值:false
顯示圖例

是否在圖例文字中的值旁邊顯示點 (如果代表 true 代表是)。

類型:布林值
預設:
displayLegendValues

是否在圖例中顯示醒目顯示的值 (如果代表 true 代表是)。

類型:布林值
預設:
顯示範圍選取器

是否顯示縮放範圍選取區域 (圖表底部的區域),false 表示否。

縮放選取器的外框是圖表中第一個系列的記錄比例版本,可縮放至符合縮放選取器的高度。

類型:布林值
預設:
displayZoomButtons

是否顯示縮放按鈕 (「1d 5d 1m」,以此類推),其中 false 表示否。

類型:布林值
預設:
填滿

從 0 到 100 (含) 的數字,表示在折線圖中,每行下方的填滿 Alpha 值。100 表示 100% 不透明,0 表示完全不填。填滿顏色與上方線條顏色相同。

類型:數字
預設:0
圖例位置

是否使用顏色按鈕和日期 (「sameRow」) 將列的圖例,放在新的資料列 (「newRow」) 中。

類型:字串
預設值:「sameRow」
最高

Y 軸的最大值。如果資料點上限超過這個值,系統會忽略這項設定,且會調整圖表以在下一個資料點上方顯示下一個主要刻點。這個優先順序會高於 scaleType 決定的 Y 軸最大值。

這與核心圖表中的 maxValue 類似。

類型:數字
預設:自動

Y 軸上顯示的最小值。如果資料點下限低於這個值,系統會忽略這項設定,並調整圖表以在最低資料點下方顯示下一個主要刻點。這個優先順序會高於 scaleType 決定的 Y 軸最小值。

這與核心圖表中的 minValue 類似。

類型:數字
預設:自動
numberFormats

指定用來設定圖表頂端值的格式數字格式模式。

模式的格式應符合 java DecimalFormat 類別指定的格式。

  • 如未指定,系統會使用預設格式模式。
  • 如果指定單一字串模式,將用於所有值。
  • 如果指定了地圖,索引鍵是系列 (索引從零) 的索引,而值是用來格式化指定係列格式的模式。

    您不需要為圖表中的每個序列填入格式,任何未指定的系列都會使用預設格式。

如果指定此選項,系統會忽略 displayExactValues 選項。

類型:字串或數字:字串組合的對應關係
預設:自動
ScaleColumn

指定要在圖表中的 Y 軸刻點顯示的值。預設設定是右側採用單一縮放比例,適用於兩個序列。不過,您可以將圖表的不同邊縮放至不同的序列值。

這個選項使用 0 到 3 個數字的陣列,以指定係列的 (零) 索引值,做為擴充值。這些值的顯示位置取決於您在陣列中包含的值數量:

  • 如果您指定空白陣列,圖表就不會顯示在刻點旁邊。
  • 如果您指定一個值,指定序列的資源調度只會顯示在圖表右側。
  • 如果您指定兩個值,第二個序列的資源調度將會新增至圖表右側。
  • 如果您指定三個值,第三個序列會新增至圖表中間。
  • 系統會忽略陣列中第三個值之後的所有值。

顯示多個比例時,建議您將 scaleType 選項設為「allfixed」或「allmaximized」。

類型:數字陣列
預設:自動
ScaleFormat

用於軸刻標籤的標籤數字格式。'#' 的預設值為整數。

類型:字串
預設值:「#」
scaleType

設定 Y 軸上顯示的最大值和最小值。可用選項如下所示:

  • 'maximized' - Y 軸將橫跨系列的最小值。如果您有多個系列,請使用 allmaximized。
  • 'fixed' [default] - Y 軸會根據資料值而有所不同:
    • 如果所有值 >=0,Y 軸就會從零到最大資料值。
    • 如果所有值小於 <=0,那麼 Y 軸範圍會從零到最低資料值。
    • 如果值為正數和負數,Y 軸的範圍為系列的最大值到序列的最小值。
      如有多個系列,請使用「allfixed」。
  • 'allmaximized' - 與「maximized」相同,但在顯示多個比例時採用。兩張圖表將以相同比例將最大化,這表示 Y 軸將出現錯誤圖表,但將遊標懸停在每個序列上方會顯示其實際值。
  • 'allfixed' - 與「fixed」相同,但會在顯示多個比例時採用。這項設定將調整每個調整範圍,使其套用至適用的序列 (搭配 scaleColumns 使用)。

如果您指定最小和/或最大選項,這些選項的優先順序會高於您的資源調度類型決定的最小值和最大值。

類型:字串
預設值:「fixed」
資料表

包含註解表格的相關選項。如要指定這個物件的屬性,您可以使用物件常值標記法:

var options: {
  table: {
    sortAscending: true,
    sortColumn: 1
  }
};
      
類型:物件
預設值:空值
table.sort 遞增

如果設為 true,系統會還原註解表格的順序,並以遞增順序顯示註解。

類型:布林值
預設值:false
table.sortColumn

註解表格的資料欄索引,用於將註解排序。註解標籤欄的索引必須為 0,註解註解欄的索引則為 1。

類型:數字
預設:0
厚度

介於 0 到 10 (含) 之間的數字,用於指定線條粗細,其中 0 代表最細。

類型:數字
預設:0
zoomEndTime

設定所選縮放範圍的結束日期/時間。

類型:日期
預設:
zoomStartTime

設定所選縮放範圍的開始日期/時間。

類型:日期
預設:

方法

方法
clearChart()

清除圖表並釋出其分配的所有資源。

傳回類型:
draw(data, options, state)

繪製圖表。

傳回類型:
getContainer()

擷取含有註解圖表的容器元素的處理常式。

傳回類型:處理 DOM 元素
getSelection()

標準 getSelection() 實作。所選元素是儲存格元素。使用者一次只能選取一個儲存格。

傳回類型:選取元素陣列
getVisibleChartRange()

傳回包含 startend 屬性的物件,每個屬性都是 Date 物件,代表目前時間。

傳回類型:包含 startend 屬性的物件
hideDataColumns(columnIndexes)

在圖表中隱藏指定的資料序列。可接受一個參數,可以是數字或數字陣列,其中 0 代表第一個資料序列,依此類推。

傳回類型:
setVisibleChartRange(start, end)

將可見範圍 (縮放) 設為指定範圍。可接受 Date 類型的兩個參數,代表想要顯示可見範圍的首次和上次。將 start 設為 null 以加入從最早到 end 之間的所有日期;將 end 設為 null,加入從 start 到最後一個日期的所有內容。

傳回類型:
showDataColumns(columnIndexes)

使用 hideDataColumns 方法隱藏圖表之後,顯示圖表中的指定資料序列。可接受一個參數 (可以是數字或數字陣列),其中 0 代表第一個資料序列,依此類推。

傳回類型:

活動

名稱
rangechange

當使用者變更範圍滑桿時觸發。新的範圍端點將以 event['start']event['end'] 的形式提供:

google.visualization.events.addListener(chart, 'rangechange', rangechange_handler);

function rangechange_handler(e) {
  console.log('You changed the range to ', e['start'], ' and ', e['end']);
}
屬性:start、end
ready

圖表可供外部方法呼叫使用。如果您想要與圖表互動,並在繪製圖表後呼叫方法,請先為這個事件設定監聽器,然後再呼叫 draw 方法,並且只在事件觸發後呼叫這些方法。

屬性:無
select

使用者點選視覺實體時觸發。如要瞭解所選項目,請呼叫 getSelection()

屬性:無

資料政策

系統會處理所有程式碼和資料,並在瀏覽器中顯示。系統不會將資料傳送至任何伺服器。