# @pisell/materials

> > Pisell 2.0 基础物料库 - 包含原子组件和 Pro 组件

Latest version **6.3.51** (published 2026-10-22) · 0 weekly downloads

## Install

```sh
npm install @pisell/materials
pnpm add @pisell/materials
yarn add @pisell/materials
bun add @pisell/materials
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; large bundle.

## Facts

| | |
|---|---|
| Version | 6.3.51 |
| Published | 2026-10-22 |
| First published | 2023-06-27 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 27 |
| Unpacked size | 39.7 MB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Maintainers | wang_han, zsj1037797769, zhiwei.wang, yaoxiaojia, larry_ranhejun, xiangfeng.xue, ah-sc, jinglin.tan |

## Links

- npm: https://www.npmjs.com/package/@pisell/materials
- npm.io page: https://npm.io/package/@pisell/materials

## Dependencies (27)

- [antd](https://npm.io/package/antd.md) 5.10.1
- [dayjs](https://npm.io/package/dayjs.md) ^1.11.8
- [ahooks](https://npm.io/package/ahooks.md) ^3.7.6
- [swiper](https://npm.io/package/swiper.md) ^8.4.7
- [crypto-js](https://npm.io/package/crypto-js.md) ^4.2.0
- [classnames](https://npm.io/package/classnames.md) ^2.3.2
- [@pisell/icon](https://npm.io/package/@pisell/icon.md) workspace:*
- [react-window](https://npm.io/package/react-window.md) ^1.8.10
- [@dnd-kit/core](https://npm.io/package/@dnd-kit/core.md) ^6.0.8
- [@pisell/utils](https://npm.io/package/@pisell/utils.md) workspace:*
- [antd-img-crop](https://npm.io/package/antd-img-crop.md) ^4.23.0
- [react-barcode](https://npm.io/package/react-barcode.md) ^1.5.3
- [vod-js-sdk-v6](https://npm.io/package/vod-js-sdk-v6.md) 1.4.11
- [@zxing/library](https://npm.io/package/@zxing/library.md) 0.21.2
- [react-resizable](https://npm.io/package/react-resizable.md) ^3.0.5
- [react-camera-pro](https://npm.io/package/react-camera-pro.md) 1.4.0
- [@ant-design/icons](https://npm.io/package/@ant-design/icons.md) ^5.6.1
- [@dnd-kit/sortable](https://npm.io/package/@dnd-kit/sortable.md) ^7.0.2
- [libphonenumber-js](https://npm.io/package/libphonenumber-js.md) ^1.11.17
- [styled-components](https://npm.io/package/styled-components.md) ^6.0.0-rc.3
- [@ant-design/colors](https://npm.io/package/@ant-design/colors.md) ^7.1.0
- [@dnd-kit/modifiers](https://npm.io/package/@dnd-kit/modifiers.md) ^6.0.1
- [@dnd-kit/utilities](https://npm.io/package/@dnd-kit/utilities.md) ^3.2.1
- [@pisell/date-picker](https://npm.io/package/@pisell/date-picker.md) workspace:*
- [react-zoom-pan-pinch](https://npm.io/package/react-zoom-pan-pinch.md) ^3.7.0
- [react-virtualized-auto-sizer](https://npm.io/package/react-virtualized-auto-sizer.md) ^1.0.20
- [react-infinite-scroll-component](https://npm.io/package/react-infinite-scroll-component.md) ^6.1.0

## Recent versions

- 6.3.51 (latest) — 2026-10-22
- 6.3.52 (beta) — 2026-10-22
- 1.0.1108 — 2026-10-22
- 1.0.1107 — 2026-10-22
- 1.0.1106 — 2026-10-22
- 1.0.1105 — 2026-10-22
- 3.4.1 — 2026-10-22
- 6.12.86 — 2026-10-21
- 1.10.35 — 2026-10-21
- 6.12.84 — 2026-10-20
- 6.12.85 — 2026-10-20
- 6.12.83 — 2026-10-20
- 6.11.273 — 2026-10-20
- 1.10.34 — 2026-10-20
- 6.3.50 — 2026-10-19
- … 1968 more at https://npm.io/package/@pisell/materials/versions

## README

# @pisell/materials

> Pisell 2.0 基础物料库 - 包含原子组件和 Pro 组件

[![Version](https://img.shields.io/npm/v/@pisell/materials.svg)](https://www.npmjs.com/package/@pisell/materials)
[![License](https://img.shields.io/npm/l/@pisell/materials.svg)](https://github.com/your-org/pisell2)

## 开发方案

- [PisellCalendar 日历使用说明](./src/components/pisellCalendar/README.md)（React/低代码接入、截止日展示、拖动回退）
- [PisellGantt 甘特图使用说明](./src/components/pisellGantt/README.md)（React/低代码接入、分组、移动与拉伸）

## 📦 安装

```bash
npm install @pisell/materials
# or
pnpm add @pisell/materials
```

## 🚀 快速开始

### ✨ 方式一：命名空间导入（推荐）

```tsx
import { PisellFields, PisellMetrics, PisellLayouts, PisellCards } from '@pisell/materials';

