SVG円形プログレスバーの円周計算とstroke-dashoffset

目次
ダッシュボードの統計カードやファイルアップロードの待機画面で、円形ゲージとして進行率(%)を示したいとき、四角いバーのようにwidthだけを変えてもうまくいきません。SVGの円の円周の長さを計算し、stroke-dasharrayとstroke-dashoffsetの値として指定することで、はじめて「その分だけ塗られた」ように見せられます。サイズ(直径)や線の太さ、目標パーセントが変わるたびに半径から計算し直す必要があるため、仕組みを理解しておけば、その値がなぜそうなるのかを自分で検証できます。
まとめ ① 円形プログレスバーは、円の円周の長さをstroke-dasharrayで宣言し、残りの区間をstroke-dashoffsetで隠すことで進行率を表現します。 ② サイズ(直径)120px・線の太さ8px・進行率75%を基準にすると、半径は56px、円周は約351.86px、stroke-dashoffsetは約87.96pxになります。 ③ 値を自分で計算せず、円のサイズ・太さ・色・進行率だけを調整してSVG・CSSコードをそのまま受け取ることもできます。
円形プログレスバーを作るときに計算が必要な理由
一般的な四角いプログレスバーは、塗られた部分の幅(width)をパーセントで変えるだけで済みますが、円形バーではそうはいきません。SVGの<circle>要素は、枠線(stroke)を実線で描くことも、stroke-dasharrayで点線のように途切れさせて描くこともできます。この途切れる間隔を円周全体の長さに合わせると、「線がどこまで描かれ、どこから空いているか」で進行率を表せます。そのため円形ゲージを作るには、まず円の円周の長さを知り、進行率に応じてどれだけを隠すかを計算する必要があります。
SVGの円周計算とCSSコードで自作する方法
計算の順序は2ステップです。
- 半径(r) = (サイズ(直径) − 線の太さ) ÷ 2
- 円周(C) = 2 × 円周率(π) × 半径(r)
- stroke-dashoffset = 円周(C) × (1 − 進行率(P) ÷ 100)
サイズ(直径)120px、線の太さ8px、目標進行率75%を例にすると、次のようになります。
- 半径: (120 − 8) ÷ 2 = 56px (線は円の中心線に沿って描かれるため、線の太さの半分だけ内側に入ります)
- 円周: 2 × 3.14159 × 56 ≈ 351.86px
- stroke-dasharray: 351.86 (円全体の円周の長さをそのまま宣言)
- stroke-dashoffset: 351.86 × (1 − 0.75) ≈ 87.96px (残りの25%分を隠して非表示に)
進行率75%の円形プログレスバーを作るマークアップとCSSは次のとおりです。
<div class="progress-circle-container">
<svg class="progress-ring" width="120" height="120">
<!-- 背景の円トラック -->
<circle class="progress-ring-bg" stroke="#e2e8f0" stroke-width="8" fill="transparent" r="56" cx="60" cy="60" />
<!-- 進行の円トラック -->
<circle class="progress-ring-bar" stroke="#3b82f6" stroke-width="8" stroke-linecap="round" fill="transparent" r="56" cx="60" cy="60" />
</svg>
<span class="progress-text">75%</span>
</div>
.progress-ring { transform: rotate(-90deg); /* 12時の方向から塗り始めるように開始点を回転 */ }
.progress-ring-bar { stroke-dasharray: 351.86; stroke-dashoffset: 87.96; /* 75% 進行状態 / transition: stroke-dashoffset 0.8s ease-in-out; / 進行率(%)の値が変わるときになめらかにつながる */ }
参考 毎回、円周率と半径の数値を電卓で叩いてstroke-dashoffsetのピクセルを算出しなくても、CSS円形プログレスバー生成ツールなら円のサイズ・太さ・色・進行率(%)をスライダーで調整しながら、SVGとCSSのコードをそのままコピーできます。
値を自分で計算してコードを手で書き換える代わりに、進行率とスタイルだけを変えながら結果をすぐに確認したい方は、無料ツールで確認してみましょう。
進捗率(%)、円のサイズ(直径)、ゲージの太さ、色を調整して、最適化されたSVG・CSS円形チャートのコードをすぐに取得できます。

