# 長條圖

長條圖提供了一種以垂直長條表示資料值的方法。它有時用於顯示趨勢資料，以及並排比較多個資料集。

const config = {
  type: 'bar',
  data: data,
  options: {
    scales: {
      y: {
        beginAtZero: true
      }
    }
  },
};const config = {
  type: 'bar',
  data: data,
  options: {
    scales: {
      y: {
        beginAtZero: true
      }
    }
  },
};

# 資料集屬性

命名空間

data.datasets[index] - 僅適用於此資料集的選項
options.datasets.bar - 適用於所有長條圖資料集的選項
options.elements.bar - 適用於所有長條圖元素的選項
options - 適用於整個圖表的選項

長條圖允許為每個資料集指定多個屬性。這些屬性用於設定特定資料集的顯示屬性。例如，長條的顏色通常以這種方式設定。在資料集命名空間中只需要指定 data 選項。

名稱	類型	可腳本化	可索引	預設值
`backgroundColor`	`顏色`	是	是	`'rgba(0, 0, 0, 0.1)'`
`base`	`數字`	是	是
`barPercentage`	`數字`	-	-	`0.9`
`barThickness`	`數字`\|`字串`	-	-
`borderColor`	`顏色`	是	是	`'rgba(0, 0, 0, 0.1)'`
`borderSkipped`	`字串`\|`布林值`	是	是	`'start'`
`borderWidth`	`數字`\|`物件`	是	是	`0`
`borderRadius`	`數字`\|`物件`	是	是	`0`
`categoryPercentage`	`數字`	-	-	`0.8`
`clip`	`數字`\|`物件`\|`false`	-	-
`data`	`物件`\|`物件[]`\| `數字[]`\|`字串[]`	-	-	必填
`grouped`	`布林值`	-	-	`true`
`hoverBackgroundColor`	`顏色`	是	是
`hoverBorderColor`	`顏色`	是	是
`hoverBorderWidth`	`數字`	是	是	`1`
`hoverBorderRadius`	`數字`	是	是	`0`
`indexAxis`	`字串`	-	-	`'x'`
`inflateAmount`	`數字`\|`'auto'`	是	是	`'auto'`
`maxBarThickness`	`數字`	-	-
`minBarLength`	`數字`	-	-
`label`	`字串`	-	-	`''`
`order`	`數字`	-	-	`0`
`pointStyle`	`pointStyle`	是	-	`'circle'`
`skipNull`	`布林值`	-	-
`stack`	`字串`	-	-	`'bar'`
`xAxisID`	`字串`	-	-	第一個 x 軸
`yAxisID`	`字串`	-	-	第一個 y 軸

如果這些值為 undefined，則會回退到選項解析中描述的範圍

# 資料集設定範例

data: {
    datasets: [{
        barPercentage: 0.5,
        barThickness: 6,
        maxBarThickness: 8,
        minBarLength: 2,
        data: [10, 20, 30, 40, 50, 60, 70]
    }]
};

# 一般

名稱	描述
`base`	沿著數值軸的資料單位中長條的基本值。如果未設定，則預設為數值軸基本值。
`clip`	如何相對於 chartArea 剪裁。正值允許溢位，負值會將多餘的像素剪裁到 chartArea 內部。`0` = 在 chartArea 剪裁。也可以針對每一側設定剪裁：`clip: {left: 5, top: false, right: -2, bottom: 0}`
`grouped`	長條是否應該在索引軸上分組。當 `true` 時，相同索引值的所有資料集將彼此相鄰放置，並以該索引值為中心。當 `false` 時，每個長條都放置在其真實的索引軸值上。
`indexAxis`	資料集的基本軸。垂直長條為 `'x'`，水平長條為 `'y'`。
`label`	資料集的標籤，會顯示在圖例和工具提示中。
`order`	資料集的繪圖順序。也會影響堆疊、工具提示和圖例的順序。更多
`skipNull`	如果為 `true`，則在判斷長條大小時，不會使用 null 或 undefined 值進行間距計算。
`stack`	此資料集所屬的群組 ID (堆疊時，每個群組將是一個單獨的堆疊)。更多
`xAxisID`	要在其上繪製此資料集的 x 軸 ID。
`yAxisID`	要在其上繪製此資料集的 y 軸 ID。

# 樣式

可以使用以下屬性控制每個長條的樣式

名稱	描述
`backgroundColor`	長條的背景顏色。
`borderColor`	長條的邊框顏色。
`borderSkipped`	繪製長條時要跳過的邊緣。
`borderWidth`	長條邊框寬度 (以像素為單位)。
`borderRadius`	長條邊框半徑 (以像素為單位)。
`minBarLength`	設定此項可確保長條具有最小長度 (以像素為單位)。
`pointStyle`	圖例中點的樣式。更多...

如果這些值為 undefined，則會回退到相關聯的 elements.bar.* 選項。

# borderSkipped

此設定用於避免在填滿的底部繪製長條筆觸，或停用邊框半徑。一般來說，除非建立衍生自長條圖的圖表類型，否則不需要變更此設定。

注意

對於垂直圖表中的負長條，top 和 bottom 會翻轉。水平圖表中 left 和 right 也是如此。

選項如下

'start'
'end'
'middle' (僅在堆疊長條上有效：會跳過長條之間的邊框)
'bottom'
'left'
'top'
'right'
false (不跳過任何邊框)
true (跳過所有邊框)

# borderWidth

如果此值是數字，則會套用至矩形的所有邊 (左、上、右、下)，但 borderSkipped 除外。如果此值是物件，則 left 屬性會定義左邊框寬度。同樣地，也可以指定 right、top 和 bottom 屬性。會跳過省略的邊框和 borderSkipped。

# borderRadius

