Merge pull request #673 from klinecharts/feature/#663

liihuu · web-flow · commit 97a4921c1131 · 2025-03-12T01:30:36.000+08:00
opt: opt `customApi.formatDate`
diff --git a/docs/@views/api/references/chart/init.md b/docs/@views/api/references/chart/init.md
@@ -45,7 +45,12 @@
     styles?: string | Styles
     timezone?: string
     customApi?: {
-      formatDate?: (timestamp: number, format: string, type: number) => string
+      formatDate?: (params: {
+        dateTimeFormat: Intl.DateTimeFormat
+        timestamp: number
+        template: string
+        type: 'tooltip' | 'crosshair' | 'xAxis'
+      }) => string
       formatBigNumber?: (value: string | number) => string
     }
     thousandsSeparator?: {
diff --git a/docs/@views/api/references/instance/setCustomApi.md b/docs/@views/api/references/instance/setCustomApi.md
@@ -1,7 +1,12 @@
 ```typescript
 (
   customApi: {
-    formatDate?: (timestamp: number, format: string, type: number) => string
+    formatDate?: (params: {
+      dateTimeFormat: Intl.DateTimeFormat
+      timestamp: number
+      template: string
+      type: 'tooltip' | 'crosshair' | 'xAxis'
+    }) => string
     formatBigNumber?: (value: string | number) => string
   }
 ) => void
diff --git a/docs/@views/api/samples/init-formateDate/index.js b/docs/@views/api/samples/init-formateDate/index.js
@@ -1,33 +1,31 @@
-import { init } from 'klinecharts';
+import { init, utils } from 'klinecharts'
 
 const chart = init(
   'init-formatDate-chart',
   {
     customApi: {
-      formatDate: (timestamp, _, type) => {
-        const date = new Date(timestamp)
-        const year = date.getFullYear()
-        const month = `${date.getMonth() + 1}`.padStart(2, '0')
-        const day = `${date.getDate()}`.padStart(2, '0')
-        const hour = `${date.getHours()}`.padStart(2, '0')
-        const minute = `${date.getMinutes()}`.padStart(2, '0')
+      formatDate: ({
+        dateTimeFormat,
+        timestamp,
+        type
+      }) => {
         switch (type) {
-          case 0: {
-            return `${year}-${month}-${day} ${hour}:${minute}`
+          case 'tooltip': {
+            return utils.formatDate(dateTimeFormat, timestamp, 'YYYY-MM-DD HH:mm')
           }
-          case 1: {
-            return `${year}-${month}-${day}`
+          case 'crosshair': {
+            return utils.formatDate(dateTimeFormat, timestamp, 'YYYY-MM-DD')
           }
-          case 2: {
-            return `${month}-${day}`
+          case 'xAxis': {
+            return utils.formatDate(dateTimeFormat, timestamp, 'MM-DD')
           }
         }
-        return `${month}-${day} ${hour}-${minute}`
+        return utils.formatDate(dateTimeFormat, timestamp, 'MM-DD HH:mm')
       }
     }
   }
 )
 
 fetch('https://klinecharts.com/datas/kline.json')
   .then(res => res.json())
-  .then(dataList => { chart.applyNewData(dataList); });
+  .then(dataList => { chart.applyNewData(dataList) })
diff --git a/docs/@views/api/samples/setCustomApi-formatDate/index.js b/docs/@views/api/samples/setCustomApi-formatDate/index.js
@@ -1,30 +1,28 @@
-import { init } from 'klinecharts';
+import { init, utils } from 'klinecharts'
 
 const chart = init('setCustomApi-formatDate-chart')
 
 chart.setCustomApi({
-  formatDate: (timestamp, _, type) => {
-    const date = new Date(timestamp)
-    const year = date.getFullYear()
-    const month = `${date.getMonth() + 1}`.padStart(2, '0')
-    const day = `${date.getDate()}`.padStart(2, '0')
-    const hour = `${date.getHours()}`.padStart(2, '0')
-    const minute = `${date.getMinutes()}`.padStart(2, '0')
+  formatDate: ({
+    dateTimeFormat,
+    timestamp,
+    type
+  }) => {
     switch (type) {
-      case 0: {
-        return `${year}-${month}-${day} ${hour}:${minute}`
+      case 'tooltip': {
+        return utils.formatDate(dateTimeFormat, timestamp, 'YYYY-MM-DD HH:mm')
       }
-      case 1: {
-        return `${year}-${month}-${day}`
+      case 'crosshair': {
+        return utils.formatDate(dateTimeFormat, timestamp, 'YYYY-MM-DD')
       }
-      case 2: {
-        return `${month}-${day}`
+      case 'xAxis': {
+        return utils.formatDate(dateTimeFormat, timestamp, 'MM-DD')
       }
     }
-    return `${month}-${day} ${hour}-${minute}`
+    return utils.formatDate(dateTimeFormat, timestamp, 'MM-DD HH:mm')
   }
 })
 
 fetch('https://klinecharts.com/datas/kline.json')
   .then(res => res.json())
-  .then(dataList => { chart.applyNewData(dataList); });
+  .then(dataList => { chart.applyNewData(dataList) })
diff --git a/src/Options.ts b/src/Options.ts
@@ -19,12 +19,19 @@ import type { IndicatorCreate } from './component/Indicator'
 import type { PaneOptions } from './pane/types'
 
 export enum FormatDateType {
-  Tooltip,
-  Crosshair,
-  XAxis
+  Tooltip = 'tooltip',
+  Crosshair = 'crosshair',
+  XAxis = 'xAxis',
 }
 
-export type FormatDate = (timestamp: number, format: string, type: FormatDateType) => string
+export interface FormatDateParams {
+  dateTimeFormat: Intl.DateTimeFormat
+  timestamp: number
+  template: string
+  type: FormatDateType
+}
+
+export type FormatDate = (params: FormatDateParams) => string
 
 export type FormatBigNumber = (value: string | number) => string
 
diff --git a/src/Store.ts b/src/Store.ts
@@ -14,6 +14,7 @@
 
 import type Nullable from './common/Nullable'
 import type DeepPartial from './common/DeepPartial'
+import type PickRequired from './common/PickRequired'
 import type { KLineData, VisibleRangeData } from './common/Data'
 import type VisibleRange from './common/VisibleRange'
 import type Coordinate from './common/Coordinate'
@@ -24,7 +25,7 @@ import type BarSpace from './common/BarSpace'
 import type Precision from './common/Precision'
 import Action from './common/Action'
 import { ActionType, type ActionCallback } from './common/Action'
-import { formatValue, formatTimestampToString, formatBigNumber, formatThousands, formatFoldDecimal } from './common/utils/format'
+import { formatValue, formatTimestampByTemplate, formatBigNumber, formatThousands, formatFoldDecimal } from './common/utils/format'
 import { getDefaultStyles, type TooltipFeatureStyle, type Styles, type TooltipLegend } from './common/Styles'
 import { isArray, isString, isValid, isNumber, isBoolean, isFunction, merge } from './common/utils/typeChecks'
 import { createId } from './common/utils/id'
@@ -36,7 +37,7 @@ import { type LoadDataCallback, type LoadDataParams, LoadDataType } from './comm
 import type TimeWeightTick from './common/TimeWeightTick'
 import { classifyTimeWeightTicks, createTimeWeightTickList } from './common/TimeWeightTick'
 
-import type { Options, CustomApi, ThousandsSeparator, DecimalFold } from './Options'
+import type { Options, CustomApi, ThousandsSeparator, DecimalFold, FormatDateType, FormatDateParams, FormatBigNumber } from './Options'
 
 import { IndicatorDataState, type IndicatorOverride, type IndicatorCreate, type IndicatorFilter, type Indicator } from './component/Indicator'
 import type IndicatorImp from './component/Indicator'
@@ -52,7 +53,6 @@ import { getStyles as getExtensionStyles } from './extension/styles/index'
 import { PaneIdConstants } from './pane/types'
 
 import type Chart from './Chart'
-import type PickRequired from './common/PickRequired'
 
 const BarSpaceLimitConstants = {
   MIN: 1,
@@ -150,10 +150,23 @@ export default class StoreImp implements Store {
    * Custom api
    */
   private readonly _customApi = {
-    formatDate: (timestamp: number, format: string) => formatTimestampToString(this._dateTimeFormat, timestamp, format),
+    formatDate: ({
+      dateTimeFormat,
+      timestamp,
+      template
+    }: FormatDateParams) => formatTimestampByTemplate(dateTimeFormat, timestamp, template),
     formatBigNumber
   }
 
+  /**
+   * Inner custom api
+   * @description Internal use only
+   */
+  private readonly _innerCustomApi = {
+    formatDate: (timestamp: number, template: string, type: FormatDateType) => this._customApi.formatDate({ dateTimeFormat: this._dateTimeFormat, timestamp, template, type }),
+    formatBigNumber: this._customApi.formatBigNumber
+  }
+
   /**
    * Locale
    */
@@ -397,6 +410,13 @@ export default class StoreImp implements Store {
 
   getCustomApi (): CustomApi { return this._customApi }
 
+  getInnerCustomApi (): {
+    formatDate: (timestamp: number, template: string, type: FormatDateType) => string
+    formatBigNumber: FormatBigNumber
+    } {
+    return this._innerCustomApi
+  }
+
   setLocale (locale: string): void { this._locale = locale }
 
   getLocale (): string { return this._locale }
diff --git a/src/common/utils/format.ts b/src/common/utils/format.ts
@@ -91,10 +91,10 @@ export function formatTimestampToDateTime (dateTimeFormat: Intl.DateTimeFormat,
   return date as unknown as DateTime
 }
 
-export function formatTimestampToString (dateTimeFormat: Intl.DateTimeFormat, timestamp: number, format: string): string {
+export function formatTimestampByTemplate (dateTimeFormat: Intl.DateTimeFormat, timestamp: number, template: string): string {
   const date = formatTimestampToDateTime(dateTimeFormat, timestamp)
   // eslint-disable-next-line @typescript-eslint/no-unsafe-return -- ignore
-  return format.replace(/YYYY|MM|DD|HH|mm|ss/g, key => date[key])
+  return template.replace(/YYYY|MM|DD|HH|mm|ss/g, key => date[key])
 }
 
 export function formatPrecision (value: string | number, precision?: number): string {
diff --git a/src/component/XAxis.ts b/src/component/XAxis.ts
@@ -76,7 +76,7 @@ export default abstract class XAxisImp extends AxisImp implements XAxis {
   protected override createTicksImp (): AxisTick[] {
     const { realFrom, realTo } = this.getRange()
     const chartStore = this.getParent().getChart().getChartStore()
-    const formatDate = chartStore.getCustomApi().formatDate
+    const formatDate = chartStore.getInnerCustomApi().formatDate
     const timeWeightTickList = chartStore.getTimeWeightTickList()
     const ticks: AxisTick[] = []
 
diff --git a/src/index.ts b/src/index.ts
@@ -39,9 +39,9 @@ import {
   formatValue,
   formatPrecision,
   formatBigNumber,
-  formatTimestampToString,
   formatThousands,
-  formatFoldDecimal
+  formatFoldDecimal,
+  formatTimestampByTemplate
 } from './common/utils/format'
 import { calcTextWidth } from './common/utils/canvas'
 import { ActionType } from './common/Action'
@@ -149,7 +149,7 @@ const utils = {
   formatValue,
   formatPrecision,
   formatBigNumber,
-  formatDate: formatTimestampToString,
+  formatDate: formatTimestampByTemplate,
   formatThousands,
   formatFoldDecimal,
   calcTextWidth,
diff --git a/src/view/CandleTooltipView.ts b/src/view/CandleTooltipView.ts
@@ -363,7 +363,7 @@ export default class CandleTooltipView extends IndicatorTooltipView {
     const chartStore = this.getWidget().getPane().getChart().getChartStore()
     const styles = chartStore.getStyles().candle
     const dataList = chartStore.getDataList()
-    const customApi = chartStore.getCustomApi()
+    const customApi = chartStore.getInnerCustomApi()
     const decimalFold = chartStore.getDecimalFold()
     const thousandsSeparator = chartStore.getThousandsSeparator()
     const locale = chartStore.getLocale()
diff --git a/src/view/CrosshairVerticalLabelView.ts b/src/view/CrosshairVerticalLabelView.ts
@@ -38,7 +38,7 @@ export default class CrosshairVerticalLabelView extends CrosshairHorizontalLabel
 
   override getText (crosshair: Crosshair, chartStore: ChartStore): string {
     const timestamp = crosshair.timestamp!
-    return chartStore.getCustomApi().formatDate(timestamp, 'YYYY-MM-DD HH:mm', FormatDateType.Crosshair)
+    return chartStore.getInnerCustomApi().formatDate(timestamp, 'YYYY-MM-DD HH:mm', FormatDateType.Crosshair)
   }
 
   override getTextAttrs (text: string, textWidth: number, crosshair: Crosshair, bounding: Bounding, _axis: Axis, styles: StateTextStyle): TextAttrs {
diff --git a/src/view/OverlayXAxisView.ts b/src/view/OverlayXAxisView.ts
@@ -60,7 +60,7 @@ export default class OverlayXAxisView extends OverlayYAxisView<XAxis> {
         rightX = Math.max(rightX, coordinate.x)
         const point = overlay.points[index]
         if (isNumber(point.timestamp)) {
-          const text = chartStore.getCustomApi().formatDate(point.timestamp, 'YYYY-MM-DD HH:mm', FormatDateType.Crosshair)
+          const text = chartStore.getInnerCustomApi().formatDate(point.timestamp, 'YYYY-MM-DD HH:mm', FormatDateType.Crosshair)
           figures.push({ type: 'text', attrs: { x: coordinate.x, y: 0, text, align: 'center' }, ignoreEvent: true })
         }
       })

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,12 @@`
`1`	`1`	```typescript
`2`	`2`	`(`
`3`	`3`	`customApi: {`
`4`		`- formatDate?: (timestamp: number, format: string, type: number) => string`
	`4`	`+ formatDate?: (params: {`
	`5`	`+ dateTimeFormat: Intl.DateTimeFormat`
	`6`	`+ timestamp: number`
	`7`	`+ template: string`
	`8`	`+ type: 'tooltip' \| 'crosshair' \| 'xAxis'`
	`9`	`+ }) => string`
`5`	`10`	`formatBigNumber?: (value: string \| number) => string`
`6`	`11`	`}`
`7`	`12`	`) => void`
Original file line number	Diff line number	Diff line change
`@@ -1,33 +1,31 @@`
`1`		`-import { init } from 'klinecharts';`
	`1`	`+import { init, utils } from 'klinecharts'`
`2`	`2`
`3`	`3`	`const chart = init(`
`4`	`4`	`'init-formatDate-chart',`
`5`	`5`	`{`
`6`	`6`	`customApi: {`
`7`		`- formatDate: (timestamp, _, type) => {`
`8`		`- const date = new Date(timestamp)`
`9`		`- const year = date.getFullYear()`
`10`		- const month = `${date.getMonth() + 1}`.padStart(2, '0')
`11`		- const day = `${date.getDate()}`.padStart(2, '0')
`12`		- const hour = `${date.getHours()}`.padStart(2, '0')
`13`		- const minute = `${date.getMinutes()}`.padStart(2, '0')
	`7`	`+ formatDate: ({`
	`8`	`+ dateTimeFormat,`
	`9`	`+ timestamp,`
	`10`	`+ type`
	`11`	`+ }) => {`
`14`	`12`	`switch (type) {`
`15`		`- case 0: {`
`16`		- return `${year}-${month}-${day} ${hour}:${minute}`
	`13`	`+ case 'tooltip': {`
	`14`	`+ return utils.formatDate(dateTimeFormat, timestamp, 'YYYY-MM-DD HH:mm')`
`17`	`15`	`}`
`18`		`- case 1: {`
`19`		- return `${year}-${month}-${day}`
	`16`	`+ case 'crosshair': {`
	`17`	`+ return utils.formatDate(dateTimeFormat, timestamp, 'YYYY-MM-DD')`
`20`	`18`	`}`
`21`		`- case 2: {`
`22`		- return `${month}-${day}`
	`19`	`+ case 'xAxis': {`
	`20`	`+ return utils.formatDate(dateTimeFormat, timestamp, 'MM-DD')`
`23`	`21`	`}`
`24`	`22`	`}`
`25`		- return `${month}-${day} ${hour}-${minute}`
	`23`	`+ return utils.formatDate(dateTimeFormat, timestamp, 'MM-DD HH:mm')`
`26`	`24`	`}`
`27`	`25`	`}`
`28`	`26`	`}`
`29`	`27`	`)`
`30`	`28`
`31`	`29`	`fetch('https://klinecharts.com/datas/kline.json')`
`32`	`30`	`.then(res => res.json())`
`33`		`- .then(dataList => { chart.applyNewData(dataList); });`
	`31`	`+ .then(dataList => { chart.applyNewData(dataList) })`
Original file line number	Diff line number	Diff line change
`@@ -91,10 +91,10 @@ export function formatTimestampToDateTime (dateTimeFormat: Intl.DateTimeFormat,`
`91`	`91`	`return date as unknown as DateTime`
`92`	`92`	`}`
`93`	`93`
`94`		`-export function formatTimestampToString (dateTimeFormat: Intl.DateTimeFormat, timestamp: number, format: string): string {`
	`94`	`+export function formatTimestampByTemplate (dateTimeFormat: Intl.DateTimeFormat, timestamp: number, template: string): string {`
`95`	`95`	`const date = formatTimestampToDateTime(dateTimeFormat, timestamp)`
`96`	`96`	`// eslint-disable-next-line @typescript-eslint/no-unsafe-return -- ignore`
`97`		`- return format.replace(/YYYY\|MM\|DD\|HH\|mm\|ss/g, key => date[key])`
	`97`	`+ return template.replace(/YYYY\|MM\|DD\|HH\|mm\|ss/g, key => date[key])`
`98`	`98`	`}`
`99`	`99`
`100`	`100`	`export function formatPrecision (value: string \| number, precision?: number): string {`