DataItemDisplay 组件 / DataItemDisplay Component

轻量级 Vue 数据展示组件，支持数字格式化、最大占位宽度和多框架响应式核心。

A lightweight Vue data display component with number formatting, max placeholder width, and a framework-agnostic reactive core.

一、特性 Features

• 数字格式化：支持千分符、本地化格式、前缀/后缀、自定义小数位等。

• 最大字符占位：基于最宽字符静态计算容器宽度，避免动态拉伸。

• 响应式核心：核心逻辑使用 signal-polyfill，可适配 Vue、React 等环境。

• 多样式扩展：支持传入类名和行内样式，灵活定制外观。

• Number Formatting: Supports thousands separators, locale formatting, prefix/suffix, custom decimals.

• Max Placeholder Width: Calculates container width from max placeholder characters to avoid layout shifts.

• Reactive Core: Core logic uses signal-polyfill, adaptable to Vue, React, etc.

• Style Flexibility: Accepts CSS classes and inline styles for flexible styling.

二、安装 Installation

npm install data-item-display signal-polyfill
# or
pnpm add data-item-display signal-polyfill

三、使用示例 Usage Example

Vue 3 (推荐)

<template>
  <DataItemDisplay
    v-bind="{
      value,
      loading,
      decimals,
      extraDigits,
      prefix,
      suffix,
      unit,
      formatter,
      label,
      separator,
      wrapperClass,
      wrapperStyle,
      labelWrapperClass,
      labelWrapperStyle,
      labelClass,
      labelStyle,
      separatorClass,
      separatorStyle,
      valueClass,
      valueStyle,
      skeletonClass,
      skeletonStyle,
    }"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import 'signal-polyfill'                   // 引入信号 Polyfill
import DataItemDisplay from 'data-item-display/components/DataItemDisplay.vue'
import type { ClassType, StyleType } from 'data-item-display/core/types'

// 响应式数据
const value = ref(12345.678)
const loading = ref(false)

// 可选配置
const decimals = ref(2)
const extraDigits = ref(2)
const prefix = ref('$')
const suffix = ref(' USD')
const unit = ref('kg')
const formatter = (v: number) => v.toFixed(1)

// 样式
const label = ref('Price')
const separator = ref(': ')
const wrapperClass: ClassType = 'flex items-center gap-1'
const wrapperStyle: StyleType = {}
// ... 其余样式类与样式同理
</script>

React 示例 (核心可复用)

import React, { useState, useEffect } from 'react'
import 'signal-polyfill'
import { DataItemDisplayReact } from 'data-item-display/react'

export default function App() {
  const [value, setValue] = useState(12345.678)
  const [loading, setLoading] = useState(false)

  return (
    <DataItemDisplayReact
      value={value}
      loading={loading}
      decimals={2}
      extraDigits={2}
      prefix="$"
      suffix=" USD"
      unit="kg"
      formatter={v => v.toFixed(1)}
      label="Price"
      separator=": "
      wrapperClass="flex items-center gap-1"
    />
  )
}

四、组件 Props / API

| Prop 名称 | 类型 | 默认 | 说明 / Description | | | | ------------------- | ----------------------------------------- | ------------------------------------------------ | --------------------------------------------- | ------------------- | ------------------------------ | | value | number 或 Signal.State<number> | — | 必需，展示的数值 / Required value. | | | | loading | boolean | false | 加载状态占位符 / Loading placeholder. | | | | decimals | number 或 Signal.State<number> | 2 | 保留小数位数 / Number of decimal places. | | | | extraDigits | number 或 Signal.State<number> | 2 | 最大占位字符额外长度 / Extra placeholder char count. | | | | prefix | string 或 Signal.State<string> | '' | 数值前缀 / Prefix text. | | | | suffix | string 或 Signal.State<string> | '' | 数值后缀 / Suffix text. | | | | unit | string 或 Signal.State<string> | '' | 单位文本 / Unit label. | | | | formatter | (v: number) => string | Intl | 自定义格式化函数 / Custom formatting callback. | | | | label | string | '' | 标签文本 / Label before value. | | | | separator | string | ':' | 标签与数值分隔符 / Separator between label and value. | | | | wrapperClass | string/string[]/Record<string,bool> | flex items-center gap-1 | 容器 CSS 类 / Container classes. | | | | wrapperStyle | object | {} | 容器内联样式 / Container inline styles. | | | | labelWrapperClass | `string | string[] | Record<string,bool>` | flex items-center | 标签容器类 / Label wrapper classes. | | labelWrapperStyle | object | {} | 标签容器样式 / Label wrapper styles. | | | | labelClass | string | text-xs text-ink-600 leading-[18px] font-light | 标签类 / Label classes. | | | | labelStyle | object | {} | 标签样式 / Label styles. | | | | separatorClass | string | '' | 分隔符类 / Separator classes. | | | | separatorStyle | object | {} | 分隔符样式 / Separator styles. | | | | valueClass | string | text-xs text-ink leading-[18px] font-normal | 值类 / Value classes. | | | | valueStyle | object | {} | 值样式 / Value styles. | | | | skeletonClass | string | '' | 加载占位符类 / Skeleton classes. | | | | skeletonStyle | object | {} | 加载占位符样式 / Skeleton styles. | | |

五、开发 & 构建 Development & Build

# 安装依赖
pnpm install

# 本地开发（Vue + React 示例）
pnpm run dev

# 构建打包
pnpm run build

六、许可证 License

MIT