如果此值是數字，則會套用至矩形的所有角 (topLeft、topRight、bottomLeft、bottomRight)，但與 borderSkipped 接觸的角除外。如果此值是物件，則 topLeft 屬性會定義左上角的邊框半徑。同樣地，也可以指定 topRight、bottomLeft 和 bottomRight 屬性。會跳過省略的角和與 borderSkipped 接觸的角。例如，如果跳過 top 邊框，也會跳過角 topLeft 和 topRight 的邊框半徑。

堆疊圖表

當邊框半徑以數字形式提供且圖表已堆疊時，半徑僅會套用至位於堆疊邊緣或長條浮動的長條。物件語法可用於覆寫此行為。

# inflateAmount

此選項可用於膨脹用於繪製長條的矩形。當 barPercentage * categoryPercentage 為 1 時，這可用於隱藏長條之間的偽像。預設值 'auto' 在大多數情況下都應該有效。

# 互動

可以使用以下屬性控制與每個長條的互動

名稱	描述
`hoverBackgroundColor`	滑鼠停在其上時，長條的背景顏色。
`hoverBorderColor`	滑鼠停在其上時，長條的邊框顏色。
`hoverBorderWidth`	滑鼠停在其上時，長條的邊框寬度 (以像素為單位)。
`hoverBorderRadius`	滑鼠停在其上時，長條的邊框半徑 (以像素為單位)。

如果這些值為 undefined，則會回退到相關聯的 elements.bar.* 選項。

# barPercentage

每個長條應在類別寬度內的可用寬度百分比 (0-1)。1.0 將佔用整個類別寬度，並將長條彼此相鄰放置。更多...

# categoryPercentage

每個類別應在樣本寬度內的可用寬度百分比 (0-1)。更多...

# barThickness

如果此值是數字，則會套用至每個長條的寬度 (以像素為單位)。強制執行此設定時，會忽略 barPercentage 和 categoryPercentage。

如果設定為 'flex'，則會根據前一個和後續樣本自動計算基本樣本寬度，以便它們佔用所有可用的寬度而不會重疊。然後，使用 barPercentage 和 categoryPercentage 來調整長條大小。當百分比選項為 1 時，沒有間隙。當資料間隔不均勻時，此模式會產生具有不同寬度的長條。

如果未設定 (預設)，則會使用可防止長條重疊的最小間隔計算基本樣本寬度，並使用 barPercentage 和 categoryPercentage 來調整長條大小。此模式始終會產生大小相同的長條。

# maxBarThickness

設定此項可確保長條的大小不會超過此值。

# 刻度設定

長條圖會從相關聯的 scale 選項中為以下設定設定唯一的預設值

名稱	類型	預設值	描述
`offset`	`布林值`	`true`	如果為 true，則會在兩個邊緣新增額外空間，並縮放座標軸以符合圖表區域。
`grid.offset`	`布林值`	`true`	如果為 true，則特定資料點的長條會落在網格線之間。網格線將向左移動刻度間隔的一半。如果為 false，則網格線將正好位於長條的中央。更多...

# 刻度設定範例

options = {
    scales: {
        x: {
            grid: {
              offset: true
            }
        }
    }
};

# 偏移網格線

若為真，特定數據點的長條圖會落在格線之間。格線會向左移動刻度間隔的一半，即格線之間的空間。若為假，格線會正好位於長條圖的中心。在長條圖中，類別比例尺預設為真，而其他比例尺或圖表類型則預設為假。

# 預設選項

通常會希望將設定套用於所有建立的長條圖。全域長條圖設定儲存在 Chart.overrides.bar 中。變更全域選項只會影響變更後建立的圖表。現有的圖表不會變更。

# barPercentage 與 categoryPercentage

以下顯示長條百分比選項和類別百分比選項之間的關係。

// categoryPercentage: 1.0
// barPercentage: 1.0
Bar:        | 1.0 | 1.0 |
Category:   |    1.0    |
Sample:     |===========|
// categoryPercentage: 1.0
// barPercentage: 0.5
Bar:          |.5|  |.5|
Category:  |      1.0     |
Sample:    |==============|
// categoryPercentage: 0.5
// barPercentage: 1.0
Bar:             |1.0||1.0|
Category:        |   .5   |
Sample:     |==================|

# 資料結構

所有支援的資料結構都可以用於長條圖。

# 堆疊長條圖

可以透過變更 X 軸和 Y 軸的設定來啟用堆疊，將長條圖設定為堆疊長條圖。堆疊長條圖可以用來顯示一個數據系列如何由許多較小的部分組成。

const stackedBar = new Chart(ctx, {
    type: 'bar',
    data: data,
    options: {
        scales: {
            x: {
                stacked: true
            },
            y: {
                stacked: true
            }
        }
    }
});

# 水平長條圖

水平長條圖是垂直長條圖的一種變體。有時會用於顯示趨勢資料，以及並排比較多個數據集。要達成此目的，您必須將選項物件中的 indexAxis 屬性設定為 'y'。此屬性的預設值為 'x'，因此將會顯示垂直長條。

const config = {
  type: 'bar',
  data,
  options: {
    indexAxis: 'y',
  }
};const config = {
  type: 'bar',
  data,
  options: {
    indexAxis: 'y',
  }
};

# 水平長條圖設定選項

水平長條圖的設定選項與長條圖相同。但是，在長條圖中於 x 軸指定的任何選項，都會套用於水平長條圖的 y 軸。

# 內部資料格式

{x, y, _custom}，其中 _custom 是一個可選物件，定義堆疊長條屬性：{start, end, barStart, barEnd, min, max}。start 和 end 是輸入值。這兩個值會重複出現在 barStart（更接近原點）、barEnd（更遠離原點）、min 和 max 中。

← 面積圖泡泡圖 →