@pisell/materials

@pisell/materials

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

📦 安装

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

🚀 快速开始

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

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="内容" />

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

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

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

💡 两种方式完全等价，选择你喜欢的方式！详见 命名空间使用指南

📚 组件分类

🌟 命名空间（推荐使用）

命名空间	说明	组件数量	使用方式
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 - 字段组件（最新开发）

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 - 指标展示

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

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

3. PisellLayouts - 布局组合

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 - ✨ 新的命名空间使用方式
• 组件索引：COMPONENTS.md - 162 个组件的完整分类索引
• 开发规范：.cursor/rules/create-component-rule.mdc
• LowCode 配置：.cursor/rules/lowcode-meta-rule.mdc
• 在线文档：查看 application/docs

🛠️ 开发

# 安装依赖
pnpm install

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

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

# 构建
pnpm run build

# 测试
pnpm run test

📦 构建产物

ESM/CJS 模块

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

LowCode 物料

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

🔧 配置

TypeScript

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

低代码集成

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

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

主题定制

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

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

📋 组件命名规范

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

🎯 使用建议

新项目

• ✅ 使用命名空间导入：PisellFields, PisellMetrics 等
• ✅ 更清晰的代码组织
• ✅ 更好的 IDE 提示

历史项目

• ✅ 保持现有导入方式
• ✅ 无需修改任何代码
• ✅ 100% 向后兼容

混合使用

• ✅ 两种方式可以同时使用
• ✅ 根据场景灵活选择

🤝 贡献

请参考 组件开发规范

📄 许可

MIT

💡 提示：

• 查看 NAMESPACE_GUIDE.md 了解命名空间详细用法
• 查看 COMPONENTS.md 获取完整组件列表