neo-cmp-cli 1.12.2 → 1.12.3

package/template/develop/EntityGrid Web /347/273/204/344/273/266/347/232/204/350/257/246/347/273/206/345/210/206/346/236/220/346/226/207/346/241/243.md"

@@ -0,0 +1,868 @@
+# web端 EntityGrid 组件详细分析文档
+
+## 目录
+
+- [组件概述](#组件概述)
+- [核心功能](#核心功能)
+- [组件架构](#组件架构)
+- [主要属性说明](#主要属性说明)
+- [生命周期方法](#生命周期方法)
+- [核心方法详解](#核心方法详解)
+- [使用示例](#使用示例)
+- [扩展机制](#扩展机制)
+- [注意事项](#注意事项)
+- [常见问题](#常见问题)
+
+## 组件概述
+
+`EntityGrid` 是 Neo UI Component Web 端的核心业务组件，用于展示和管理实体数据列表。它基于 AG-Grid 实现，支持表格视图、分屏视图、地图视图、BI 看板等多种展示模式，提供了完整的数据展示、筛选、排序、批量操作、单元格编辑等功能。
+
+### 技术栈
+
+- **React**: 基于 React 类组件实现
+- **MobX**: 使用 MobX 进行状态管理（通过 `@observer` 装饰器）
+- **MobX State Tree**: Store 使用 MST 进行状态管理
+- **AG-Grid**: 基于 AG-Grid 进行表格渲染
+- **amis**: 通过 amis 框架进行布局和部分 UI 渲染
+- **TypeScript**: 完整的类型定义支持
+
+### 组件位置
+
+```
+packages/neo-ui-component-web/src/components/EntityGrid/
+├── component.tsx          # 主组件实现
+├── amisRegister.tsx       # amis 注册入口
+├── store.ts              # Store 定义（EntityGridStore）
+├── interface/            # 接口定义
+│   └── index.ts          # 接口导出
+├── constant/             # 常量定义
+│   ├── index.ts          # 常量导出
+│   ├── hoc.props.ts      # HOC 透传属性
+│   └── store.types.ts     # Store 类型定义
+├── model/                # 数据模型
+│   ├── dataSource.ts     # 数据源
+│   ├── dataView.ts       # 数据视图
+│   └── layout/           # 布局模型
+├── nex/                  # Nex 扩展
+│   ├── nexManager.ts     # Nex 管理器
+│   ├── nex.v1/           # Nex 1.0 实现
+│   └── nex.v2/           # Nex 2.0 实现
+├── cmp/                  # 内部组件
+│   ├── EntityGridHeader.tsx   # 头部
+│   ├── EntityGridFooter.tsx  # 底部
+│   ├── empty.tsx         # 空状态
+│   ├── SmartView/        # SmartView 切换
+│   ├── FilterList/       # 筛选列表
+│   ├── BatchOperate/     # 批量操作
+│   ├── MapView/          # 地图视图
+│   └── splitView/        # 分屏视图
+└── request/              # 请求相关
+```
+
+## 核心功能
+组件 cmpType: entityGrid
+
+基于 neoGrid 实现，而 neoGrid 又基于 aggrid 封装；
+注册 entityGrid 时，storeType 设置的是自定义的 store（EntityGridStore：packages/neo-ui-component-web/src/components/EntityGrid/store.ts）。
+
+### 1. 多种展示模式
+
+组件支持以下展示模式（通过 `displayMode` 控制）：
+
+- **`list`**: 列表视图（默认）- 标准表格展示
+- **`listSplitView`**: 分屏视图 - 左侧列表 + 右侧详情
+- **`listMapView`**: 地图视图 - 地图 + 列表联动
+- **BI Board**: BI 看板视图（通过 `biListVisible` 控制）
+
+### 2. 数据展示功能
+
+- **表格视图**: 基于 AG-Grid 的完整表格能力
+- **SmartView 切换**: 支持多个视图配置切换
+- **分页加载**: 支持服务端分页（serverSide）和客户端分页（clientSide）
+- **树形结构**: 支持树形数据展示（`treeData: true`）
+- **空状态处理**: 提供友好的空数据提示
+- **错误处理**: 完善的错误提示和重试机制
+
+### 3. 筛选和排序
+
+- **筛选功能**:
+  - 支持列头筛选
+  - 支持自定义筛选条件（`setCustomCondition`）
+  - 筛选条件持久化
+- **排序功能**:
+  - 支持多列排序
+  - 支持升序/降序切换
+  - 排序状态持久化
+
+### 4. 批量操作
+
+- **批量选择**: 支持单选/多选模式
+- **批量操作按钮**: 支持批量编辑、删除、转移等操作
+- **批量编辑**: 支持扣框编辑（单元格内联编辑）
+- **Picker 模式**: 支持作为选择器使用（`pattern: 'pickView'`）
+
+### 5. 单元格编辑
+
+- **扣框编辑**: 支持单元格内联编辑
+- **批量保存**: 支持批量编辑后统一保存
+- **权限控制**: 支持字段级编辑权限
+- **校验**: 支持保存前校验
+
+### 6. 详情打开方式
+
+- **单击**: 侧滑抽屉打开详情
+- **双击**: 新页签打开详情
+- **分屏视图**: 右侧直接展示详情
+- **地图视图**: 点击地图标记打开详情
+
+### 7. 扩展机制
+
+- **Nex 1.0**: 通过 `nexVersion: 1` 进行扩展
+- **Nex 2.0**: 通过 `nexVersion: 2` 进行扩展
+- **HOC 扩展**: 通过 `HOC_PROPS` 透传业务线扩展属性
+
+## 组件架构
+
+### 组件继承关系
+
+```typescript
+@GridRenderer({ Layout: {} })
+export default class ComponentRenderer extends Common<RendererProps>
+```
+
+- `@GridRenderer({ Layout: {} })`: amis 网格渲染器装饰器
+- `Common`: 即 `EntityGrid` 主组件
+- 继承自 `React.Component`
+
+### 核心实例属性
+
+```typescript
+class EntityGrid {
+  neoStore: DataStore              // 导航栏相关 Store（多页签模式）
+  entityGridLayout: EntityGridLayout  // 布局管理器
+  nexObj: NexManager               // Nex 扩展实例
+  rightFloatElement: HTMLDivElement   // 单元格编辑图标容器
+  uuid: string                     // 组件唯一标识
+  __com__: EntityGridPageCom       // 页面 Com 实例（用于刷新等）
+}
+```
+
+### Store 结构
+
+组件依赖 `EntityGridStore`（基于 MST），主要包含以下状态：
+
+- **数据状态**: `rowData`, `totalCount`, `currentPage`
+- **视图状态**: `displayMode`, `activeSmartView`, `dataListViews`
+- **筛选状态**: `filterModel`, `headerCondition`
+- **排序状态**: `sortModel`
+- **加载状态**: `loading`, `ready`, `error`
+- **权限状态**: `funPermission`, `dataPermission`
+- **选中状态**: `selectedRowsID`, `selectedIds`
+- **树形状态**: `treeExpandedAll`, `treeExpandState`（树形模式）
+
+### 布局结构
+
+组件采用 `EntityGridLayout` 进行布局管理，包含三个主要区域：
+
+1. **entityGridHeader**: 头部区域（搜索、SmartView、筛选、操作按钮）
+2. **entityGridBody**: 主体区域（表格/分屏/地图/BI 看板）
+3. **entityGridFooter**: 底部区域（分页、汇总等）
+
+## 主要属性说明
+
+### 基础属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `objectApiKey` | `string` | - | 实体的 ApiKey（必填） |
+| `name` | `string` | - | 组件名称，用于 amis 通信（必填） |
+| `pattern` | `string` | - | 使用模式：`entityView`/`pickView`/`simpleListView`/`globalSearchPage`/`secondaryList` |
+| `height` | `string \| number` | `'100%'` | 组件高度 |
+| `className` | `string` | `''` | 自定义样式类名 |
+
+### 数据加载属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `dataLoadType` | `LOAD_TYPE` | - | 数据加载方式：`serverSide`/`clientSide`/`auto`/`pagination` |
+| `rowModelType` | `LOAD_TYPE` | - | AG-Grid 行模型类型 |
+| `cacheBlockSize` | `number` | - | 服务端模式下单次请求条数 |
+| `paginationPageSize` | `number` | - | 分页每页条数 |
+| `agGridDataSource` | `object` | - | 自定义数据源 |
+
+### 列表配置属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `withOrder` | `boolean` | `true` | 是否显示序号列 |
+| `withCheck` | `boolean` | `true` | 是否显示多选列 |
+| `editable` | `boolean` | `true` | 是否支持单元格编辑 |
+| `disableSearch` | `boolean` | `false` | 是否禁用搜索 |
+| `disableExport` | `boolean` | `false` | 是否禁用导出 |
+| `disablePagination` | `boolean` | `false` | 是否禁用分页 |
+| `selectionMode` | `'single' \| 'multiple'` | - | 选择模式（Picker 下默认 single） |
+
+### 事件回调属性
+
+| 属性名 | 类型 | 说明 |
+|--------|------|------|
+| `onRowSelected` | `(data, event) => void` | 行选中变化回调 |
+| `onRecordChange` | `(data) => void` | 行数据变化回调 |
+| `onGridReady` | `(gridModel) => void` | 表格就绪回调 |
+| `onFirstDataRendered` | `() => void` | 首次数据渲染完成回调 |
+| `onDataLoaded` | `(data) => void` | 数据加载完成回调 |
+| `onDataRequest` | `(store) => void` | 数据请求前回调（可修改请求参数） |
+| `onLayoutLoaded` | `(data) => void` | 布局加载完成回调 |
+| `onLoadedDataComplete` | `(payload) => void` | 布局数据加载完成回调 |
+| `onSmartViewChanged` | `(data) => void` | SmartView 切换回调 |
+| `onSinglerClick` | `(clickData) => boolean` | 单击行拦截（返回 true 拦截默认逻辑） |
+| `interceptClick` | `(clickData, options) => boolean` | 详情打开前拦截 |
+
+### 扩展属性（HOC_PROPS）
+
+| 属性名 | 类型 | 说明 |
+|--------|------|------|
+| `batchButtons` | `array` | 批量操作按钮配置 |
+| `entityButtons` | `array` | 列表操作按钮配置 |
+| `shortcutButtons` | `array` | 快捷操作按钮配置 |
+| `referData` | `object` | Picker 相关数据 |
+| `selectedIds` | `array` | Picker 默认选中数据 |
+| `searchCondition` | `object` | 初始搜索条件 |
+| `additionalConditions` | `array` | 附加筛选条件 |
+| `customToolbarButtons` | `array` | 自定义工具栏按钮 |
+| `treeData` | `boolean` | 是否启用树形模式 |
+| `treeParentIdField` | `string` | 树形父ID字段名 |
+| `treeInitialLoadCount` | `number` | 树形每层初始加载数量 |
+| `treeLoadMoreCount` | `number` | 树形加载更多数量 |
+
+### 其他属性
+
+| 属性名 | 类型 | 说明 |
+|--------|------|------|
+| `pageInfo` | `object` | 页面信息，用于注册刷新方法 |
+| `footerBlock` | `object` | 底部操作区配置 |
+| `headerBlock` | `object` | 头部扩展配置 |
+| `noPermission` | `ReactNode \| Function` | 无权限时展示内容 |
+| `customEmptyMsg` | `string` | 自定义空数据提示 |
+| `scene` | `string` | 场景标识（如 `standard`） |
+
+## 生命周期方法
+
+### componentWillMount（amis 包装层）
+
+```typescript
+componentWillMount() {
+  const scoped = this.context as IScopedContext
+  scoped.registerComponent(this)
+}
+```
+
+- **作用**: 注册组件到 amis 的 ScopedContext
+- **时机**: 组件挂载前
+
+### constructor
+
+```typescript
+constructor(options) {
+  // 1. 解析 URL 参数（urlConditions, urlExpression, canCreate, canEdit）
+  // 2. 多页签模式下初始化 DataStore 和导航栏刷新方法
+  // 3. 初始化 NexManager
+  // 4. 调用 store.initGrid 初始化 Store
+  // 5. 创建 EntityGridLayout 布局
+  // 6. 如有 pageInfo，创建 EntityGridPageCom 并注册刷新方法
+}
+```
+
+### componentDidMount
+
+```typescript
+componentDidMount() {
+  // 1. 监听 customEventBus（cell_save, cell_cancel, refresh_grid）
+  // 2. 监听 onSlideChanged 事件
+  // 3. 监听 compositionstart/compositionend（中文输入法）
+  // 4. 监听 document click（清除详情行高亮）
+  // 5. 设置 __com__ 的 context
+  // 6. Safari 浏览器添加 is-safari 类名
+}
+```
+
+### componentDidUpdate
+
+```typescript
+componentDidUpdate() {
+  // 根据 store.aggridModel?.cellEditing 动态添加/移除 neo-entity-view-cell-editing 类名
+}
+```
+
+### componentWillUnmount
+
+```typescript
+componentWillUnmount() {
+  // 1. 移除所有事件监听
+  // 2. 清空 entityGridLayout 引用
+  // 3. 销毁 nexObj
+  // 4. 多页签模式下清理 neoStore
+}
+```
+
+## 核心方法详解
+
+### 初始化方法
+
+#### createLayout()
+
+创建布局结构：
+
+```typescript
+createLayout = () => {
+  let entityGridLayout = {
+    grids: [
+      { type: 'entityGridHeader', name: 'entityGridHeader', ... },
+      { nameSpace: 'entityGridBody' },
+      { type: 'entityGridFooter', name: 'entityGridFooter', ... }
+    ]
+  }
+  // 支持 neoLayout 合并自定义布局
+  if (neoLayout) {
+    entityGridLayout = EntityGridLayout.commonMerge(neoLayout, entityGridLayout)
+  }
+  this.entityGridLayout = new EntityGridLayout(entityGridLayout)
+}
+```
+
+#### resetGrid(props)
+
+重置整个列表（刷新页面时使用）：
+
+```typescript
+resetGrid = (props) => {
+  this._hasDetailRowHighlight = false
+  store.clearStatus()
+  store.initGrid(props, this.t0)
+  this.nexObj.getInstance().getRef('header').clear()
+}
+```
+
+### 点击处理方法
+
+#### onLinkSingerClick(clickData)
+
+单击行处理逻辑：
+
+1. 堆叠视图模式下关闭所有弹框
+2. 若配置 `openDetailInNewTab` 则走双击逻辑
+3. Picker 模式：调用 `bridge?.detailOpenNew`
+4. 多页签模式：`NeoNavigator.openEntityDetail` 新页签打开
+5. 侧滑模式：`NeoNavigator.openEntityDetail` 抽屉打开
+6. 根据 `layoutMode` 决定抽屉全屏/80%
+
+#### onLinkDoubleClick(clickData)
+
+双击行处理逻辑：新页签或新窗口打开详情页。
+
+### 视图切换方法
+
+#### getGridView()
+
+获取可用视图列表（列表、分屏、地图、BI 看板、自定义视图）：
+
+```typescript
+getGridView = () => {
+  const views = []
+  if (store.biListVisible) { views.push({ component: biBoard, ... }) }
+  if (store.splitListVisible) { views.push({ component: splitView, ... }) }
+  if (store.mapListVisible) { views.push({ component: mapView, ... }) }
+  if (customViews({ store }).length > 0) { views.push(...customViews) }
+  if (views.length > 0) { views.unshift({ component: list, ... }) }
+  return views
+}
+```
+
+#### addGridBody(component)
+
+向 body 区域添加视图组件。
+
+### 指令方法（cmd_*）
+
+组件通过 `receive` 接收 amis 指令，支持以下 cmd：
+
+| 指令 | 说明 |
+|------|------|
+| `cmd_refresh_grid` | 刷新列表数据 |
+| `cmd_refresh_singleData` | 刷新单行数据 |
+| `cmd_cell_save` | 单元格保存 |
+| `cmd_cancel_edit` | 取消编辑 |
+| `cmd_batch_save` | 批量保存 |
+| `cmd_picker_sure` | Picker 确定 |
+| `cmd_picker_close` | Picker 关闭 |
+| `cmd_close` | 关闭页面 |
+
+### 树形模式方法
+
+#### getTreeExpandButton()
+
+获取树形模式下的「展开全部」「收起全部」按钮配置。
+
+## 使用示例
+
+### 示例 1: 基础大列表（amis Schema）
+
+```typescript
+import { NeoRenderer } from 'neo-ui-common'
+
+// 通过 amis Schema 渲染
+<NeoRenderer
+  schema={{
+    type: 'page',
+    body: [
+      {
+        type: 'entityGrid',
+        name: 'listviewx',
+        objectApiKey: 'account',
+        height: '100%',
+        pageInfo: {
+          pageKey: 'entityGrid',
+          scope: { objectApiKey: 'account' }
+        }
+      }
+    ]
+  }}
+/>
+```
+
+### 示例 2: NeoEntityGrid 标准组件（表单设计器）
+
+```typescript
+import NeoEntityGrid from '@/components/GenBizComp/NeoEntityGrid'
+
+<NeoEntityGrid
+  objectApiKey="account"
+  showView={true}
+  enableChangeView={true}
+  defaultViewId="default_view"
+  additionalConditions={[]}
+  paginationPageSize={10}
+  enableSearch={true}
+  enableHeaderOptions={true}
+  withOrder={true}
+  enableToolbar={true}
+  canEdit={true}
+  onRecordChange={(data) => console.log('数据变化', data)}
+/>
+```
+
+### 示例 3: Picker 列表（选择器）
+
+```typescript
+{
+  type: 'entityGrid',
+  name: 'pickerList',
+  objectApiKey: 'contact',
+  pattern: 'pickView',
+  height: '100%',
+  selectionMode: 'multiple',
+  referData: {
+    referItemId: 'xxx',
+    referItemApiKey: 'accountId'
+  },
+  onSelectedCall: (selectedData) => {
+    console.log('选中的数据', selectedData)
+  },
+  shouldCloseDialog: true
+}
+```
+
+### 示例 4: 二级列表（详情页相关列表）
+
+```typescript
+{
+  type: 'entityGrid',
+  name: 'listviewx',
+  objectApiKey: 'opportunity',
+  pattern: 'secondaryList',
+  height: '100%',
+  isViewList: true,
+  data: { entityId: 123 },
+  onDataRequest: (store) => {
+    store.setCustomCondition([
+      { item: 456, type: 10, value: detailId }
+    ])
+  },
+  footerBlock: {
+    actions: {
+      type: 'button-group',
+      target: 'listviewx',
+      buttons: [
+        { type: 'action', actionType: 'reload', label: '取消', target: 'listviewx?cmd=cancel_edit' },
+        { type: 'action', actionType: 'reload', label: '保存', target: 'listviewx?cmd=batch_save' }
+      ]
+    }
+  }
+}
+```
+
+### 示例 5: 自定义筛选条件
+
+```typescript
+{
+  type: 'entityGrid',
+  name: 'listviewx',
+  objectApiKey: 'account',
+  additionalConditions: [
+    { item: 123, type: 1, value: 'active' }
+  ],
+  onDataRequest: (store) => {
+    // 动态设置额外条件
+    store.setCustomCondition([
+      { item: 456, type: 10, value: [1, 2, 3] }
+    ])
+  }
+}
+```
+
+### 示例 6: 树形列表
+
+```typescript
+{
+  type: 'entityGrid',
+  name: 'listviewx',
+  objectApiKey: 'order',
+  treeData: true,
+  treeParentIdField: 'parentId',
+  treeInitialLoadCount: 50,
+  treeLoadMoreCount: 20
+}
+```
+
+### 示例 7: 扩展配置（Nex 2.0）
+
+```typescript
+{
+  type: 'entityGrid',
+  name: 'listviewx',
+  objectApiKey: 'account',
+  nexVersion: 2,
+  entityList: {
+    openDetailInNewTab: true,
+    disableSearch: false,
+    dataList: {
+      beforeFieldRender: (event) => {
+        // 字段渲染前处理
+        return null
+      }
+    },
+    listButton: [
+      {
+        apiKey: 'customBtn',
+        label: '自定义按钮',
+        onClick: (event) => console.log(event)
+      }
+    ]
+  }
+}
+```
+
+### 示例 8: 完整配置示例
+
+```typescript
+{
+  type: 'entityGrid',
+  name: 'accountList',
+  objectApiKey: 'account',
+  height: '100%',
+  pattern: 'entityView',
+  scene: 'standard',
+  
+  // 数据配置
+  rowModelType: 'serverSide',
+  dataLoadType: 'serverSide',
+  paginationPageSize: 20,
+  
+  // 功能配置
+  withOrder: true,
+  withCheck: true,
+  editable: true,
+  disableSearch: false,
+  disableExport: false,
+  
+  // 事件回调
+  onRowSelected: (data, event) => console.log('选中', data),
+  onRecordChange: (data) => console.log('变更', data),
+  onGridReady: (gridModel) => console.log('就绪', gridModel),
+  onDataRequest: (store) => {
+    // 请求前可修改 store 状态
+  },
+  
+  // 底部操作
+  footerBlock: {
+    actions: {
+      type: 'button-group',
+      target: 'accountList',
+      buttons: [
+        { type: 'action', actionType: 'reload', label: '取消', target: 'accountList?cmd=cancel_edit' },
+        { type: 'action', actionType: 'reload', label: '保存', target: 'accountList?cmd=batch_save' }
+      ]
+    }
+  },
+  
+  // 页面刷新
+  pageInfo: {
+    pageKey: 'entityGrid',
+    scope: { objectApiKey: 'account' }
+  }
+}
+```
+
+## 扩展机制
+
+### Nex 1.0 扩展
+
+通过 `nexVersion: 1` 或默认，主要扩展点：
+
+- `entityList.dataList.fields`: 字段扩展
+- `entityList.dataList.onColumnResized`: 列宽变化
+- `entityList.buttonGroup.actions`: 列表按钮
+- `entityList.bulkButtonGroup.actions`: 批量操作按钮
+- `entityList.listViews.disableLeftCustomView`: 禁用自定义视图
+
+### Nex 2.0 扩展
+
+通过 `nexVersion: 2`，主要扩展点：
+
+- `entityList.dataList`: listItem、beforeFieldRender
+- `entityList.listButton`: 列表按钮（事件形式）
+- `entityList.multiButton`: 批量操作按钮（事件形式）
+- `entityList.listViews`: 视图配置
+- `entityList.openDetailInNewTab`: 详情在新页签打开
+
+### HOC 扩展
+
+通过 `HOC_PROPS` 和 `ExtGet` 透传业务线扩展：
+
+```typescript
+// 业务线通过 ExtGet 获取扩展配置
+store.ExtGet('treeData')
+store.ExtGet('customToolbarButtons')
+store.ExtGet('onDataRequest')
+```
+
+### 指令调用
+
+通过 amis 的 target 机制调用组件方法：
+
+```typescript
+// 刷新列表
+target: 'listviewx?cmd=refresh_grid'
+
+// 批量保存
+target: 'listviewx?cmd=batch_save'
+
+// 取消编辑
+target: 'listviewx?cmd=cancel_edit'
+```
+
+## 注意事项
+
+### 1. Store 初始化
+
+- Store 由 amis 框架根据 `storeType: EntityGridStore.name` 自动创建
+- 无需手动创建 Store 实例
+
+### 2. 模式区分
+
+- `pattern='entityView'`: 标准大列表
+- `pattern='pickView'`: Picker 选择器
+- `pattern='secondaryList'`: 二级/相关列表
+- `pattern='globalSearchPage'`: 全局搜索结果列表
+
+### 3. 必传参数
+
+- **所有模式**: `objectApiKey`、`name`
+- **Picker**: `referData`、`onSelectedCall`
+- **二级列表**: `onDataRequest` 中设置 `setCustomCondition`
+
+### 4. 树形模式
+
+- 需显式设置 `treeData: true`
+- 支持 `treeParentIdField`、`treeInitialLoadCount`、`treeLoadMoreCount` 等配置
+- 超过 1000 条时「展开全部」按钮禁用
+
+### 5. 性能优化
+
+- 服务端模式（serverSide）适合大数据量
+- 客户端模式（clientSide）适合小数据量
+- `rowModelType: 'auto'` 会根据数据量自动切换
+
+### 6. 多页签集成
+
+- 传入 `pageInfo` 可注册 `refreshPage`、`refreshData` 等刷新方法
+- 通过 `NeoApp.openPageCom` 获取页面 Com 实例
+
+## 常见问题
+
+### Q1: 如何刷新列表数据？
+
+**A**: 通过指令或 Store 方法：
+
+```typescript
+// 方式1: amis 指令
+target: 'listviewx?cmd=refresh_grid'
+
+// 方式2: 通过 pageInfo 注册的 refreshData
+const pageCom = NeoApp.getPageCom('EntityGridPage.account')
+pageCom?.extApi?.refreshData()
+
+// 方式3: 直接调用 store（需获取 store 引用）
+store.reloadGrid(false)
+```
+
+### Q2: 如何拦截行点击打开详情？
+
+**A**: 使用 `onSinglerClick` 或 `interceptClick`：
+
+```typescript
+{
+  type: 'entityGrid',
+  onSinglerClick: (clickData) => {
+    // 自定义逻辑，返回 true 拦截默认打开详情
+    console.log('点击了', clickData)
+    return true
+  },
+  interceptClick: (clickData, { layoutMode, navigationType }) => {
+    // 更细粒度拦截，可获取 layoutMode 等
+    return false
+  }
+}
+```
+
+### Q3: 如何获取选中的数据？
+
+**A**: 通过 `onRowSelected` 回调或 Store：
+
+```typescript
+// 方式1: 回调
+onRowSelected: (selectedData, event) => {
+  const data = selectedData.map(({ data }) => data)
+  console.log('选中', data)
+}
+
+// 方式2: Store（需在 onGridReady 等时机获取）
+const selectedData = store.getSelectedData()
+```
+
+### Q4: 如何自定义空状态提示？
+
+**A**: 使用 `customEmptyMsg`：
+
+```typescript
+{
+  type: 'entityGrid',
+  customEmptyMsg: '暂无数据，请先创建'
+}
+```
+
+### Q5: 如何禁用某些功能？
+
+**A**: 使用对应的禁用属性：
+
+```typescript
+{
+  type: 'entityGrid',
+  disableSearch: true,
+  disableExport: true,
+  disablePagination: true,
+  withOrder: false,
+  withCheck: false,
+  editable: false
+}
+```
+
+### Q6: Picker 模式如何获取选中结果？
+
+**A**: 使用 `onSelectedCall` 回调：
+
+```typescript
+{
+  type: 'entityGrid',
+  pattern: 'pickView',
+  onSelectedCall: (selectedData) => {
+    // selectedData 为选中的记录数组
+    console.log(selectedData)
+    closeDialog()
+  },
+  shouldCloseDialog: true  // 选择后是否关闭弹窗
+}
+```
+
+### Q7: 如何添加自定义工具栏按钮？
+
+**A**: 使用 `customToolbarButtons`（业务线扩展）：
+
+```typescript
+{
+  type: 'entityGrid',
+  customToolbarButtons: [
+    {
+      key: 'customBtn',
+      label: '自定义',
+      icon: 'custom-icon',
+      onClick: () => console.log('clicked')
+    }
+  ]
+}
+```
+
+### Q8: 树形列表如何配置？
+
+**A**: 设置 `treeData` 及相关属性：
+
+```typescript
+{
+  type: 'entityGrid',
+  treeData: true,
+  treeParentIdField: 'parentId',
+  treeInitialLoadCount: 50,
+  treeLoadMoreCount: 20
+}
+```
+
+### Q9: 如何自定义详情打开方式？
+
+**A**: 通过 Nex 扩展 `openDetailInNewTab`：
+
+```typescript
+{
+  type: 'entityGrid',
+  nexVersion: 2,
+  entityList: {
+    openDetailInNewTab: true  // 单击也在新页签打开
+  }
+}
+```
+
+### Q10: 无权限时如何自定义展示？
+
+**A**: 使用 `noPermission`：
+
+```typescript
+{
+  type: 'entityGrid',
+  noPermission: () => <div>您没有权限查看此列表</div>
+}
+// 或
+noPermission: <NoPermissionComponent />
+```
+
+## 总结
+
+`EntityGrid` 是 Web 端功能强大的列表组件，基于 AG-Grid 提供了完整的数据展示、筛选、排序、批量操作、单元格编辑、多视图切换等功能。通过 amis Schema 配置即可使用，支持 Nex 扩展和 HOC 透传满足业务线定制需求。
+
+在使用时需要注意：
+
+1. 正确设置 `objectApiKey` 和 `name`
+2. 根据业务场景选择合适的 `pattern`
+3. 合理使用 `onDataRequest` 设置筛选条件
+4. 树形模式需显式开启 `treeData`
+5. 通过 `pageInfo` 集成多页签刷新能力
+
+更多详细信息请参考组件源码和 Store 定义。