@cainiaofe/cn-domain-ai-table

v1.0.25

Published

3 days ago

菜鸟组件工程

快速开始

安装

npm install @cainiaofe/cn-domain-ai-table

基础用法

import { CnAiTable, ConfigProvider } from '@cainiaofe/cn-domain-ai-table';
import '@cainiaofe/cn-domain-ai-table/style.css';

function App() {
  return (
    <ConfigProvider>
      <CnAiTable id="my-table" columns={columns} remote={{ url: '/api/list' }} />
    </ConfigProvider>
  );
}

对等依赖

请确保安装以下对等依赖：

react / react-dom（^16.8.0 || ^18.3.0）
@cainiaofe/cn-ui (^0.12.59)

组件 API

CnAiTable

AI 驱动的多视图表格组件，支持表格、任务、智能跟单等多种视图类型。

基础属性

| 属性 | 类型 | 必填 | 说明 | | --------------- | -------------------- | :--: | ------------------------------------ | | id | string | 是 | 表格唯一标识，视图持久化依赖此值 | | columns | ColumnDefinition[] | 是 | 列定义数组 | | remote | { url: string } | 是 | 数据源配置（CnTable.useRemote 风格） | | operateColumn | object | 否 | 操作列配置 |

字段配置

| 属性 | 类型 | 默认值 | 说明 | | ------------------- | ----------------------------------- | ------ | ------------------------------------ | | enabledFieldTypes | ('ai' \| 'lookup' \| 'formula')[] | [] | 启用的自定义字段类型 | | fieldTypeOptions | object | — | 字段类型高级选项（如 lookup 的回调） |

// 启用全部字段类型
<CnAiTable
  enabledFieldTypes={['ai', 'lookup', 'formula']}
  fieldTypeOptions={{
    lookup: {
      hiddenSubTable: true,
      addFieldCallback: async (params) => {
        /* ... */
      },
      deleteFieldCallback: async (params) => {
        /* ... */
      },
    },
  }}
/>

视图配置 `viewTypes`

控制可用视图及视图内功能开关：

| 视图 | 默认状态 | 说明 | | ------------- | -------- | ---------------------------------- | | grid | 始终启用 | 表格视图，不可关闭，可配置 toolbar | | task | 启用 | 任务视图，false 关闭 | | smartFollow | 关闭 | 智能跟单视图，true 启用 |

<CnAiTable
  viewTypes={{
    grid: {
      toolbar: {
        fieldManagement: true,
        filter: true,
        sort: true,
        group: true,
        colorFill: true,
      },
    },
    task: { enableSummary: false, toolbar: false },
    smartFollow: { enableDetailSummary: true },
  }}
/>

列宽自动计算

| 属性 | 类型 | 默认值 | 说明 | | --------------------- | --------- | ------ | ---------------- | | columnsAutoWidth | boolean | true | 是否自动计算列宽 | | columnsAutoWidthOpt | object | — | 列宽调优参数 |

// 限制最大列宽并优化大数据量性能
<CnAiTable columnsAutoWidthOpt={{ maxWidth: 360, sampleRate: 0.2 }} />

columnsAutoWidthOpt 推荐参数：

| 参数 | 类型 | 默认值 | 说明 | | -------------------- | --------- | ------ | -------------------------------------------- | | maxWidth | number | 460 | 单列最大宽度 | | sampleRate | number | 自适应 | 行采样率（0~1），数据 > 200 行时自动降为 0.3 | | fillContainerWidth | boolean | true | 是否将剩余空间分配给可伸缩列 |

业务请求配置 `bizRequestConfig`

通过 bizRequestConfig 自定义各能力的接口地址：

<CnAiTable
  id="my-table"
  bizRequestConfig={{
    cubePlatform: {
      getListRequestConfig: {
        url: 'https://your-domain/api/views/getList',
        data: { pageId: 'xxx', appCode: 'xxx', userId: 'current-user' },
      },
      createOrUpdateRequestConfig: {
        url: 'https://your-domain/api/views/createOrUpdate',
        data: { pageId: 'xxx', appCode: 'xxx', userId: 'current-user' },
      },
    },
    subTableConfig: {
      url: '/api/sub-table/config',
      method: 'POST',
      data: { tableId: 'xxx' },
    },
    aiColumn: {
      queryTableTasksUrl: 'https://your-domain/api/ai/tasks',
      submitTasksUrl: 'https://your-domain/api/ai/submit',
    },
    smartFollow: {
      queryTasksUrl: 'https://your-domain/api/follow/tasks',
    },
    agent: {
      queryResponseUrl: 'https://your-domain/api/agent/query',
    },
  }}
