---

title: 地址与日期工具 description: A1 地址转换、列宽转换、Excel 日期序列号与错误类型 sidebarOrder: 3 outline: deep

地址与日期工具

介绍

除读写能力外，@cat-kit/excel 还提供可独立使用的辅助函数：

• 地址工具：列名/索引与 A1 地址互转
• 尺寸工具：像素宽度与 Excel 列宽互转
• 日期工具：Date 与 Excel 序列号互转（含 1900/1904 系统）
• 错误类型：统一的 ExcelError 体系

快速使用

import {
  columnToIndex,
  formatCellAddress,
  pixelsToExcelWidth,
  dateToExcelSerial,
  excelSerialToDate
} from '@cat-kit/excel'

const col = columnToIndex('AA') // 27
const address = formatCellAddress(10, 3) // C10
const width = pixelsToExcelWidth(140) // 20

const serial = dateToExcelSerial(new Date('2026-03-03T00:00:00.000Z'), 1900)
const date = excelSerialToDate(serial, 1900)

console.log(col, address, width, date.toISOString())

vue

列号转换

列名

索引: 27

列索引

列名: AA

A1 地址转换

单元格地址

row=12, col=3

row col

地址: C12

日期序列号转换

日期时间 dateSystem 19001904

序列号: 46094.388194

反向测试序列号

ISO: 2023-03-15T00:00:00.000Z

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211

<template>
  <div class="tools-card">
    <div class="tools-grid">
      <section class="panel">
        <h4>列号转换</h4>
        <label>
          列名
          <input v-model.trim="columnLabel" placeholder="例如 AA" />
        </label>
        <div class="result" :class="columnLabelResult.ok ? 'ok' : 'error'">
          {{ columnLabelResult.ok ? `索引: ${columnLabelResult.value}` : columnLabelResult.error }}
        </div>

        <label>
          列索引
          <input v-model.number="columnIndex" type="number" min="1" max="16384" />
        </label>
        <div class="result" :class="columnIndexResult.ok ? 'ok' : 'error'">
          {{ columnIndexResult.ok ? `列名: ${columnIndexResult.value}` : columnIndexResult.error }}
        </div>
      </section>

      <section class="panel">
        <h4>A1 地址转换</h4>
        <label>
          单元格地址
          <input v-model.trim="addressText" placeholder="例如 C12" />
        </label>
        <div class="result" :class="addressResult.ok ? 'ok' : 'error'">
          {{
            addressResult.ok
              ? `row=${addressResult.value.row}, col=${addressResult.value.col}`
              : addressResult.error
          }}
        </div>

        <div class="inline-inputs">
          <label>
            row
            <input v-model.number="rowIndex" type="number" min="1" max="1048576" />
          </label>
          <label>
            col
            <input v-model.number="colIndex" type="number" min="1" max="16384" />
          </label>
        </div>
        <div class="result" :class="formatResult.ok ? 'ok' : 'error'">
          {{ formatResult.ok ? `地址: ${formatResult.value}` : formatResult.error }}
        </div>
      </section>

      <section class="panel panel-wide">
        <h4>日期序列号转换</h4>
        <div class="inline-inputs">
          <label>
            日期时间
            <input v-model="dateInput" type="datetime-local" />
          </label>
          <label>
            dateSystem
            <select v-model.number="dateSystem">
              <option :value="1900">1900</option>
              <option :value="1904">1904</option>
            </select>
          </label>
        </div>

        <div class="result" :class="serialResult.ok ? 'ok' : 'error'">
          {{ serialResult.ok ? `序列号: ${serialResult.value}` : serialResult.error }}
        </div>

        <label>
          反向测试序列号
          <input v-model.number="serialInput" type="number" step="0.001" />
        </label>
        <div class="result" :class="dateResult.ok ? 'ok' : 'error'">
          {{ dateResult.ok ? `ISO: ${dateResult.value}` : dateResult.error }}
        </div>
      </section>
    </div>
  </div>
</template>

