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

opt: opt `customApi.formatDate`

Author: liihuu

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?: {

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

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) })

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) })

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
 

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 }

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 {

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[] = []
 

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,

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()

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 {

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 })
         }
       })