/>

可配置的子项：

| 子项 | 说明 | | ---------------- | ---------------------------------------- | | cubePlatform | 视图持久化（getList / createOrUpdate） | | subTableConfig | 引用字段子表配置接口 | | aiColumn | AI 字段相关接口（提交/轮询/预览/删除等） | | smartFollow | 智能跟单接口 | | agent | AI 助理接口 |

未配置的项走组件内置默认逻辑，建议逐项替换，优先替换只读接口。

CnAiFilter

AI 智能筛选组件，支持自然语言转结构化查询条件。

<CnAiFilter
  bizRequestConfig={{
    filter: {
      fieldTransformUrl: '/api/filter/transform',
      suggestionUrl: '/api/filter/suggestions',
    },
  }}
/>

CnAiAgent

AI 助理组件，提供对话式交互能力。

<CnAiAgent
  bizRequestConfig={{
    agent: {
      submitPromptUrl: '/api/agent/submit',
      queryResponseUrl: '/api/agent/query',
    },
  }}
/>

视图持久化

通过 bizRequestConfig.cubePlatform 对接业务后端，实现视图配置的保存与恢复。

接口协议：

getList：页面加载时拉取已保存的视图配置
createOrUpdate：用户操作视图后自动触发保存

data 参数说明：

| 参数 | 必填 | 说明 | | --------- | :--: | ----------------------------------------- | | pageId | 是 | 页面唯一标识，隔离不同页面的视图配置 | | appCode | 否 | 应用编码，多应用共用后端时需传 | | userId | 否 | 当前用户 ID，不传则所有用户共享同一份视图 |

完整接口协议文档见 docs/view-config-api-spec.md。

主题定制

快速上手

通过 ConfigProvider 组件覆盖主题 Token 和视觉资产：

import { ConfigProvider } from '@cainiaofe/cn-domain-ai-table';

<ConfigProvider
  theme={{
    token: {
      'cnai-color-brand-primary': '#ff6a00',
      'cnai-gradient-brand': 'linear-gradient(135deg, #ff9500 36%, #ff6a00 96%)',
      'cnai-agent-bubble-user-bg': '#fff3e6',
    },
    components: {
      agent: { avatarUrl: 'https://my-cdn.com/avatar.png' },
      filter: { sendButtonIconUrl: 'https://my-cdn.com/search.png' },
    },
  }}
>
  <CnAiAgent />
  <CnAiFilter />
  <CnAiTable />
</ConfigProvider>;

ThemeConfig API

| 属性 | 类型 | 说明 | | ------------ | ---------------------------------- | ----------------------------------------------------- | | token | Record<string, string \| number> | CSS Token 覆盖映射，key 为 token 名（不含 -- 前缀） | | components | { agent?, filter?, table? } | 主题视觉资产覆盖（按组件维度） |

Hooks

| Hook | 返回类型 | 说明 | | ------------------ | ----------------- | -------------------------------------------- | | useTheme() | ThemeConfig | 获取当前作用域的主题配置 | | useBrandAssets() | BrandAssetGroup | 获取当前作用域的主题资产（已与默认资产合并） |

请使用主题配置Skill进行操作

公式字段

CnAiTable 支持类 Excel 的公式字段，用户可基于已有字段值进行自动计算。

启用

<CnAiTable enabledFieldTypes={['formula']} />

支持的函数

| 分类 | 函数 | | ---- | ---------------------------------------------------------------------------------------------------- | | 数学 | SUM, AVERAGE, MAX, MIN, COUNT, ABS, ROUND, CEILING, FLOOR, MOD, POWER, FIXED | | 逻辑 | IF, TRUE, FALSE | | 时间 | TODAY, YEAR, MONTH, HOUR, MINUTE, DAYS | | 文本 | CONCATENATE, LEFT, RIGHT, MID, REPLACE, REPT |

运算符

支持标准算术和比较运算符：+ - * / % == != > < >= <=

ROUND({单价} * {数量} * 0.9, 2)

完整使用指南见 docs/字段使用指南/公式字段使用方式.md。

npm 消费（ESM / CJS）

npm install @cainiaofe/cn-domain-ai-table

import { CnAiTable, CnAiFilter, CnAiAgent, ConfigProvider } from '@cainiaofe/cn-domain-ai-table';
import '@cainiaofe/cn-domain-ai-table/style.css';

对等依赖：react、react-dom、@cainiaofe/cn-ui。