npm package: @herongxhr/data-item
Description: > 轻量级 Vue 数据展示组件，支持数字格式化、最大占位宽度和多框架响应式核心。 > > A lightweight Vue data display component with number formatting, max placeholder width, and a framework-agnostic reactive core.
Latest version: 0.0.1

# 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

```bash
npm install data-item-display signal-polyfill
# or
pnpm add data-item-display signal-polyfill
```

---

## 三、使用示例 Usage Example

### Vue 3 (推荐)

```vue
<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 示例 (核心可复用)

```tsx
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

```bash
# 安装依赖
pnpm install

# 本地开发（Vue + React 示例）
pnpm run dev

# 构建打包
pnpm run build
```

---

## 六、许可证 License

MIT