// 字段组件 - 支持编辑/只读/禁用三态
<PisellFields.SingleLineText value="Hello" viewMode="edit" />
<PisellFields.Currency value={1000} currencySymbol="$" />
<PisellFields.Percent value={0.85} />

// 数据展示 - 指标卡片
<PisellMetrics.MetricCard 
  title="Total Sales" 
  value={1580}
  comparison={120}
  showTrendIcon 
/>

// 布局组件 - 网格布局
<PisellLayouts.BasicGrid columns={3} gap={16}>
  {items.map(item => <Card key={item.id} {...item} />)}
</PisellLayouts.BasicGrid>

// 卡片组件
<PisellCards.TextCard title="标题" content="内容" />
```

### ✅ 方式二：单独导入（兼容历史）

```tsx
import { 
  PisellSingleLineText, 
  PisellMetricCard, 
  PisellBasicGrid 
} from '@pisell/materials';

// 使用方式完全一致
<PisellSingleLineText value="Hello" viewMode="edit" />
<PisellMetricCard title="Total Sales" value={1580} />
<PisellBasicGrid columns={3}>{children}</PisellBasicGrid>
```

> 💡 **两种方式完全等价**，选择你喜欢的方式！详见 [命名空间使用指南](./NAMESPACE_GUIDE.md)

---

## 📚 组件分类

### 🌟 命名空间（推荐使用）

| 命名空间 | 说明 | 组件数量 | 使用方式 |
|---------|------|---------|----------|
| **`PisellFields`** | 字段组件（三态视图） | 11 个 | `<PisellFields.SingleLineText />` |
| **`PisellMetrics`** | 指标展示组件 | 3 个 | `<PisellMetrics.MetricCard />` |
| **`PisellLayouts`** | 布局组件 | 10 个 | `<PisellLayouts.BasicGrid />` |
| **`PisellCards`** | 卡片组件 | 5 个 | `<PisellCards.TextCard />` |

### 📦 完整组件列表

| 分类 | 组件数量 | 说明 |
|------|---------|------|
| 字段组件 | 11 个 | 支持编辑/只读/禁用三态的表单字段 |
| 卡片组件 | 12+ 个 | 各类内容展示卡片 |
| 数据展示 | 10+ 个 | 指标、统计、KPI 展示 |
| 布局组件 | 10+ 个 | 页面布局和容器 |
| 表格组件 | 5 个 | 数据表格及增强功能 |
| 表单组件 | 15+ 个 | 表单输入和编辑 |
| 导航组件 | 10+ 个 | 菜单、步骤条、标签页 |

---

## ⭐ 核心特性

### 命名空间组件示例

#### 1. PisellFields - 字段组件（最新开发）

```tsx
import { PisellFields } from '@pisell/materials';

// 支持三态视图：编辑态、只读态、禁用态
<PisellFields.SingleLineText
  value="Hello"
  viewMode="edit"  // edit | readonly | disabled
  onChange={setValue}
/>

<PisellFields.Currency
  value={1000}
  currencySymbol="$"
  precision={2}
  useGrouping
/>

<PisellFields.Percent
  value={0.85}
  showAsDecimal={false}  // 显示为 85%
