@pisell/materials 1.0.1048 → 1.0.1050

package/es/components/pisellExport/docs/pisellExport.md

@@ -0,0 +1,162 @@
+---
+nav:
+  title: 组件
+  order: 1
+group:
+  title: Data Entry
+  order: 1
+title: PisellExport
+order: 1
+category: atom
+---
+
+# PisellExport 导出按钮
+
+导出触发器组件，提供「仅图标」与「图标+文案」两种形态，支持小/中/大三种尺寸与默认、主色、禁用等状态。点击后通过 `onExport` 回调由调用方实现导出请求、下载等逻辑。
+
+## 何时使用
+
+- 表格、列表的导出为 Excel/CSV
+- 报表、数据导出
+- 需要与 PisellImport 搭配使用的导入导出场景
+
+## 代码演示
+
+### 基础用法
+
+默认 Button 形态，点击后触发 `onExport`，由调用方实现导出逻辑。
+
+```tsx
+import React from 'react';
+import { PisellExport } from '@pisell/materials';
+
+export default () => {
+  return (
+    <PisellExport
+      onExport={(e) => {
+        console.log('点击导出', e);
+        // 调用方：请求导出接口、轮询、下载等
+      }}
+    />
+  );
+};
+```
+
+### 仅图标
+
+`variant="icon"` 时只显示图标，不显示文案。
+
+```tsx
+import React from 'react';
+import { PisellExport } from '@pisell/materials';
+
+export default () => {
+  return <PisellExport variant="icon" onExport={() => console.log('export')} />;
+};
+```
+
+### 三种尺寸
+
+`size` 支持 `small`、`medium`、`large`。
+
+```tsx
+import React from 'react';
+import { PisellExport } from '@pisell/materials';
+
+export default () => {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
+      <PisellExport size="small" onExport={() => {}} />
+      <PisellExport size="medium" onExport={() => {}} />
+      <PisellExport size="large" onExport={() => {}} />
+    </div>
+  );
+};
+```
+
+### 默认与主色
+
+`type="default"` 为灰边样式，`type="primary"` 为主色描边样式。
+
+```tsx
+import React from 'react';
+import { PisellExport } from '@pisell/materials';
+
+export default () => {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
+      <PisellExport type="default" onExport={() => {}} />
+      <PisellExport type="primary" onExport={() => {}} />
+    </div>
+  );
+};
+```
+
+### 禁用
+
+`disabled` 为 true 时不可点击。
+
+```tsx
+import React from 'react';
+import { PisellExport } from '@pisell/materials';
+
+export default () => {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
+      <PisellExport disabled onExport={() => {}} />
+      <PisellExport type="primary" disabled onExport={() => {}} />
+    </div>
+  );
+};
+```
+
+### 自定义文案与图标
+
+通过 `label`、`icon` 自定义按钮文案和图标。
+
+```tsx
+import React from 'react';
+import { PisellExport } from '@pisell/materials';
+import { DownloadOutlined } from '@ant-design/icons';
+
+export default () => {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
+      <PisellExport label="导出 Excel" onExport={() => {}} />
+      <PisellExport
+        icon={<DownloadOutlined style={{ fontSize: 20 }} />}
+        label="下载"
+        onExport={() => {}}
+      />
+    </div>
+  );
+};
+```
+
+## API
+
+### PisellExport Props
+
+| 参数      | 说明                     | 类型                                              | 默认值    | 必填 |
+| --------- | ------------------------ | ------------------------------------------------- | --------- | ---- |
+| variant   | 展示形态                 | `'icon' \| 'button'`                             | `'button'` | ❌   |
+| size      | 尺寸                     | `'small' \| 'medium' \| 'large'`                 | `'medium'` | ❌   |
+| type      | 视觉类型                 | `'default' \| 'primary'`                         | `'default'` | ❌   |
+| disabled  | 是否禁用                 | `boolean`                                         | `false`   | ❌   |
+| label     | Button 形态文案           | `ReactNode`                                       | 国际化默认 | ❌   |
+| icon      | 自定义图标               | `ReactNode`                                       | 内置下载图标 | ❌   |
+| onExport  | 点击触发导出             | `(e: React.MouseEvent<HTMLElement>) => void`       | -         | ❌   |
+| className | 自定义类名               | `string`                                          | -         | ❌   |
+| style     | 自定义样式               | `CSSProperties`                                   | -         | ❌   |
+
+## 注意事项
+
+1. **回调必传**：实际使用中建议传入 `onExport`，在回调中实现导出请求、轮询、下载等逻辑，组件本身不内置导出能力
+2. **形态与尺寸**：与 PisellImport 保持一致，支持 `variant="icon"`、`size`、`type`，便于并排使用
+3. **搭配使用**：常与 PisellImport 并排使用，形成导入导出能力
+
+## 相关文档
+
+- [设计文档](./pisellExport.$tab-design.md)
+- [开发文档](./pisellExport.$tab-dev.md)
+- [测试文档](./pisellExport.$tab-test.md)

package/es/components/pisellExport/index.d.ts

@@ -0,0 +1,2 @@
+import { ExportButtonType, PisellExportProps, SizeType, VariantType } from "./types.js";
+import { PisellExport } from "./PisellExport.js";

package/es/components/pisellExport/types.d.ts

@@ -0,0 +1,67 @@
+import { CSSProperties, MouseEvent, ReactNode } from "react";
+
+//#region src/components/pisellExport/types.d.ts
+/**
+ * 展示形态
+ * @description icon：仅图标；button：图标 + 文案
+ */
+type VariantType = 'icon' | 'button';
+/**
+ * 尺寸
+ * @description 小、中、大三种尺寸，对应设计稿 padding 与字体
+ */
+type SizeType = 'small' | 'medium' | 'large';
+/**
+ * 视觉类型
+ * @description default：默认边框/灰字；primary：主色描边或填充
+ */
+type ExportButtonType = 'default' | 'primary';
+/**
+ * PisellExport 组件 Props
+ * @description 导出触发器 UI 组件，仅负责展示与点击回调，不内置导出逻辑
+ */
+interface PisellExportProps {
+  /**
+   * 展示形态
+   * @default 'button'
+   */
+  variant?: VariantType;
+  /**
+   * 尺寸
+   * @default 'medium'
+   */
+  size?: SizeType;
+  /**
+   * 视觉类型（默认样式 / 主色样式）
+   * @default 'default'
+   */
+  type?: ExportButtonType;
+  /**
+   * 是否禁用
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Button 形态下的文案，不传时使用国际化默认文案
+   */
+  label?: ReactNode;
+  /**
+   * 自定义图标，不传时使用内置下载图标（download-cloud-01）
+   */
+  icon?: ReactNode;
+  /**
+   * 点击触发导出
+   * @description 由调用方在此回调中实现导出请求、轮询、下载等逻辑
+   */
+  onExport?: (e: MouseEvent<HTMLElement>) => void;
+  /**
+   * 自定义类名
+   */
+  className?: string;
+  /**
+   * 自定义样式
+   */
+  style?: CSSProperties;
+}
+//#endregion
+export { ExportButtonType, PisellExportProps, SizeType, VariantType };