@canvas-components/react-pivot-table 0.1.9 → 0.2.2

package/README.md

@@ -0,0 +1,118 @@
+# @canvas-components/react-pivot-table
+
+`@canvas-components/react-pivot-table` 是 `@canvas-components/pivot-table` 的 React 适配层，在保留原生 Canvas 数据透视表性能的同时，提供标题栏、字段配置面板、图表联动和 React ref 接口。
+
+## 示例效果
+
+![React Pivot Table 示例](./assets/react-pivot-table-demo.gif)
+
+## 功能作用
+
+- 提供 `ReactPivotTable` 组件
+- 支持行、列、指标的多层聚合与虚拟滚动
+- 支持字段面板配置和透视图表联动
+- 暴露选择、展开、筛选、排序、导出和状态快照方法
+- 聚合、布局和 Canvas 渲染复用纯原生 `pivot-table` 内核
+
+## 安装方法
+
+```bash
+pnpm add @canvas-components/react-pivot-table @canvas-components/pivot-table react@^16.8 react-dom@^16.8
+```
+
+最低依赖版本：
+
+- `react >= 16.8.0`
+- `react-dom >= 16.8.0`
+- `Node.js >= 18.12.0`
+- `pnpm >= 9.0.0`
+
+## 使用方法
+
+```tsx
+import { ReactPivotTable } from "@canvas-components/react-pivot-table";
+
+interface SalesRecord {
+  region: string;
+  city: string;
+  year: number;
+  sales: number;
+}
+
+export function SalesPivotTable(props: { data: SalesRecord[] }) {
+  return (
+    <div style={{ width: "100%", height: 560 }}>
+      <ReactPivotTable<SalesRecord>
+        title="销售数据透视表"
+        dataSource={props.data}
+        rows={[
+          { key: "region", title: "区域", dataIndex: "region" },
+          { key: "city", title: "城市", dataIndex: "city" },
+        ]}
+        columns={[{ key: "year", title: "年份", dataIndex: "year" }]}
+        indicators={[
+          {
+            key: "sales",
+            title: "销售额",
+            dataIndex: "sales",
+            aggregator: "sum",
+          },
+        ]}
+        totals={{
+          showRowSubtotals: true,
+          showColumnGrandTotal: true,
+          showRowGrandTotal: true,
+        }}
+      />
+    </div>
+  );
+}
+```
+
+## 属性说明
+
+### `ReactPivotTableProps`
+
+`ReactPivotTableProps` 继承自 `PivotTableOptions`，并增加 React 宿主相关属性。
+
+| 属性            | 类型                                             | 说明                         |
+| --------------- | ------------------------------------------------ | ---------------------------- |
+| `className`     | `string`                                         | 根节点类名                   |
+| `style`         | `CSSProperties`                                  | 根节点样式                   |
+| `title`         | `ReactNode`                                      | 标题栏内容                   |
+| `customization` | `boolean \| ReactPivotTableCustomizationOptions` | 是否启用字段配置面板及其配置 |
+
+其余 `dataSource`、`rows`、`columns`、`indicators`、`totals`、`filters`、`sorts` 和虚拟滚动等属性与 `@canvas-components/pivot-table` 保持一致。
+
+### `ReactPivotTableCustomizationOptions`
+
+| 属性             | 类型               | 说明                     |
+| ---------------- | ------------------ | ------------------------ |
+| `fields`         | `PivotField[]`     | 可参与透视配置的全部字段 |
+| `open`           | `boolean`          | 受控字段面板开关         |
+| `defaultOpen`    | `boolean`          | 非受控字段面板初始状态   |
+| `layout`         | `PivotFieldLayout` | 受控字段区域布局         |
+| `defaultLayout`  | `PivotFieldLayout` | 非受控字段区域初始布局   |
+| `panelWidth`     | `number`           | 字段面板宽度             |
+| `onOpenChange`   | `(open) => void`   | 面板开关变化回调         |
+| `onLayoutChange` | `(layout) => void` | 字段区域布局变化回调     |
+| `onFieldChange`  | `(field) => void`  | 字段配置变化回调         |
+
+## 实例方法
+
+通过 `ReactPivotTableRef` 可以访问以下能力：
+
+- 获取透视模型、可见行列节点和单元格明细记录
+- 读取或设置选择状态，并滚动到指定单元格
+- 展开、收起行列节点或全部节点
+- 设置维度筛选、维度排序和指标排序
+- 导出 CSV、XLSX
+- 获取和恢复版本化状态快照
+- 获取调试快照
+
+## 推荐场景
+
+- React 数据分析后台
+- 大数据量多维聚合报表
+- 需要字段拖放配置或图表联动的数据透视场景
+- 需要原生 Canvas 性能和 React 组件用法的场景

package/dist/index.cjs

@@ -954,13 +954,21 @@ function buildPivotChartOption(params) {
         show: true,
         left: 12,
         right: 14,
-        top: 14,
+        top: 40,
         bottom: 18,
         containLabel: true,
         backgroundColor: "#ffffff",
         borderColor: "#e6e9ed",
         borderWidth: 1
       },
+      legend: {
+        show: true,
+        orient: "horizontal",
+        left: "center",
+        top: "top",
+        itemGap: 12,
+        textStyle: { color: "#646a73", fontSize: 11 }
+      },
       xAxis: horizontal ? valueAxis : categoryAxis,
       yAxis: horizontal ? categoryAxis : valueAxis,
       tooltip: {
@@ -1594,7 +1602,12 @@ function toSharedValue(value) {
     secondConditionValue: stringifyConditionValue(value.secondCondition?.value),
     secondConditionSecondValue: stringifyConditionValue(
       value.secondCondition?.secondValue
-    )
+    ),
+    conditions: value.conditions?.map((condition) => ({
+      operator: toSharedOperator(condition.operator),
+      value: stringifyConditionValue(condition.value),
+      secondValue: stringifyConditionValue(condition.secondValue)
+    }))
   };
 }
 function toPivotFilter(value) {
@@ -1610,6 +1623,13 @@ function toPivotFilter(value) {
         value.secondConditionValue,
         value.secondConditionSecondValue
       ),
+      conditions: value.conditions?.map(
+        (condition) => toPivotCondition(
+          condition.operator,
+          condition.value,
+          condition.secondValue
+        )
+      ),
       conditionRelation: value.conditionRelation
     };
   }
@@ -1693,7 +1713,10 @@ var defaultFilterTexts = {
   relationAndLabel: "\u4E14",
   relationOrLabel: "\u6216",
   resetAction: "\u91CD\u7F6E",
-  applyAction: "\u786E\u5B9A"
+  applyAction: "\u786E\u5B9A",
+  conditionLabel: "\u6761\u4EF6",
+  addConditionAction: "\u65B0\u589E\u6761\u4EF6",
+  deleteConditionAction: "\u5220\u9664\u6761\u4EF6"
 };
 function inferFieldAggregator(records, dataIndex) {
   const value = records.map((record) => pivotTable.getValueByDataIndex(record, dataIndex)).find((item) => item != null);