進行率ごとのstroke-dashoffset値とデザインのコツ
サイズ(直径)120px、線の太さ8px(半径56px、円周≈351.86px)を基準に、進行率に応じたstroke-dashoffsetの値は次のとおりです。
| 進行率 | stroke-dashoffset |
|---|---|
| 25% | 263.89px |
| 50% | 175.93px |
| 75% | 87.96px |
| 100% | 0px |
デザインを適用するときに参考にしたい点は2つです。
- 開始点を12時の方向に回す: SVGの
<circle>の既定の開始位置は3時の方向です。12時から時計回りに満ちていくようにするには、SVG要素にtransform: rotate(-90deg)を指定します。 - 端を丸く処理する: 進行ゲージの両端を丸めるには、
stroke-linecap: roundを追加します。インフォグラフィックのような、やわらかい印象になります。
よく使うサイズ別の半径と円周の早見表
バッジのような小さな円から大きなダッシュボードカードまで、サイズ(直径)と線の太さの組み合わせが変われば、半径と円周も一緒に変わります。半径 = (直径 − 線の太さ) ÷ 2 の公式に当てはめてあらかじめ値を出しておけば、画面サイズごとに毎回計算し直さなくても、下の表ですぐに確認できます。
| サイズ(直径) | 線の太さ | 半径 | 円周 |
|---|---|---|---|
| 80px | 6px | 37px | ≈232.48px |
| 120px | 8px | 56px | ≈351.86px |
| 160px | 10px | 75px | ≈471.24px |
| 200px | 12px | 94px | ≈590.62px |
同じ進行率でも、サイズが大きくなるほど円周が長くなり、stroke-dashoffsetの値も一緒に大きくなる点に注意します。たとえばサイズ200px・線の太さ12pxの組み合わせで進行率75%なら、stroke-dashoffsetは590.62 × 0.25 ≈ 147.65pxです。
まとめ
- 円形プログレスバーは、円周(C = 2 × π × r)を
stroke-dasharrayで、残りの区間をstroke-dashoffsetで表現します。 - 半径(r)はサイズ(直径)から線の太さを引いた値の半分で、stroke-dashoffset = 円周 × (1 − 進行率 ÷ 100)の公式で、目的のパーセントの値を計算できます。
- 開始点の回転(
rotate(-90deg))と端の処理(stroke-linecap: round)は、デザインの完成度に影響します。 - サイズや線の太さ、進行率がよく変わる場合は、値を自分で計算するより、ツールでSVG・CSSコードをそのまま受け取るほうが早く済みます。
進捗率(%)、円のサイズ(直径)、ゲージの太さ、色を調整して、最適化されたSVG・CSS円形チャートのコードをすぐに取得できます。
核心技術メカニズム:SVG円形プログレスバーの動作原理
SVG円形の進捗バーが数学的にどう計算され、視覚的にどう滑らかに描画されるのか、その深層メカニズムを詳しく掘り下げます。コードをコピー&ペーストする段階を超え、ブラウザが画面上に円を描画する正確な原理を理解することで、複雑な応用が可能になります。
1. SVG Circle Strokeの座標幾何学と半径の計算式
SVGのキャンバス役を担うのはビューポート(Viewport)とビューボックス(viewBox)です。たとえばD×D(120×120px)の空間を想定した座標系を考えてみましょう。 SVGのstroke(線)は常に描画されたパス(Path)の中心線を基準に広がります。つまり線の太さ(StrokeWidth)が8pxなら、4pxはパスの内側、残りの4pxはパスの外側に領域を占めます。 したがって、円が画面の境界で切れずに全体が描画されるには、直径を120pxにしたい場合、実際にコードに書くべきパスの半径は、その半分の60pxから線の太さの半分(4px)を引いた値になります。
- 真の半径の公式(True Radius Formula): r = D − StrokeWidth/2 = 120 − 8/2 = 56px
こうして得た半径を使って円の全周長を計算します。円の周、すなわち円周(Circumference)は、幾何学の最も基本的な公式から導かれます。
- 真の円周の公式(True Circumference Formula): C = 2π r = 2 × 3.1415926535... × 56 ≈ 351.858377px
この数値(約351.86)が、今後進捗率を調整する上で最も重要な基準点になります。
2. CSS Dash Offsetによるレンダリングマスキングの物理
SVG線の点線(dash)機能を活用すると、実線ではなく進捗バーを作れます。ポイントは、点線の長さを円周全体の長さとまったく同じにすることです。
- stroke-dasharray: C C; このプロパティは「線が描かれる長さ」と「空白の長さ」を設定します。ここでC(351.86)を入れると、1本の長い点線が円を一周ぴったり覆います。
- stroke-dashoffset: C × (1 − Progress/100)
このプロパティは点線の開始位置を押し出す(Offset)役割をします。まるで目隠しを設置するかのような、物理的なマスキング効果を生みます。
- 進捗率0%のとき:Offset = C(351.86px)。点線が円周分だけ完全に後ろへ押し出され、0%の空のトラックだけが見えます。
- 進捗率50%のとき:Offset = 0.5C(175.93px)。半分だけ押し出されるため、円の半分が埋まったゲージが可視化されます。
- 進捗率100%のとき:Offset = 0px。まったく押し出されず、点線が最初から最後まで埋まり、完全に閉じた丸い円が完成します。
3. 座標系の回転(Coordinate System Rotation)
SVGの三角関数の基本座標系では、0ラジアン(radian)、つまり角度0の開始点は3時の方向(右側、x=r、y=0)です。しかし私たちが日常的に目にするプログレスバーや時計は、ほとんどが正午12時(最上部)の方向から始まり、時計回りに満ちていきます。 この直感的なUIを実装するには、描画されたSVG要素を反時計回りに90度回転させる必要があります。
- transform: rotate(-90deg); またこのとき、回転の軸が円の真正中になるよう、transform-origin: 50% 50%; または rotate(-90deg 60 60) のような基準点を必ず設定してください。この設定が漏れると、円がとんでもない軌道を描いてビューポートの外へ飛び出してしまう大惨事になります。
状況別比較表:円形プログレス実装手法マトリクス
ウェブで円形の進捗ゲージを描く方法はさまざまです。各手法の特徴と長所・短所を比較し、プロジェクトの状況に合った最適な選択ができます。
| 比較項目 | Pure SVG + stroke-dashoffset(おすすめ) | CSS conic-gradient() + マスク | HTML5 Canvas arc() | Animated GIF / Lottie | WebGLシェーダー |
|---|---|---|---|---|---|
| ベクタースケーリングの鮮明さ | 無限スケーリング(完全にクリーン) | ブラウザのレンダリングにより異なる | 高解像度(Retina)処理が別途必要 | 拡大時に崩れるかファイル容量が激増 | 非常にクリーン(ただしオーバーエンジニアリング) |
| CSSアニメーション(Transition)対応 | 完全対応(滑らかでシンプル) | 部分的に対応(@propertyなど最新仕様が必要) | 非対応(requestAnimationFrameでJSを手動コーディング) | Lottieプレーヤーに依存 | 非対応(JSレンダリングループが必要) |
| 初期ロードのバンドルとファイルサイズ | 最も軽量(約1KB未満) | 最も軽量 | 普通(キャンバス制御ロジックが必要) | 非常に重い(数百KB〜MB) | 重い(Three.jsなどのライブラリ) |
| 実装の難易度と保守性 | 簡単(数学公式を知っていればよい) | 非常に簡単 | やや複雑 | デザイナー依存度が非常に高い | 非常に難しい |
| クロスブラウザ互換性 | すべてのブラウザで完全対応 | 古いブラウザでは制約あり | 優れている | ライブラリ依存 | 低スペック端末で発熱を引き起こす |
比較まとめ: 最も広く使われ、性能面の利点が大きい方法は断然「純粋なSVGベースの方式」です。容量は羽毛のように軽く、CSSアニメーションとの相性は抜群で、どんな画面でもピクセル一つ崩れない鮮明さを誇ります。
円形プログレスバー制作でよくある5つのミス
円形チャートを作る際、多くのフロントエンド開発者がうっかり犯す致命的な誤りがあります。この5つだけをチェックすれば、デバッグ時間を大幅に短縮できます。
- 線の太さを考慮しない半径計算(クリッピングエラー): 全体の直径を2で割るだけで、線の太さ(stroke-width)の半分を引かないミスです。viewBoxの外へ枠線が押し出され、円の上下左右が平たく切れて見える原因になります。常に r = (D − S)/2 の公式を忘れないでください。
- 回転時の基準点(transform-origin)の漏れ: SVG要素を12時の方向へ回すためにrotate(-90deg)を適用するとき、transform-origin: center;(または50% 50%)を入れ忘れるケースです。円は中心軸を失い、画面の左上へ消えてしまいます。
- 粗い端の処理を放置(stroke-linecapの漏れ): 線の端を丸くするstroke-linecap: round;を入れ忘れると、進捗バーの両端が切り株のように角ばってしまいます。特に進捗率が低いときにデザインの完成度を損なう主犯です。
- 不正確な円周率の使用による誤差: πの値を単純に3.14だけで計算すると、周長のピクセル値が微妙にずれます。結果として100%の進捗率でもごくわずかな隙間(Gap)が生じ、線が完全に閉じないバグが発生します。JavaScriptのMath.PIを使うか、最低でも小数点以下4桁(3.1416)以上を使用してください。
- will-changeプロパティ未適用によるアニメーションのカクつき: データが絶えず変化する複雑なダッシュボードやリアルタイム監視システムで、CSSアニメーションにwill-change: stroke-dashoffset;の最適化を行わないと、ブラウザのレンダリングエンジンに過負荷がかかり、動作がぎこちなくなることがあります。
5ステップで完璧なSVG円形プログレスバーを作るワークフロー
コンポーネントを最も安定して正確に設計するための、ステップごとのガイドラインです。
- ステップ1:SVGキャンバスのサイズと線の太さを決める コンポーネントが画面上で占める全体のサイズ(D)と、描く線の太さ(S)を決めます。例:D = 120px、S = 8px。
- ステップ2:数学的に正しい半径(r)を導き出す ビューボックス内で切り取られないように、r = (D − S)/2 を計算します。例:(120 − 8)/2 = 56。
- ステップ3:円周(C、全体の周の長さ)を計算して変数に代入する C = 2 × π × r の公式で円周を求めます。例:2 × 3.14159 × 56 = 351.86。この値はCSSやJSの変数(CSSカスタムプロパティ)として保存しておきます。
- ステップ4:背景のトラックと前景(進行)の円を配置する 2つの<circle>タグを使い、1つはグレー系の淡い背景線、もう1つはブランドカラーを適用した進行線にします。先ほど求めたr、cx、cy属性を指定します。
- ステップ5:CSSトランジションとDash Offsetの動的な数式を適用する 前景の<circle>に stroke-dasharray: 351.86; を指定し、JavaScriptフレームワーク(React、Vueなど)から渡されるパーセント(P)値に応じて stroke-dashoffset 属性を動的に更新します。このとき transition: stroke-dashoffset 0.6s ease-out; を加えるとアニメーションが完成します。
SVG円形プログレスバーのコツ7選
単なる実装にとどまらず、ユーザー体験(UX)を最大化する7つの上級テクニックです。
- 現代的でなめらかな印象の端の処理: デザインが角ばって野暮ったく見えるのを防ぐため、必ず stroke-linecap="round" 属性を指定しましょう。円形デザインのトレンド感が引き立ちます。
- マルチカラーグラデーション(Multi-stop Gradient)の適用: 単色の線ではなく、<defs> の内部に <linearGradient> や <radialGradient> を定義し、stroke="url(#myGradient)" の形で適用すると、生き生きとしたゲージを作れます。
- 中央揃えのテキストアンカーを活用する: <text> タグで進行パーセントを表示するとき、dominant-baseline="central" と text-anchor="middle" 属性を指定すれば、x="50%" y="50%" だけで上下左右が完璧に揃います。
- ズレのないインプレース回転を保証する: 回転アニメーション時に要素がはみ出さないよう、transform-origin: 50% 50%; を設定するか、CSSではなくSVG内部の属性である transform="rotate(-90 cx cy)" を直接使ってください。
- メーター型の半円(Semi-circular Speedometer)ゲージへの応用: 360度の円ではなく、車のスピードメーターのような180度の半円ゲージを作りたい場合は、stroke-dasharray を全体の円周ではなく半分(0.5C)に制限し、開始点の回転角度を調整すれば簡単に実装できます。
- スムーズなデータストリームの更新: 株価の気配値やセンサーモニタリングなど、データが1秒に何度も変わる場合は、ease-out のような一般的なイージング関数ではなく linear を使うか、D3.js ベースの補間法(Interpolation)を組み合わせると、画面がはるかに滑らかになります。
- ボイラープレートのコードジェネレーターを活用する: サイズや太さを変えるたびにこの数式をすべて打ち直す必要はありません。本ページ上部の生成ツールを使って、完成済みのコードをすぐに出力して使うのが実務者の知恵です。
レンダリング技術を選ぶための判断ツリー(Decision Tree)
いつSVGを使い、いつ別の技術を使うべきかを一目で把握しましょう。
- Q:画面を拡大・縮小したときに、枠線が完全になめらかである必要がありますか?
- No ➔ Canvas または WebGL を検討。
- Yes ➔ 2番へ進む。
- Q:進行状態がパーセント(%)に応じてなめらかに満ちていくアニメーションが必要ですか?
- No ➔ 純粋なCSSの conic-gradient() が最も簡単です。
- Yes ➔ 3番へ進む。
- Q:React、Vueなどのフレームワークと組み合わせて、バンドルサイズを最小限に抑えたいですか?
- No ➔ Lottieアニメーションやサードパーティライブラリを使用。
- Yes ➔ 正解:SVG + stroke-dashoffset の手法(最も完璧な組み合わせ)
この判断ツリーを通して、ほとんどの最新Web UI環境では数学的なSVGベースのアプローチが正解だという結論にたどり着きます。
用語解説チートシート(Terminology Cheatsheet)
Webビジュアライゼーションに欠かせない用語を簡潔にまとめました。コードレビューやコミュニケーションの際に、迷わないように活用してください。
- 円周(Circumference): 円の縁全体の長さを意味します。公式は 2 × π × r です。この長さを基準に線の長さを決めます。
- stroke-dasharray: SVGの線を点線にしてくれる属性です。この値を円周と同じにすると、1つの巨大な点線の断片が作られます。
- stroke-dashoffset: 点線が始まる位置をどれだけずらすかを決めます。進行率0%のときは円周の分だけ押し出し、100%のときは0にします。
- stroke-linecap: round: 線の始点と終点を四角い直角ではなく、丸い曲線でなめらかにレンダリングする属性です。
- viewBox: SVG内でグラフィックが描かれる論理的なキャンバスの比率と座標系を設定する属性で、この外側にはみ出したグラフィックは切り取られ(Clip)て表示されません。
- ベクタースケーリング(Vector Scaling): 画像を点(ピクセル)の集合ではなく数式で描くため、画面を無限に拡大しても劣化が起きない特性です。
よくある質問
単なる使い方にとどまらず、技術の本質を突く3つの深掘り質問と、明快な回答です。
Q1. SVGの半径(r)を計算するとき、どうしてキャンバス全体の直径の半分から線の太さ(stroke-width)の半分を引かなければならないのですか?
A1. ブラウザのSVGレンダリングエンジンは、線(Stroke)を描くとき、基準となる見えない中心線(Path)に沿って正確に両側へ同じ太さだけ広げて描きます。もし線の太さが20pxなら、中心線の内側に10px、外側に10pxが描かれます。ここで半径をキャンバスの端にぴったり合わせると、外側に描かれるはずの10px分の線がSVGのキャンバス(viewBox)の境界の外へ押し出され、画面に表示されずスパッと切り取られてしまいます。これを防ぐために、中心線そのものを線の太さの半分だけ内側にずらし、すべての線が安全な領域に収まるようにしているのです。
Q2. SVGの円形の軌道に、単色ではなく華やかなマルチカラーグラデーションを施すにはどうすればよいですか?
A2. 通常のCSSの background-image プロパティでは、SVG内部の線の色を制御できません。代わりにSVGマークアップ内部の上部で <defs> 要素を宣言し、その中に <linearGradient> や <radialGradient> タグを作成します。その中に <stop offset="0%" stop-color="red" /> のように複数色の地点を定義したうえで、グラデーション要素にid(例:id="myGrad")を付けます。最後に <circle> の stroke 属性でグラデーションのidを参照する形、つまり stroke="url(#myGrad)" を宣言すれば、線に沿ってなめらかにつながるグラデーションが完成します。
Q3. 純粋なCSSの conic-gradient() 関数で描く円形チャートと、SVGベースの方式は根本的に何が違うのですか?
A3. CSSの conic-gradient() は、要素の背景(background)をピザの1ピースのように円錐状に塗り進めていく方式です。コードが極端に短く実装が簡単という利点がありますが、致命的な欠点があります。それは、進行率が変わるときに自然にスッと満ちていくCSS transition(アニメーション)の効果を付けるのが非常に難しいことです。(最新の @property 仕様を使えば可能ですが、古いブラウザでのサポートが途切れます)。一方、SVGの stroke-dashoffset 手法は、ほとんどのブラウザで圧倒的になめらかな60fpsのアニメーションを標準でサポートしており、枠線の端を丸く(round)処理する細部の実装もはるかに簡単です。動的で美しいUIには、常にSVG方式が優位に立ちます。
この記事は韓国語の原文をもとに作成しています。 韓国語の原文を読む