Documentation / @finchart/core / Plot
Class: Plot
Defined in: packages/core/src/plot/plot.ts:414
조작을 실제로 적용하는 쪽. 차트가 구현한다.
입력은 픽셀로 들어오지만 도메인은 데이터 단위라 환산이 필요하다. 환산에 쓰이는 스케일은 차트만 알고 있으므로 픽셀 진입점도 여기 둔다 — 핸들러가 스케일을 알게 되면 입력 층이 좌표계까지 떠안는다.
Implements
InteractionTargetRenderRequesterDecorationHostPlotEventSourcePaneHostInputHostOverlayHostViewportControlXCoordinatesFormatSourceCursorHostFocusAreaHostPluginHost<Plot>
Constructors
Constructor
new Plot(
options):Plot
Defined in: packages/core/src/plot/plot.ts:503
Parameters
options
Returns
Plot
Accessors
mainPane
Get Signature
get mainPane():
Pane
Defined in: packages/core/src/plot/plot.ts:457
시리즈를 담는 기본 pane. 항상 존재한다.
pane을 따로 만들지 않으면 모든 시리즈가 여기 들어가므로, pane이 하나인 것이 지금까지의 동작 그대로다.
밖으로는 좁은 얼굴만 나간다 — 프레임 배선(setArea·draw …)은 무대의 것이다 → PaneApi
Returns
시리즈를 담는 기본 pane. 항상 존재한다.
Implementation of
overlay
Get Signature
get overlay():
unknown
Defined in: packages/core/src/plot/plot.ts:913
annotation·tooltip을 올리는 DOM 레이어. 캔버스를 다시 그려도, 시리즈를 교체해도 여기 붙인 것은 살아남는다.
코어는 이것이 무엇인지 모른다 — 레이어가 넣은 것을 그대로 내놓는다 (ChartLayers.overlay). DOM 소비자는 requireOverlayElement로 좁힌다. headless 무대에는 없다(null) — DOM이 없으니 올릴 곳도 없다 (H2).
Returns
unknown
Implementation of
panes
Get Signature
get panes(): readonly
Pane[]
Defined in: packages/core/src/plot/plot.ts:618
위에서부터 쌓인 순서.
복사본이다 (51차 ㉒). readonly는 컴파일러의 약속이라 원본을 주면 런타임에 splice가 통하고, 그것은 무대가 그리는 목록 자체다 — 밖에서 pane 하나를 뽑으면 detach도 구독 해제도 없이 사라져 확장의 dispose가 영영 안 불린다. 목록을 바꾸는 문은 addPane·removePane뿐이다.
Returns
readonly Pane[]
위에서부터 쌓인 순서.
Implementation of
Methods
addDecoration()
addDecoration(
decoration,options?): () =>void
Defined in: packages/core/src/plot/plot.ts:678
무대 전체에 장식을 얹는다. 값 축을 쓰지 않는 것이 여기 온다 — 크로스헤어, 구간 음영, 워터마크.
y가 필요하면 pane.addDecoration을 쓴다. x는 Plot이, y는 Pane이 소유하기 때문이다 (ADR-0002).
Parameters
decoration
options?
DecorationOptions = {}
Returns
() => void
Implementation of
addInputConsumer()
addInputConsumer(
consumer,options?): () =>void
Defined in: packages/core/src/plot/plot.ts:1210
입력을 먼저 받아 볼 소비자를 얹는다 — 드로잉 툴·축 드래그가 이 자리다 (X2).
addDecoration과 같은 모양이다: 해제 함수를 돌려주고, 플러그인의 teardown에 그대로 들어간다. 우선순위는 클수록 먼저, 동률은 나중 등록이 먼저다 — 위에 그려진 것이 먼저 잡는 관례.
Parameters
consumer
options?
InputConsumerOptions = {}
Returns
() => void
Implementation of
addPane()
addPane(
options?):Pane
Defined in: packages/core/src/plot/plot.ts:793
아래에 pane을 하나 더 쌓는다.
값 범위가 전혀 다른 지표(RSI·거래량)를 위한 것이다. 가격 위에 겹치기만 하면 되는 지표는 pane을 만들지 말고 mainPane.addSeries를 쓴다.
값 축은 따로 갖는다 — 기본은 선형이고, 로그가 필요하면 넣어 준다.
Parameters
options?
PaneOptions & object = {}
Returns
Implementation of
applyOptions()
applyOptions(
options):void
Defined in: packages/core/src/plot/plot.ts:1030
설정만 바꾼다. 레이어도 도메인도 건드리지 않는다.
그리드 토글 같은 것 때문에 Plot을 다시 만들면 캔버스가 새로 생기면서 pan 위치와 오버레이의 annotation이 통째로 날아간다.
준 자리만 바뀐다. axis: { x }를 줘도 y는 그대로다 — 예전 setConfig는 얕은 병합이라 여기서 조용히 날아갔다. 자리마다 갈아 끼우는 단위는 PlotOptionsPatch에 적혀 있다.
Parameters
options
Returns
void
applyState()
applyState(
state):void
Defined in: packages/core/src/plot/plot.ts:1529
상태 조각을 밖에서 반영한다. 준 조각만 바뀐다 — 부분 적용이 곧 "줌만 밖에서" 같은 부분 controlled의 재료다.
TanStack처럼 상태의 원천을 밖으로 옮기지 않는다 — pan이 60fps로 도는 캔버스에서 그 왕복은 한 프레임 늦은 드래그가 된다. 코어는 거울 + 되먹임 (getState / stateChange / applyState)이고, controlled 모양은 React 래퍼가 이 셋으로 조립한다.
xDomain: null은 "fit 전"의 스냅샷이라 반영할 것이 없다 — 무시한다. panes는 인덱스로 짝을 맞추고, 지금 없는 pane의 조각은 버린다 — pane을 만드는 쪽(래퍼)이 목록이 바뀔 때 다시 적용한다.
Parameters
state
Partial<ChartState>
Returns
void
claimCursor()
claimCursor(
cursor): () =>void
Defined in: packages/core/src/plot/plot.ts:1236
커서 모양을 주장한다 — 도구의 드래그·작도, 축 hover가 이 자리다.
나중 클레임이 이긴다. hover 위에 드래그가 자연히 얹히고, 해제하면 아래 것으로 돌아온다(입력 스택의 "나중 등록이 먼저"와 같은 방향). 드래그 중에 모양을 바꾸는 소비자는 새것을 먼저 얹고 옛것을 풀어야 꼭대기가 사이에 흔들리지 않는다.
값은 CSS cursor의 어휘 그대로다 — 유니온으로 다시 적지 않는다. headless 레이어에는 보여 줄 커서가 없어 주장은 쌓이되 화면이 없을 뿐이다. 해제는 멱등이다.
Parameters
cursor
string
Returns
() => void
Implementation of
claimFocusArea()
claimFocusArea(
areaOf):FocusClaim
Defined in: packages/core/src/plot/plot.ts:1389
FocusAreaHost — 확장이 *"커서가 키를 겨루는 남에게 갔다"*와 *"아무에게도 안 갔다"*를 가르는 문.
47차는 여기서 *"영역을 가진 남이 있는가"*를 물었다. 그러면 범례·워터마크처럼 키보드에 관심 없는 주장자가 도구함의 Delete를 죽인다 — 48차 배포차단. 등록은 이제 *"나도 키를 겨룬다"*는 선언이다.
Parameters
areaOf
() => PlotArea | null
Returns
Implementation of
click()
click(
position):void
Defined in: packages/core/src/plot/plot.ts:1337
클릭 셋 — crosshair와 같은 에코다. 페이로드도 같은 모양이다 (2.5).
Parameters
position
Returns
void
Implementation of
contextMenu()
contextMenu(
position):void
Defined in: packages/core/src/plot/plot.ts:1345
Parameters
position
Returns
void
Implementation of
crosshair()
crosshair(
position):void
Defined in: packages/core/src/plot/plot.ts:1311
커서 아래를 좌표에서 의미로 바꾼다.
값은 pane마다 다른 스케일에서 나오므로 어느 pane 위인지부터 찾는다. 여백이나 pane 사이 간격이면 읽을 값이 없다.
Parameters
position
Returns
void
Implementation of
destroy()
destroy():
void
Defined in: packages/core/src/plot/plot.ts:2137
Returns
void
doubleClick()
doubleClick(
position):void
Defined in: packages/core/src/plot/plot.ts:1341
Parameters
position
Returns
void
Implementation of
fitDomains()
fitDomains():
void
Defined in: packages/core/src/plot/plot.ts:982
지금 가진 데이터 전체가 보이도록 두 축을 다시 맞춘다.
Returns
void
Implementation of
formatX()
formatX(
value):string
Defined in: packages/core/src/plot/plot.ts:900
해석된 x 표기 (F1) — config.axis.x.format, 없으면 반올림 정수. x는 무대의 것이라 여기 있다 (ADR-0002). 장식 컨텍스트와 툴팁 (FormatSource)의 기본값이 이걸 읽는다. 화살표인 이유는 컨텍스트에 함수째 실리기 때문이다.
Parameters
value
number
Returns
string
Implementation of
getOptions()
getOptions():
PlotConfig
Defined in: packages/core/src/plot/plot.ts:1085
지금 설정의 복사본. 고쳐도 무대는 모른다 — 바꾸는 창구는 applyOptions 하나다.
얕은 복사였을 때는 getOptions().padding.left = 0이 내부를 그대로 바꿨다. 중첩된 자리가 셋(padding·axis·style)뿐이라 손으로 복사한다 — 구조적 복제(structuredClone)는 format·ticks처럼 함수를 든 자리에서 던진다.
Returns
getSeries()
getSeries():
unknown
Defined in: packages/core/src/plot/plot.ts:1016
mainPane에 처음 얹힌 시리즈. 여러 개를 보려면 mainPane.getSeries()를 쓴다. 아직 아무것도 얹지 않았으면 undefined다.
파생 시리즈는 원본과 점 타입이 다를 수 있어 좁히지 않는다 — 신원 비교용이다.
Returns
unknown
getState()
getState():
ChartState
Defined in: packages/core/src/plot/plot.ts:1434
보는 상태의 스냅샷. 밖에서 들 수 있는 값이다 (계획 H1).
xDomain은 도메인(매핑 공간)이 아니라 데이터의 x다 — 인덱스는 밖으로 안 나간다(ADR-0021). 직렬화해 두었다가 다른 세션에서 복원해도, 봉 번호 좌표계가 그때의 데이터로 인덱스를 다시 세우면 같은 자리가 나온다.
아직 데이터에 맞춘 적이 없으면 xDomain은 null이다 — 스케일 기본값 [0,1]은 사용자가 만든 상태가 아니라서, 저장할 것도 아니다.
Returns
on()
on<
E>(event,handler): () =>void
Defined in: packages/core/src/plot/plot.ts:1135
해제 함수를 돌려준다. 두 번 불러도 안전하다.
Type Parameters
E
E extends keyof PlotEvents
Parameters
event
E
handler
EventHandler<E>
Returns
() => void
Implementation of
pan()
pan(
offset):void
Defined in: packages/core/src/plot/plot.ts:1272
x 도메인을 offset만큼 민다. y는 건드리지 않는다.
offset은 도메인 단위다 — 연속이면 데이터 x, 봉 번호면 봉 개수. 픽셀에서 출발하는 panByPixels는 그래서 좌표계와 무관하게 맞다.
Parameters
offset
number
Returns
void
Implementation of
panByPixels()
panByPixels(
dx):void
Defined in: packages/core/src/plot/plot.ts:1292
드래그 거리를 도메인 이동으로 옮긴다. 오른쪽으로 끌면 이전 구간이 보여야 하므로 부호를 뒤집는다.
Parameters
dx
number
Returns
void
Implementation of
pixelAtX()
pixelAtX(
x):number
Defined in: packages/core/src/plot/plot.ts:890
데이터 x가 놓이는 화면 x(px).
Parameters
x
number
Returns
number
Implementation of
removePane()
removePane(
pane):void
Defined in: packages/core/src/plot/plot.ts:829
mainPane은 항상 남는다 — 시리즈가 갈 곳이 없어지기 때문이다.
Parameters
pane
Returns
void
Implementation of
render()
render():
void
Defined in: packages/core/src/plot/plot.ts:1698
예약을 기다리지 않고 지금 그린다.
파괴된 뒤에는 아무것도 하지 않는다. 던지지 않는 이유는 언마운트 도중 늦게 도착한 이벤트 핸들러가 부르는 것이 정상적인 경로이기 때문이다.
Returns
void
requestRender()
requestRender():
void
Defined in: packages/core/src/plot/plot.ts:701
다음 프레임에 다시 그려 달라고 요청한다.
자기 상태를 들고 있는 장식(십자선처럼)이 화면을 갱신하는 창구다. render()와 달리 같은 프레임의 요청은 하나로 합쳐진다 → ADR-0004
Returns
void
Implementation of
routeInput()
routeInput(
event):boolean
Defined in: packages/core/src/plot/plot.ts:1262
정규화된 입력을 스택에 제안한다. 핸들러가 제스처 번역 전에 부른다 — true면 먹힌 것이라 pan/zoom/crosshair로 내려가지 않는다.
호스트가 입력을 직접 몰 때(핸들러 없이)도 이 문으로 넣으면 소비자들이 같은 규칙으로 동작한다.
Parameters
event
Returns
boolean
Implementation of
scrollToRealTime()
scrollToRealTime():
void
Defined in: packages/core/src/plot/plot.ts:976
창의 폭은 그대로 두고 라이브(마지막 봉 + rightOffset)로 돌아온다 (lightweight scrollToRealTime). fitDomains와 달리 줌 레벨이 살아남는다 — 과거를 보다 돌아오는 ⏩의 목적지다.
Returns
void
setSeries()
setSeries<
TSource,TPoint>(registration):SeriesHandle<TSource,TPoint>
Defined in: packages/core/src/plot/plot.ts:1000
mainPane을 이 등록 하나로 갈아 끼운다. 손잡이를 돌려준다.
x 도메인은 건드리지 않으므로 보고 있던 구간(pan/zoom)이 유지된다. y는 시리즈마다 차지하는 범위가 달라서(라인=close, 캔들=low~high) 다시 맞춘다.
데이터는 따라오지 않는다 — 등록의 것이므로 새 등록에 같이 준다.
Type Parameters
TSource
TSource extends BaseDataPoint
TPoint
TPoint extends BaseDataPoint = TSource
Parameters
registration
SeriesRegistration<TSource, TPoint> | Series<TSource>
Returns
SeriesHandle<TSource, TPoint>
setViewport()
setViewport(
viewport):void
Defined in: packages/core/src/plot/plot.ts:1114
"준 것만 바꾼다"를 문자 그대로 지킨다 — F1의 길목 ③ (docs/plans/boundary-values-approach-2026-08-18.md).
예전에는 { ...this.viewportSize, ...viewport }였다. 스프레드는 명시적 undefined도 값으로 취급하므로, setViewport({ width: 640, height: undefined })가 높이를 지웠다 — 그리고 @finchart/react가 정확히 그렇게 부른다(use-chart.ts: 폭만 prop으로 받으면 높이는 undefined로 간다). 지워진 높이는 레이아웃 산수에서 NaN이 되어 스케일 range까지 흘렀다.
1283개 테스트가 이것을 못 잡았다 — 아무도 결과 range를 단언하지 않았고, NaN은 조용히 그려지기 때문이다. F1의 requireFinite가 잡았다.
Parameters
viewport
Partial<ViewportDimensions>
Returns
void
setVisibleRange()
setVisibleRange(
fromX,toX):void
Defined in: packages/core/src/plot/plot.ts:958
보는 x 구간을 데이터의 x로 잡는다 (2.3, lightweight setVisibleRange).
applyState의 xDomain 조각과 같은 산술이다 — 봉 번호 좌표계면 toDomain이 인덱스로 되찾는다. 데이터 전이면 pending으로 화해한다.
Parameters
fromX
number
toX
number
Returns
void
Implementation of
ViewportControl.setVisibleRange
takeScreenshot()
takeScreenshot():
string
Defined in: packages/core/src/plot/plot.ts:1325
지금 화면을 PNG dataURL로 (2.5).
픽셀의 주인은 레이어라 위임이다. 찍기 전에 한 프레임을 지금 그린다 — 스케줄러가 프레임을 미루는 배선(rAF)에서 예약만 걸린 채 찍으면 옛 그림이 나온다. 레이어가 능력을 안 주면(headless) 던진다.
DOM 라벨 배선이면 라벨이 빠진 그림이다 — 온전한 스크린샷은 createCanvasAxisLabels 배선이 전제다 (ADR-0023).
Returns
string
use()
use<
Api>(plugin):Api
Defined in: packages/core/src/plot/plot.ts:663
확장 하나를 설치하고 그것이 만든 API를 그대로 돌려준다.
const maximize = plot.use(paneMaximize()); // 타입이 그냥 따라온다
maximize.maximize(plot.mainPane);무대의 것과 pane의 것을 가르는 기준은 "무엇에 매달리는가"다. 위 예제가 오래 드로잉 툴이었는데 그것은 틀린 예제였다 — 드로잉 툴은 pane.use(drawingTools({ plot }))이다(pane의 값 축을 쓴다). JSDoc은 발행되는 .d.ts에 실려 에디터 툴팁이 되므로, 여기 틀린 스니펫은 문서보다 멀리 간다 (38차 R2).
(틀린 형태를 주석에 인용하지 않는다: snippet-drift.test.ts가 발행 소스를 훑어 인자 없는 호출을 막으므로, 설명으로 적은 것도 위반으로 잡힌다. 같은 함정에 두 번 걸렸다 — 39차 R5의 옛 토큰 이름이 첫 번째였다.)
인스턴스에 메서드를 병합하지 않는다. TanStack Table v8이 _features로 그렇게 하는데(table.getSortedRowModel()), 타입 곡예가 필요하고 코어 타입이 플러그인마다 달라진다. 돌려주기만 하면 Plot 타입이 플러그인 때문에 변하지 않고 선언 병합도 필요 없다.
설치 순서는 그리는 순서가 아니다. 그건 z가 정한다 (ADR-0010).
Type Parameters
Api
Api extends PluginApi
Parameters
plugin
Plugin<Plot, Api>
Returns
Api
Implementation of
xAt()
xAt(
pixel):number
Defined in: packages/core/src/plot/plot.ts:885
화면 x(px) 아래의 데이터 x. 봉 번호 좌표계여도 인덱스가 아니다.
히트 테스트를 하는 확장이 쓰는 문이다 — 예전에는 이 문이 없어서 @finchart/tools가 draw 컨텍스트를 변수에 훔쳐 두고 있었다.
Parameters
pixel
number
Returns
number
Implementation of
zoom()
zoom(
factor,center):void
Defined in: packages/core/src/plot/plot.ts:1283
center를 고정한 채 x 도메인을 factor배 확대한다 (factor > 1이면 확대).
Parameters
factor
number
center
number
Returns
void
Implementation of
zoomAtPixel()
zoomAtPixel(
factor,screenX):void
Defined in: packages/core/src/plot/plot.ts:1300
휠 커서 아래 지점을 고정한 채 확대한다.
Parameters
factor
number
screenX
number
Returns
void