waveform-analysis 0.1.28 → 0.1.30

package/src/components/rendering/WaveformTrackAxes.vue

@@ -3,7 +3,7 @@ import { axisBottom, axisLeft, axisRight, select } from 'd3'
 import { nextTick, onMounted, ref, watch } from 'vue'
 
 import type { WaveformAxesOptions } from '../../types'
-import { formatAxisTime, formatScientificAxisLabel } from '../../utils'
+import { formatScientificAxisLabel, formatXAxisLabel } from '../../utils'
 import type { DisplaySeries, TrackLayout, WaveformYAxisLayout } from '../core/types'
 
 interface Props {
@@ -66,10 +66,12 @@ function renderAxes() {
     axisBottom(props.track.xScale)
       .tickValues(props.track.xAxisTickValues)
       .tickFormat((value) =>
-        formatAxisTime(
+        formatXAxisLabel(
           Number(value),
-          props.timeUnit,
           props.track.xScale.domain() as [number, number],
+          props.timeUnit,
+          'tick',
+          props.axes?.x?.labelFormatter,
         ),
       )
       .tickSize(-4)
@@ -93,6 +95,7 @@ watch(
     () => props.track.xAxisTickValues,
     () => props.track.yAxisTickValues,
     () => props.timeUnit,
+    () => props.axes?.x?.labelFormatter,
     () => props.axes?.x?.lineVisible,
     () => props.axes?.y?.lineVisible,
   ],

package/src/components/waveform.ts

@@ -12,6 +12,7 @@ export type {
   WaveformAnnotationStyle,
   WaveformAnnotation,
   WaveformRenderingOptions,
+  WaveformPlotMargin,
   WaveformTitleTextStyle,
   WaveformTitleOptions,
   WaveformFrameStyle,

package/src/components/waveformChartCases/frameGridAndFormatting.test.ts

@@ -1,7 +1,8 @@
 import { flushPromises } from '@vue/test-utils'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 
 import { flushAnimationFrames } from '../../test/setup'
+import type { WaveformXAxisLabelFormatter } from '../../types'
 import { type WaveformData } from '../waveform'
 
 import { gridSeries, mountSizedChart } from '../../test/waveformChart'
@@ -162,7 +163,7 @@ describe('WaveformChart', () => {
     expect(wrapper.get('.waveform-chart__axis-endpoint--end').attributes('x')).toBe(
       String(trackWidth),
     )
-    expect(wrapper.get('.waveform-chart__axis-endpoint--end').text()).toBe('4990')
+    expect(wrapper.get('.waveform-chart__axis-endpoint--end').text()).toBe('4990.3')
     expect(wrapper.find('.waveform-chart__axis-exponent--x').exists()).toBe(false)
   })
 
@@ -267,6 +268,70 @@ describe('WaveformChart', () => {
     expect(endpointGroup.attributes('font-size')).toBe(xAxis.attributes('font-size'))
   })
 
+  it('formats X-axis ticks and endpoints with display-unit values and source context', async () => {
+    const data: WaveformData = {
+      kind: 'points',
+      points: [
+        { x: 0.125, y: 0 },
+        { x: 1.875, y: 1 },
+      ],
+    }
+    const originalPoints = data.points.map((point) => ({ ...point }))
+    const labelFormatter: WaveformXAxisLabelFormatter = (value, context) =>
+      `${context.kind}:${value / 10}`
+    const formatter = vi.fn(labelFormatter)
+    const wrapper = await mountSizedChart(data, {
+      timeUnit: 'ms',
+      axes: { x: { labelFormatter: formatter } },
+    })
+
+    expect(wrapper.get('.waveform-chart__axis-endpoint--start').text()).toBe('start:12.5')
+    expect(wrapper.get('.waveform-chart__axis-endpoint--end').text()).toBe('end:187.5')
+    expect(
+      wrapper
+        .get('.waveform-chart__axis--x')
+        .findAll('.tick text')
+        .every((tick) => tick.text().startsWith('tick:')),
+    ).toBe(true)
+
+    const startCall = formatter.mock.calls.find(([, context]) => context.kind === 'start')
+    const tickCall = formatter.mock.calls.find(([, context]) => context.kind === 'tick')
+    const endCall = formatter.mock.calls.find(([, context]) => context.kind === 'end')
+    expect(startCall).toEqual([
+      125,
+      {
+        kind: 'start',
+        rawValue: 0.125,
+        timeUnit: 'ms',
+        domain: [0.125, 1.875],
+        displayDomain: [125, 1875],
+      },
+    ])
+    expect(tickCall?.[0]).toBeTypeOf('number')
+    expect(tickCall?.[1]).toMatchObject({
+      kind: 'tick',
+      timeUnit: 'ms',
+      domain: [0.125, 1.875],
+      displayDomain: [125, 1875],
+    })
+    expect(endCall?.[1]).toMatchObject({ kind: 'end', rawValue: 1.875 })
+    expect(data.points).toEqual(originalPoints)
+
+    await wrapper.setProps({
+      axes: { x: { labelFormatter: (value: number) => `updated:${value}` } },
+    })
+    await flushPromises()
+    expect(wrapper.get('.waveform-chart__axis-endpoint--start').text()).toBe('updated:125')
+    expect(wrapper.get('.waveform-chart__axis-endpoint--end').text()).toBe('updated:1875')
+    expect(
+      wrapper
+        .get('.waveform-chart__axis--x')
+        .findAll('.tick text')
+        .every((tick) => tick.text().startsWith('updated:')),
+    ).toBe(true)
+    expect(data.points).toEqual(originalPoints)
+  })
+
   it('keeps zoom-change domains in source seconds', async () => {
     const wrapper = await mountSizedChart({
       kind: 'points',
@@ -307,6 +372,8 @@ describe('WaveformChart', () => {
     )
     expect(wrapper.get('.waveform-chart__axis-endpoint--start').text()).not.toBe(initialStart)
     expect(wrapper.get('.waveform-chart__axis-endpoint--end').text()).not.toBe(initialEnd)
-    expect(wrapper.get('.waveform-chart__axis-endpoint--start').text()).toMatch(/^-?\d+$/)
+    expect(
+      Number.isFinite(Number(wrapper.get('.waveform-chart__axis-endpoint--start').text())),
+    ).toBe(true)
   })
 })

package/src/components/waveformChartCases/sizingAndTitles.test.ts

@@ -105,6 +105,65 @@ describe('WaveformChart', () => {
     expect(wrapper.get('.waveform-chart__svg').attributes('height')).toBe('300')
   })
 
+  it('configures plot top and bottom margins and reacts to updates', async () => {
+    const wrapper = await mountSizedChart(
+      { kind: 'samples', values: [0, 1], sampleRate: 1 },
+      {
+        displayMode: 'compact',
+        grid: { rowCount: 1, columnCount: 1 },
+        plotMargin: { top: 30, bottom: 70 },
+      },
+    )
+
+    expect(wrapper.attributes('data-plot-margin-top')).toBe('30')
+    expect(wrapper.attributes('data-plot-margin-bottom')).toBe('70')
+    expect(wrapper.get('.waveform-chart__overlay').attributes('height')).toBe('260')
+    expect(wrapper.get('.waveform-chart__svg > g').attributes('transform')).toContain(', 30)')
+
+    await wrapper.setProps({ plotMargin: { top: 12 } })
+
+    expect(wrapper.attributes('data-plot-margin-top')).toBe('12')
+    expect(wrapper.attributes('data-plot-margin-bottom')).toBe('52')
+    expect(wrapper.get('.waveform-chart__overlay').attributes('height')).toBe('296')
+  })
+
+  it('falls back to default plot margins for invalid values', async () => {
+    const wrapper = await mountSizedChart(
+      { kind: 'samples', values: [0, 1], sampleRate: 1 },
+      {
+        displayMode: 'compact',
+        grid: { rowCount: 1, columnCount: 1 },
+        plotMargin: { top: -1, bottom: Number.NaN },
+      },
+    )
+
+    expect(wrapper.attributes('data-plot-margin-top')).toBe('18')
+    expect(wrapper.attributes('data-plot-margin-bottom')).toBe('52')
+    expect(wrapper.get('.waveform-chart__overlay').attributes('height')).toBe('290')
+  })
+
+  it('keeps the chart title and X-axis title fixed when plot margins change', async () => {
+    const wrapper = await mountSizedChart(
+      { kind: 'samples', values: [0, 1], sampleRate: 1 },
+      {
+        displayMode: 'compact',
+        grid: { rowCount: 1, columnCount: 1 },
+        title: { text: '固定标题' },
+      },
+    )
+    const titleAreaStyle = wrapper.get('.waveform-chart__title-area').attributes('style')
+    const xAxisTitle = wrapper.get('.waveform-chart__x-label')
+    const initialX = xAxisTitle.attributes('x')
+    const initialY = xAxisTitle.attributes('y')
+
+    await wrapper.setProps({ plotMargin: { top: 60, bottom: 90 } })
+
+    expect(wrapper.get('.waveform-chart__title-area').attributes('style')).toBe(titleAreaStyle)
+    expect(wrapper.get('.waveform-chart__x-label').attributes('x')).toBe(initialX)
+    expect(wrapper.get('.waveform-chart__x-label').attributes('y')).toBe(initialY)
+    expect(wrapper.get('.waveform-chart__svg > g').attributes('transform')).toContain(', 60)')
+  })
+
   it('does not render or reserve space for missing, hidden, or blank titles', async () => {
     for (const title of [undefined, { visible: false, text: '隐藏标题' }, { text: '   ' }]) {
       const wrapper = await mountSizedChart(

package/src/demo/DemoChartHost.vue

@@ -45,6 +45,7 @@ defineExpose({ resetViewport })
       :clean-view="model.cleanView"
       :presentation-mode="model.presentationMode"
       :show-tooltip="model.showTooltip"
+      :plot-margin="model.plotMargin"
       :zero-line="model.zeroLine"
       :frame-number="model.frameWatermarkVisible ? 1 : undefined"
       :annotations-visible="model.annotationsVisible"

package/src/demo/DemoGridFrameControls.vue

@@ -8,6 +8,35 @@ const model = defineModel<DemoControlPanelModel>('model', { required: true })
 </script>
 
 <template>
+  <section class="control-section">
+    <h2>绘图区边距</h2>
+    <div class="plot-margin-controls">
+      <label class="frame-style-control">
+        <span>上边距</span>
+        <InputNumber
+          v-model:value="model.plotMarginTop"
+          :min="0"
+          :max="300"
+          :step="1"
+          addon-after="px"
+          size="small"
+          aria-label="绘图区上边距"
+        />
+      </label>
+      <label class="frame-style-control">
+        <span>下边距</span>
+        <InputNumber
+          v-model:value="model.plotMarginBottom"
+          :min="0"
+          :max="300"
+          :step="1"
+          addon-after="px"
+          size="small"
+          aria-label="绘图区下边距"
+        />
+      </label>
+    </div>
+  </section>
   <section class="control-section">
     <div class="control-section__header">
       <h2>零值参考线</h2>
@@ -96,6 +125,76 @@ const model = defineModel<DemoControlPanelModel>('model', { required: true })
         <Switch v-model:checked="model.yAxisLineVisible" size="small" aria-label="显示纵轴线" />
       </div>
     </div>
+    <div class="x-axis-label-controls">
+      <label class="frame-style-control frame-style-control--switch">
+        <span>自定义 Label</span>
+        <Switch
+          v-model:checked="model.xAxisLabelFormatterEnabled"
+          size="small"
+          aria-label="自定义 X 轴 Label"
+        />
+      </label>
+      <label v-if="model.xAxisLabelFormatterEnabled" class="frame-style-control">
+        <span>格式类型</span>
+        <Select
+          v-model:value="model.xAxisLabelFormat"
+          :options="model.xAxisLabelFormatOptions"
+          size="small"
+          aria-label="X 轴 Label 格式类型"
+        />
+      </label>
+      <label
+        v-if="model.xAxisLabelFormatterEnabled && model.xAxisLabelFormat === 'number'"
+        class="frame-style-control"
+      >
+        <span>运算倍率</span>
+        <InputNumber
+          v-model:value="model.xAxisLabelMultiplier"
+          :min="-1000000"
+          :max="1000000"
+          :step="0.1"
+          size="small"
+          aria-label="X 轴 Label 运算倍率"
+        />
+      </label>
+      <label
+        v-if="model.xAxisLabelFormatterEnabled && model.xAxisLabelFormat === 'number'"
+        class="frame-style-control"
+      >
+        <span>小数位数</span>
+        <InputNumber
+          v-model:value="model.xAxisLabelFractionDigits"
+          :min="0"
+          :max="12"
+          :step="1"
+          size="small"
+          aria-label="X 轴 Label 小数位数"
+        />
+      </label>
+      <label
+        v-if="model.xAxisLabelFormatterEnabled && model.xAxisLabelFormat === 'datetime'"
+        class="frame-style-control"
+      >
+        <span>时区</span>
+        <Select
+          v-model:value="model.xAxisLabelTimeZone"
+          :options="model.xAxisLabelTimeZoneOptions"
+          size="small"
+          aria-label="X 轴 Label 时区"
+        />
+      </label>
+      <label
+        v-if="model.xAxisLabelFormatterEnabled && model.xAxisLabelFormat === 'datetime'"
+        class="frame-style-control frame-style-control--switch"
+      >
+        <span>显示毫秒</span>
+        <Switch
+          v-model:checked="model.xAxisLabelShowMilliseconds"
+          size="small"
+          aria-label="X 轴 Label 显示毫秒"
+        />
+      </label>
+    </div>
   </section>
   <section class="control-section">
     <h2>图框样式</h2>

package/src/demo/plotMarginControls.test.ts

@@ -0,0 +1,29 @@
+import { flushPromises, mount } from '@vue/test-utils'
+import { InputNumber } from 'ant-design-vue'
+import { describe, expect, it } from 'vitest'
+
+import App from '../App.vue'
+import { WaveformChart } from '../components'
+
+describe('plot margin demo controls', () => {
+  it('updates the chart top and bottom margins from the sidebar', async () => {
+    const wrapper = mount(App)
+    await flushPromises()
+    const chart = wrapper.getComponent(WaveformChart)
+    const controls = wrapper.get('.plot-margin-controls').findAllComponents(InputNumber)
+
+    expect(controls).toHaveLength(2)
+    expect(controls[0]?.props('value')).toBe(18)
+    expect(controls[1]?.props('value')).toBe(52)
+    expect(chart.props('plotMargin')).toEqual({ top: 18, bottom: 52 })
+
+    controls[0]?.vm.$emit('update:value', 30)
+    controls[1]?.vm.$emit('update:value', 70)
+    await flushPromises()
+
+    expect(chart.props('plotMargin')).toEqual({ top: 30, bottom: 70 })
+    expect(wrapper.get('.waveform-chart').attributes('data-plot-margin-top')).toBe('30')
+    expect(wrapper.get('.waveform-chart').attributes('data-plot-margin-bottom')).toBe('70')
+    wrapper.unmount()
+  })
+})

package/src/demo/types.ts

@@ -10,10 +10,12 @@ import type {
   WaveformLegendPosition,
   WaveformLineStyle,
   WaveformOverlayMode,
+  WaveformPlotMargin,
   WaveformTitleOptions,
   WaveformZeroLineOptions,
   WaveformZoomEndPayload,
 } from '../components'
+import type { DemoXAxisLabelFormat, DemoXAxisLabelTimeZone } from './useDemoXAxisLabelControls'
 
 interface SelectOption<T> {
   label: string
@@ -25,6 +27,8 @@ export interface DemoControlPanelModel {
   displayMode: WaveformDisplayMode
   overlayMode: WaveformOverlayMode
   showTooltip: boolean
+  plotMarginTop: number
+  plotMarginBottom: number
   cleanView: boolean
   presentationMode: boolean
   selectedSeriesId: string
@@ -44,6 +48,14 @@ export interface DemoControlPanelModel {
   verticalGridColor: string
   xAxisLineVisible: boolean
   yAxisLineVisible: boolean
+  xAxisLabelFormatterEnabled: boolean
+  xAxisLabelFormat: DemoXAxisLabelFormat
+  xAxisLabelFormatOptions: Array<SelectOption<DemoXAxisLabelFormat>>
+  xAxisLabelMultiplier: number
+  xAxisLabelFractionDigits: number
+  xAxisLabelTimeZone: DemoXAxisLabelTimeZone
+  xAxisLabelTimeZoneOptions: Array<SelectOption<DemoXAxisLabelTimeZone>>
+  xAxisLabelShowMilliseconds: boolean
   frameBorderColor: string
   frameBackgroundColor: string
   frameBorderWidth: number
@@ -90,6 +102,7 @@ export interface DemoChartModel {
   cleanView: boolean
   presentationMode: boolean
   showTooltip: boolean
+  plotMargin: WaveformPlotMargin
   zeroLine: WaveformZeroLineOptions
   frameWatermarkVisible: boolean
   annotations: WaveformAnnotation[]

package/src/demo/useDemoXAxisLabelControls.ts

@@ -0,0 +1,77 @@
+import { computed, ref } from 'vue'
+
+import type { WaveformXAxisLabelFormatter } from '../types'
+
+export type DemoXAxisLabelFormat = 'number' | 'datetime'
+export type DemoXAxisLabelTimeZone = 'local' | 'Asia/Shanghai' | 'UTC'
+
+const formatOptions = [
+  { label: '数值', value: 'number' as const },
+  { label: '固定时间', value: 'datetime' as const },
+]
+const timeZoneOptions = [
+  { label: '中国标准时间', value: 'Asia/Shanghai' as const },
+  { label: '本地时区', value: 'local' as const },
+  { label: 'UTC', value: 'UTC' as const },
+]
+
+function pad(value: number, length = 2): string {
+  return String(value).padStart(length, '0')
+}
+
+export function formatDemoTimestamp(
+  value: number,
+  timeZone: DemoXAxisLabelTimeZone,
+  showMilliseconds: boolean,
+): string {
+  const offset = timeZone === 'Asia/Shanghai' ? 8 * 60 * 60 * 1000 : 0
+  const date = new Date(value + offset)
+  if (!Number.isFinite(date.getTime())) return String(value)
+
+  const useUtcFields = timeZone !== 'local'
+  const year = useUtcFields ? date.getUTCFullYear() : date.getFullYear()
+  const month = (useUtcFields ? date.getUTCMonth() : date.getMonth()) + 1
+  const day = useUtcFields ? date.getUTCDate() : date.getDate()
+  const hours = useUtcFields ? date.getUTCHours() : date.getHours()
+  const minutes = useUtcFields ? date.getUTCMinutes() : date.getMinutes()
+  const seconds = useUtcFields ? date.getUTCSeconds() : date.getSeconds()
+  const milliseconds = useUtcFields ? date.getUTCMilliseconds() : date.getMilliseconds()
+  const suffix = showMilliseconds ? `.${pad(milliseconds, 3)}` : ''
+  return `${year}-${pad(month)}-${pad(day)} ${pad(hours)}:${pad(minutes)}:${pad(seconds)}${suffix}`
+}
+
+export function useDemoXAxisLabelControls() {
+  const xAxisLabelFormatterEnabled = ref(false)
+  const xAxisLabelFormat = ref<DemoXAxisLabelFormat>('number')
+  const xAxisLabelMultiplier = ref(1)
+  const xAxisLabelFractionDigits = ref(3)
+  const xAxisLabelTimeZone = ref<DemoXAxisLabelTimeZone>('Asia/Shanghai')
+  const xAxisLabelShowMilliseconds = ref(false)
+  const xAxisLabelFormatter = computed<WaveformXAxisLabelFormatter | undefined>(() => {
+    if (!xAxisLabelFormatterEnabled.value) return undefined
+    if (xAxisLabelFormat.value === 'datetime') {
+      return (value) =>
+        formatDemoTimestamp(value, xAxisLabelTimeZone.value, xAxisLabelShowMilliseconds.value)
+    }
+
+    const multiplier = Number.isFinite(xAxisLabelMultiplier.value) ? xAxisLabelMultiplier.value : 1
+    const fractionDigits = Number.isFinite(xAxisLabelFractionDigits.value)
+      ? Math.min(12, Math.max(0, Math.trunc(xAxisLabelFractionDigits.value)))
+      : 0
+    return (value) => (value * multiplier).toFixed(fractionDigits)
+  })
+
+  return {
+    controlModel: {
+      xAxisLabelFormatterEnabled,
+      xAxisLabelFormat,
+      xAxisLabelFormatOptions: formatOptions,
+      xAxisLabelMultiplier,
+      xAxisLabelFractionDigits,
+      xAxisLabelTimeZone,
+      xAxisLabelTimeZoneOptions: timeZoneOptions,
+      xAxisLabelShowMilliseconds,
+    },
+    xAxisLabelFormatter,
+  }
+}

package/src/demo/xAxisLabelControls.test.ts

@@ -0,0 +1,86 @@
+import { flushPromises, mount } from '@vue/test-utils'
+import { InputNumber, Select } from 'ant-design-vue'
+import { describe, expect, it } from 'vitest'
+
+import App from '../App.vue'
+import { WaveformChart } from '../components'
+import { formatDemoTimestamp } from './useDemoXAxisLabelControls'
+
+describe('X-axis label demo controls', () => {
+  it('formats timestamps in fixed UTC and China-standard-time formats', () => {
+    expect(formatDemoTimestamp(0, 'UTC', false)).toBe('1970-01-01 00:00:00')
+    expect(formatDemoTimestamp(123, 'UTC', true)).toBe('1970-01-01 00:00:00.123')
+    expect(formatDemoTimestamp(0, 'Asia/Shanghai', false)).toBe('1970-01-01 08:00:00')
+    expect(formatDemoTimestamp(Number.NaN, 'UTC', false)).toBe('NaN')
+  })
+
+  it('configures numeric and timestamp labels from the sidebar', async () => {
+    const wrapper = mount(App)
+    await flushPromises()
+    const chart = wrapper.getComponent(WaveformChart)
+
+    expect(chart.props('axes')).toEqual({
+      x: { lineVisible: false },
+      y: { lineVisible: false },
+    })
+    expect(wrapper.find('[aria-label="自定义 X 轴 Label"]').exists()).toBe(true)
+    expect(wrapper.find('[aria-label="X 轴 Label 运算倍率"]').exists()).toBe(false)
+    expect(wrapper.find('[aria-label="X 轴 Label 小数位数"]').exists()).toBe(false)
+    expect(wrapper.find('[aria-label="X 轴 Label 格式类型"]').exists()).toBe(false)
+
+    await wrapper.get('[aria-label="自定义 X 轴 Label"]').trigger('click')
+    await flushPromises()
+    const inputNumbers = wrapper.findAllComponents(InputNumber)
+    const multiplierInput = inputNumbers.find((input) =>
+      input.find('[aria-label="X 轴 Label 运算倍率"]').exists(),
+    )
+    const fractionDigitsInput = inputNumbers.find((input) =>
+      input.find('[aria-label="X 轴 Label 小数位数"]').exists(),
+    )
+    expect(multiplierInput).toBeDefined()
+    expect(fractionDigitsInput).toBeDefined()
+    expect(multiplierInput?.props('value')).toBe(1)
+    expect(fractionDigitsInput?.props('value')).toBe(3)
+    expect(wrapper.get('.waveform-chart__axis-endpoint--start').text()).toMatch(/\.000$/)
+
+    multiplierInput?.vm.$emit('update:value', 2)
+    fractionDigitsInput?.vm.$emit('update:value', 2)
+    await flushPromises()
+    const formatter = chart.props('axes')?.x?.labelFormatter
+    expect(formatter).toBeTypeOf('function')
+    expect(formatter?.(1.234, {} as never)).toBe('2.47')
+    expect(wrapper.get('.waveform-chart__axis-endpoint--start').text()).toMatch(/\.00$/)
+
+    const formatSelect = wrapper
+      .findAllComponents(Select)
+      .find((select) => select.find('[aria-label="X 轴 Label 格式类型"]').exists())
+    expect(formatSelect?.props('value')).toBe('number')
+    formatSelect?.vm.$emit('update:value', 'datetime')
+    await flushPromises()
+    expect(wrapper.find('[aria-label="X 轴 Label 运算倍率"]').exists()).toBe(false)
+    expect(wrapper.find('[aria-label="X 轴 Label 小数位数"]').exists()).toBe(false)
+    expect(wrapper.find('[aria-label="X 轴 Label 时区"]').exists()).toBe(true)
+    expect(wrapper.find('[aria-label="X 轴 Label 显示毫秒"]').exists()).toBe(true)
+    expect(chart.props('axes')?.x?.labelFormatter?.(0, {} as never)).toBe('1970-01-01 08:00:00')
+
+    await wrapper.get('[aria-label="X 轴 Label 显示毫秒"]').trigger('click')
+    await flushPromises()
+    expect(chart.props('axes')?.x?.labelFormatter?.(123, {} as never)).toBe(
+      '1970-01-01 08:00:00.123',
+    )
+    const timeZoneSelect = wrapper
+      .findAllComponents(Select)
+      .find((select) => select.find('[aria-label="X 轴 Label 时区"]').exists())
+    timeZoneSelect?.vm.$emit('update:value', 'UTC')
+    await flushPromises()
+    expect(chart.props('axes')?.x?.labelFormatter?.(123, {} as never)).toBe(
+      '1970-01-01 00:00:00.123',
+    )
+
+    await wrapper.get('[aria-label="自定义 X 轴 Label"]').trigger('click')
+    await flushPromises()
+    expect(chart.props('axes')?.x?.labelFormatter).toBeUndefined()
+    expect(wrapper.find('[aria-label="X 轴 Label 运算倍率"]').exists()).toBe(false)
+    wrapper.unmount()
+  })
+})

package/src/index.ts

@@ -17,12 +17,16 @@ export type {
   WaveformAnnotationStyle,
   WaveformAnnotation,
   WaveformRenderingOptions,
+  WaveformPlotMargin,
   WaveformTitleTextStyle,
   WaveformTitleOptions,
   WaveformLegendPosition,
   WaveformLegendOrientation,
   WaveformLegendOptions,
   WaveformFrameStyle,
+  WaveformXAxisLabelKind,
+  WaveformXAxisLabelFormatterContext,
+  WaveformXAxisLabelFormatter,
   WaveformAxesOptions,
   WaveformZeroLineOptions,
   // 数据类型

package/src/styles.css

@@ -133,6 +133,14 @@ body {
   grid-template-columns: minmax(0, 1fr) auto;
 }
 
+.x-axis-label-controls {
+  display: grid;
+  gap: 10px;
+  margin-top: 12px;
+  padding-top: 12px;
+  border-top: 1px solid #eaecf0;
+}
+
 .grid-line-color-picker,
 .grid-line-color-picker .vc-color-wrap {
   width: 48px;
@@ -187,6 +195,7 @@ body {
 }
 
 .frame-style-controls,
+.plot-margin-controls,
 .auxiliary-style-controls {
   display: grid;
   gap: 10px;

package/src/types/chart.ts

@@ -74,6 +74,14 @@ export interface WaveformRenderingOptions {
   errorBarMinSpacing?: number
 }
 
+/** Pixel margins reserved above and below the waveform plotting area. */
+export interface WaveformPlotMargin {
+  /** Space between the top of the drawing SVG and the plotting area. Defaults to 18. */
+  top?: number
+  /** Space between the plotting area and the bottom of the drawing SVG. Defaults to 52. */
+  bottom?: number
+}
+
 /** Text styling for the chart-level title. */
 export interface WaveformTitleTextStyle {
   color?: string
@@ -121,10 +129,31 @@ export interface WaveformFrameStyle {
   backgroundColor?: string
 }
 
+export type WaveformXAxisLabelKind = 'tick' | 'start' | 'end'
+
+/** Context passed to custom X-axis label formatters. */
+export interface WaveformXAxisLabelFormatterContext {
+  kind: WaveformXAxisLabelKind
+  /** X coordinate in the source data, before time-unit conversion. */
+  rawValue: number
+  timeUnit: 's' | 'ms'
+  /** Current visible X domain in source coordinates. */
+  domain: [number, number]
+  /** Current visible X domain converted to the selected display unit. */
+  displayDomain: [number, number]
+}
+
+export type WaveformXAxisLabelFormatter = (
+  value: number,
+  context: WaveformXAxisLabelFormatterContext,
+) => string
+
 /** Controls axis baseline visibility while preserving tick marks and axis text. */
 export interface WaveformAxesOptions {
   x?: {
     lineVisible?: boolean
+    /** Formats display-unit X values for ticks and visible-range endpoints. */
+    labelFormatter?: WaveformXAxisLabelFormatter
   }
   y?: {
     lineVisible?: boolean

package/src/types/index.ts

@@ -12,12 +12,16 @@ export type {
   WaveformAnnotationStyle,
   WaveformAnnotation,
   WaveformRenderingOptions,
+  WaveformPlotMargin,
   WaveformTitleTextStyle,
   WaveformTitleOptions,
   WaveformLegendPosition,
   WaveformLegendOrientation,
   WaveformLegendOptions,
   WaveformFrameStyle,
+  WaveformXAxisLabelKind,
+  WaveformXAxisLabelFormatterContext,
+  WaveformXAxisLabelFormatter,
   WaveformAxesOptions,
   WaveformZeroLineOptions,
 } from './chart'