/>
```

**完整字段列表：**
- SingleLineText, LongText
- Number, Currency, Percent
- Phone, Email, Url
- Rating, SingleSelect, MultipleSelect

#### 2. PisellMetrics - 指标展示

```tsx
import { PisellMetrics } from '@pisell/materials';

// 完整功能的指标卡片
<PisellMetrics.MetricCard
  title="Total Sales"
  value={1580}
  showCurrencySymbol
  currencySymbol="$"
  comparison={120}        // 环比数据
  showComparison
  showTrendIcon          // 自动显示上升/下降箭头
/>
```

#### 3. PisellLayouts - 布局组合

```tsx
import { PisellLayouts, PisellCards } from '@pisell/materials';

// 推荐组合：快速搭建列表/网格场景
<PisellLayouts.ScrollView direction="horizontal">
  <PisellLayouts.BasicGrid columns={3} gap={16}>
    {items.map(item => (
      <PisellCards.TextCard key={item.id} {...item} />
    ))}
  </PisellLayouts.BasicGrid>
</PisellLayouts.ScrollView>
```

---

## 📖 完整文档

- **命名空间指南**：[NAMESPACE_GUIDE.md](./NAMESPACE_GUIDE.md) - ✨ 新的命名空间使用方式
- **组件索引**：[COMPONENTS.md](./COMPONENTS.md) - 162 个组件的完整分类索引
- **开发规范**：[.cursor/rules/create-component-rule.mdc](../../.cursor/rules/create-component-rule.mdc)
- **LowCode 配置**：[.cursor/rules/lowcode-meta-rule.mdc](../../.cursor/rules/lowcode-meta-rule.mdc)
- **在线文档**：查看 application/docs

---

## 🛠️ 开发

```bash
# 安装依赖
pnpm install

# 开发模式（低代码）
pnpm run lowcode:dev

# 开发模式（ES 模块）
pnpm run dev

# 构建
pnpm run build

# 测试
pnpm run test
```

---

## 📦 构建产物

### ESM/CJS 模块

```bash
lib/       # CommonJS 格式
es/        # ES Module 格式
```

### LowCode 物料

```bash
build/lowcode/
├── assets-prod.json   # 物料描述文件
├── view.js            # UMD 格式组件包
└── view.css           # 样式文件
```

---

## 🔧 配置

### TypeScript

```tsx
import type { 
  PisellMetricCardProps,
  PisellSingleLineTextProps,
  PisellBasicGridProps 
} from '@pisell/materials';
```

### 低代码集成

```typescript
// 在低代码引擎中使用
import assets from '@pisell/materials/build/lowcode/assets-prod.json';

// 加载物料
await loadAssets(assets);
```

### 主题定制

```tsx
import { PisellConfigProvider } from '@pisell/materials';

<PisellConfigProvider theme={{...}}>
  <App />
</PisellConfigProvider>
```

---

## 📋 组件命名规范

| 前缀 | 说明 | 示例 |
|------|------|------|
| `Pisell*` | Pisell 系列组件 | PisellButton, PisellMetricCard |
| `DataSource*` | 数据源组件 | DataSourceForm, DataSourceTable |
| `FormItem*` | 表单项组件 | FormItemInput, FormItemSelect |

---

## 🎯 使用建议

### 新项目
- ✅ 使用命名空间导入：`PisellFields`, `PisellMetrics` 等
- ✅ 更清晰的代码组织
- ✅ 更好的 IDE 提示

### 历史项目
- ✅ 保持现有导入方式
- ✅ 无需修改任何代码
- ✅ 100% 向后兼容

### 混合使用
- ✅ 两种方式可以同时使用
- ✅ 根据场景灵活选择

---

## 🤝 贡献

请参考 [组件开发规范](../../.cursor/rules/create-component-rule.mdc)

---

## 📄 许可

MIT

---

**💡 提示**：
- 查看 [NAMESPACE_GUIDE.md](./NAMESPACE_GUIDE.md) 了解命名空间详细用法
- 查看 [COMPONENTS.md](./COMPONENTS.md) 获取完整组件列表

---
_Source: https://npm.io/package/@pisell/materials · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._