npm package: @findor2026/fstring-prop
Description: A JavaScript library for formatted string properties with alignment support
Author: findor2026
Latest version: 1.0.2

# FString-Prop

一个用于格式化字符串属性的JavaScript库，支持对齐和模板字符串格式化。

## 安装

```bash
npm install @findor2026/fstring-prop
```

## 使用方法

### 基本用法

```javascript
const { FStringProp, Formatter } = require('@findor2026/fstring-prop');

// 创建格式化属性
const name = FStringProp.left('张三', 10);
const age = FStringProp.right(25, 5);
const product = FStringProp.center('笔记本电脑', 12);

// 格式化输出
console.log(name.format()); // '张三        '
console.log(age.format());  // '   25'
console.log(product.format()); // '    笔记本电脑    '
```

### 使用模板字符串

```javascript
const { Formatter, FStringProp } = require('@findor2026/fstring-prop');

const result = Formatter.format`
用户名: ${FStringProp.left('张三', 8)} | 年龄: ${FStringProp.right(25, 5)}
产品: ${FStringProp.center('笔记本电脑', 12)} | 价格: ${FStringProp.right('¥5999', 10)}
`;

console.log(result);
// 输出:
// 用户名: 张三       | 年龄:    25
// 产品:    笔记本电脑     | 价格:      ¥5999
```

### 快捷方法

```javascript
// 左对齐
FStringProp.left('文本', 10);

// 右对齐
FStringProp.right('文本', 10);

// 居中对齐
FStringProp.center('文本', 10);

// 普通对齐（与居中对齐相同）
FStringProp.normal('文本', 10);

// 无对齐
FStringProp.none('文本');
```

### 字符串管道语法

```javascript
// 使用字符串管道语法
const output = Formatter.format`${'苹果|left|8'} ${'香蕉|center|8'} ${'橙子|right|8'}`;
console.log(output); // '苹果          香蕉          橙子'
```

## API 参考

### Alignment 常量类

`Alignment` 类定义了所有可用的对齐方式常量。

#### 常量值
```javascript
Alignment.LEFT   // 'left' - 左对齐
Alignment.RIGHT  // 'right' - 右对齐
Alignment.CENTER // 'center' - 居中对齐
Alignment.NORMAL // 'normal' - 普通对齐（与居中对齐相同）
Alignment.NONE   // 'none' - 无对齐，直接返回原文本
```

#### 用法示例
```javascript
const { Alignment } = require('@findor2026/fstring-prop');

console.log(Alignment.LEFT);   // 'left'
console.log(Alignment.CENTER); // 'center'
console.log(Alignment.RIGHT);  // 'right'
console.log(Alignment.NORMAL); // 'normal'
console.log(Alignment.NONE);   // 'none'
```

### FStringProp 类

用于创建和管理格式化字符串属性的核心类。

#### 构造函数
```javascript
new FStringProp(name, alignment, width)
```

**参数：**
- `name` (string | any): 要格式化的文本。如果是非字符串，会自动转换为字符串。
- `alignment` (string): 对齐方式，使用 `Alignment` 常量（默认：`Alignment.LEFT`）。
- `width` (number): 字段宽度，即格式化后的总字符数（默认：10）。

**示例：**
```javascript
const prop = new FStringProp('Hello', Alignment.CENTER, 20);
```

#### 实例方法

##### `format()`
返回格式化后的字符串。

```javascript
const prop = new FStringProp('Hello', Alignment.CENTER, 20);
console.log(prop.format()); // '       Hello       '
```

#### 静态工厂方法

##### `FStringProp.left(text, width = 10)`
创建左对齐的格式化属性。

```javascript
const leftProp = FStringProp.left('Left', 15);
console.log(leftProp.format()); // 'Left           '
```

##### `FStringProp.right(text, width = 10)`
创建右对齐的格式化属性。

```javascript
const rightProp = FStringProp.right('Right', 15);
console.log(rightProp.format()); // '           Right'
```

##### `FStringProp.center(text, width = 10)`
创建居中对齐的格式化属性。

```javascript
const centerProp = FStringProp.center('Center', 15);
console.log(centerProp.format()); // '    Center     '
```

##### `FStringProp.normal(text, width = 10)`
创建普通对齐的格式化属性（与居中对齐相同）。

```javascript
const normalProp = FStringProp.normal('Normal', 15);
console.log(normalProp.format()); // '    Normal     '
```

##### `FStringProp.none(text)`
创建无对齐的格式化属性（宽度为0，直接返回原文本）。

```javascript
const noneProp = FStringProp.none('None');
console.log(noneProp.format()); // 'None'
```

#### 静态工具方法

##### `FStringProp.formatValue(text, alignment = Alignment.NORMAL, width = 10)`
直接格式化文本，无需创建 `FStringProp` 实例。

```javascript
const formatted = FStringProp.formatValue('Hello', Alignment.CENTER, 20);
console.log(formatted); // '       Hello       '
```

**参数：**
- `text` (string | any): 要格式化的文本
- `alignment` (string): 对齐方式
- `width` (number): 字段宽度

### Formatter 类

用于格式化模板字符串的实用类。

#### 静态方法

##### `Formatter.format(strings, ...values)`
格式化模板字符串，支持 `FStringProp` 实例和字符串管道语法。

**基本用法：**
```javascript
const result = Formatter.format`Name: ${FStringProp.left('John', 10)} Age: ${FStringProp.right(25, 5)}`;
console.log(result); // 'Name: John        Age:    25'
```

**字符串管道语法：**
支持 `文本|对齐方式|宽度` 格式的字符串。

```javascript
const result = Formatter.format`${'Apple|left|10'} ${'Banana|center|10'} ${'Orange|right|10'}`;
console.log(result); // 'Apple      Banana    Orange'
```

**参数：**
- `strings` (TemplateStringsArray): 模板字符串数组
- `...values` (Array): 插入值数组，可以是 `FStringProp` 实例、管道字符串或普通值

**返回值：** (string) 格式化后的完整字符串

**工作原理：**
1. 遍历模板字符串和插入值
2. 如果值是 `FStringProp` 实例，调用其 `format()` 方法
3. 如果值是包含 `|` 的字符串，解析为管道语法并格式化
4. 其他值直接转换为字符串
5. 拼接所有部分返回完整结果

## 示例

### 创建表格输出

```javascript
const { Formatter, FStringProp } = require('@findor2026/fstring-prop');

const header = Formatter.format`
${FStringProp.center('姓名', 10)} | ${FStringProp.center('年龄', 6)} | ${FStringProp.center('城市', 12)}
${'-'.repeat(32)}
`;

const row1 = Formatter.format`${FStringProp.left('张三', 10)} | ${FStringProp.right(25, 6)} | ${FStringProp.left('北京', 12)}`;
const row2 = Formatter.format`${FStringProp.left('李四', 10)} | ${FStringProp.right(30, 6)} | ${FStringProp.left('上海', 12)}`;

console.log(header + row1 + '\n' + row2);
```

## 测试

运行测试：

```bash
npm test
```

## 许可证

MIT