<script lang="ts" setup>
import { computed, ref } from 'vue'
import {
  columnToIndex,
  indexToColumn,
  parseCellAddress,
  formatCellAddress,
  dateToExcelSerial,
  excelSerialToDate,
  type DateSystem
} from '@cat-kit/excel'

type Result<T> =
  | { ok: true; value: T }
  | { ok: false; error: string }

const columnLabel = ref('AA')
const columnIndex = ref(27)
const addressText = ref('C12')
const rowIndex = ref(12)
const colIndex = ref(3)

const now = new Date()
const defaultDate = new Date(now.getTime() - now.getTimezoneOffset() * 60_000)
const dateInput = ref(defaultDate.toISOString().slice(0, 16))
const dateSystem = ref<DateSystem>(1900)
const serialInput = ref(45000)

function capture<T>(fn: () => T): Result<T> {
  try {
    return { ok: true, value: fn() }
  } catch (error) {
    return {
      ok: false,
      error: error instanceof Error ? error.message : String(error)
    }
  }
}

const columnLabelResult = computed(() => capture(() => columnToIndex(columnLabel.value)))
const columnIndexResult = computed(() => capture(() => indexToColumn(columnIndex.value)))
const addressResult = computed(() => capture(() => parseCellAddress(addressText.value)))
const formatResult = computed(() => capture(() => formatCellAddress(rowIndex.value, colIndex.value)))

const serialResult = computed(() =>
  capture(() => {
    const date = new Date(dateInput.value)
    return dateToExcelSerial(date, dateSystem.value).toFixed(6)
  })
)

const dateResult = computed(() =>
  capture(() => excelSerialToDate(serialInput.value, dateSystem.value).toISOString())
)
</script>

<style scoped>
.tools-card {
  border: 1px solid var(--vp-c-divider);
  border-radius: 12px;
  padding: 16px;
  background: var(--vp-c-bg-soft);
}

.tools-grid {
  display: grid;
  gap: 10px;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
}

.panel {
  border: 1px solid var(--vp-c-divider);
  border-radius: 10px;
  padding: 12px;
  background: var(--vp-c-bg);
  display: grid;
  gap: 8px;
}

.panel-wide {
  grid-column: 1 / -1;
}

.panel h4 {
  margin: 0;
  font-size: 14px;
}

.panel label {
  display: grid;
  gap: 4px;
  color: var(--vp-c-text-2);
  font-size: 13px;
}

.panel input,
.panel select {
  border: 1px solid var(--vp-c-divider);
  border-radius: 8px;
  padding: 6px 8px;
  background: var(--vp-c-bg-soft);
  color: var(--vp-c-text-1);
}

.inline-inputs {
  display: grid;
  gap: 8px;
  grid-template-columns: repeat(auto-fit, minmax(120px, 1fr));
}

.result {
  border-radius: 8px;
  padding: 8px;
  font-size: 12px;
  word-break: break-word;
}

.result.ok {
  background: #e8f5e9;
  color: #1b5e20;
}

.result.error {
  background: #ffebee;
  color: #b71c1c;
}
</style>

API参考

地址相关

• columnToIndex(column: string): number
• indexToColumn(index: number): string
• parseCellAddress(address: string): { row: number; col: number }
• formatCellAddress(row: number, col: number): string
• pixelsToExcelWidth(pixels: number): number
• excelWidthToPixels(width: number): number

说明：

• 列/行均为 1-based，最大列 16384（XFD），最大行 1048576
• 参数非法时抛 ExcelValueError

日期相关

• dateToExcelSerial(date: Date, dateSystem?: 1900 | 1904): number
• excelSerialToDate(serial: number, dateSystem?: 1900 | 1904): Date

说明：

• 默认 dateSystem = 1900
• 已处理 Excel 1900 日期系统中的闰年历史兼容差异

错误类型

• ExcelError：基础错误类型，含 code 与可选 path
• ExcelParseError：解析阶段错误
• ExcelWriteError：写入阶段错误
• ExcelSchemaError：结构/约束错误（如重复工作表名）
• ExcelValueError：输入值或参数错误