@lonersyk/record-grid 1.0.29 → 1.0.31

package/README.md

@@ -74,6 +74,39 @@ RecordGrid.initialize({
 
 ### 2. 使用组件
 
+**方式一：使用 RecordGridServiceProvider（推荐，支持多实例）**
+
+```javascript
+import RecordGrid, { RecordGridServiceProvider } from '@streams/record-grid'
+import '@streams/record-grid/dist/index.css'
+import * as DataService from './services/DataService'
+
+function MyComponent() {
+  const authService = {
+    check: (auth) => authInfo?.check?.(auth),
+    userInfo: () => userInfo || {},
+    getAppInfo: () => appInfo
+  }
+
+  return (
+    <RecordGridServiceProvider
+      dataService={DataService}
+      authService={authService}
+    >
+      <div style={{ height: '600px' }}>
+        <RecordGrid
+          subjectName="your-subject-name"
+          pagination={true}
+          readonly={false}
+        />
+      </div>
+    </RecordGridServiceProvider>
+  )
+}
+```
+
+**方式二：全局初始化（适用于单实例场景）**
+
 ```javascript
 import RecordGrid from '@streams/record-grid'
 import '@streams/record-grid/dist/index.css'
@@ -181,8 +214,44 @@ export async function importRecords(subject, records) {
 | actions | `object` | `{}` | 自定义事件处理 |
 | useFrontView | `boolean \| object` | `false` | 前端视图模式 |
 | filterView | `array` | `[]` | 过滤视图 |
-| displayConfig | `object` | `{}` | 显示配置 |
+| displayConfig | `object` | `{}` | 显示配置（见下方说明） |
 | authApp | `string` | - | 权限应用名 |
+| quickSelect | `boolean` | `false` | 快速选择模式，开启后引用字段可直接在单元格内选择 |
+| autoExpandGroups | `boolean` | `false` | 是否在首次加载和刷新后自动展开所有分组 |
+| useClientSide | `boolean` | `false` | 客户端模式，数据在客户端处理 |
+| useCustomSidebar | `boolean \| object` | `false` | 自定义侧边栏配置 |
+| useCustomContextMenu | `boolean \| object` | `false` | 自定义右键菜单 |
+| useCustomOperation | `boolean \| object` | `false` | 自定义操作栏 |
+| tabBarRightSlot | `function` | - | 标签栏右侧插槽，接收 `(gridApi) => ReactNode` |
+| toolBarRightSlot | `function` | - | 工具栏右侧插槽，接收 `(gridApi) => ReactNode` |
+| extraTheme | `object` | `{}` | 主题定制配置 |
+| recordDetailRenderer | `function` | - | 自定义记录详情渲染器 |
+| documentDetailRenderer | `function` | - | 自定义文档详情渲染器 |
+| columnRenderers | `object` | `{}` | 列自定义渲染器映射 `{ fieldName: renderFunction }` |
+| detailGridColumnRenderers | `object` | `{}` | 详情抽屉中的多维表格专用列渲染器 |
+| components | `object` | `{}` | 组件映射（兼容 columnRenderers 的别名） |
+| extraFilters | `array` | `[]` | 额外的过滤条件，支持 MongoDB aggregation stages 数组 |
+
+### displayConfig 配置
+
+```javascript
+{
+  maxTagCount: 3,        // 标签字段最多显示的标签数量，超出部分显示 "+N"
+  maxAvatarCount: 5      // 用户/引用字段最多显示的头像数量，超出部分显示 "+N"
+}
+```
+
+示例：
+
+```javascript
+<RecordGrid
+  subjectName="your-subject"
+  displayConfig={{
+    maxTagCount: 10,
+    maxAvatarCount: 10
+  }}
+/>
+```
 
 ### readonly 配置
 
@@ -271,6 +340,109 @@ export async function importRecords(subject, records) {
 />
 ```
 
+### 使用权限服务（authService）
+
+权限服务用于控制字段编辑权限和视图访问权限。可以通过 `RecordGridServiceProvider` 传入：
+
+```javascript
+import { RecordGridServiceProvider } from '@streams/record-grid'
+
+const authService = {
+  // 权限检查函数
+  check: (auth) => {
+    // auth 可能是字符串（如 '管理'）或对象（如 { role: '成员' }）
+    // 返回 true/false
+    return authInfo?.check?.(auth)
+  },
+  
+  // 用户信息（可以是对象或函数）
+  userInfo: () => ({
+    username: 'user',
+    type: 'admin',  // 'admin' 或 'system' 时，字段权限设置按钮可用
+    display_name: '用户名'
+  }),
+  
+  // 获取应用信息（用于权限设置弹窗）
+  getAppInfo: async () => ({
+    members: [],      // 用户组列表
+    roles: [],        // 角色列表
+    permissions: []   // 权限列表
+  })
+}
+
+<RecordGridServiceProvider
+  dataService={DataService}
+  authService={authService}
+>
+  <RecordGrid subjectName="your-subject" />
+</RecordGridServiceProvider>
+```
+
+**重要说明**：
+- `userInfo.type` 为 `'admin'` 或 `'system'` 时，字段和视图的"权限设置"按钮才会启用
+- `getAppInfo` 返回的数据用于权限设置弹窗中的选项
+
+### 自定义列渲染器
+
+```javascript
+<RecordGrid
+  subjectName="your-subject"
+  columnRenderers={{
+    // 为特定字段自定义渲染
+    'metadata.status': ({ value, data, field }) => {
+      return <Tag color={value === 'active' ? 'green' : 'red'}>{value}</Tag>
+    },
+    'metadata.workflow': ({ value, data, field }) => {
+      // 自定义工作流渲染逻辑
+      return <CustomWorkflowDisplay value={value} />
+    }
+  }}
+  // 或者使用 components（与 columnRenderers 等价）
+  components={{
+    'metadata.status': StatusRenderer
+  }}
+/>
+```
+
+### 详情抽屉中的列渲染器
+
+```javascript
+<RecordGrid
+  subjectName="your-subject"
+  detailGridColumnRenderers={{
+    // 详情抽屉中的多维表格使用不同的渲染器
+    'metadata.workflow': ({ value, data, field }) => {
+      return (
+        <>
+          {(!data.metadata?.status || data.metadata.status === 'new') && (
+            <>{renderTagStatus('unstarted')}</>
+          )}
+          {data.metadata.status === 'completed' && (
+            <>{renderTagStatus('completed')}</>
+          )}
+          {data.metadata.status === 'in_progress' && (
+            <>{renderTagStatus('inprogress', data.metadata.workflow_data?.[(data.metadata.step * 1 || 1) - 1].title)}</>
+          )}
+        </>
+      )
+    }
+  }}
+/>
+```
+
+### 使用额外过滤条件
+
+```javascript
+<RecordGrid
+  subjectName="your-subject"
+  extraFilters={[
+    // MongoDB aggregation stages
+    { $match: { 'metadata.status': 'active' } },
+    { $lookup: { /* ... */ } }
+  ]}
+/>
+```
+
 ### 获取选中行
 
 ```javascript
@@ -355,6 +527,35 @@ A: 在 v2.0.0+ 版本中，`@tanstack/react-query` 已经打包进 dist，不需
 2. 清理缓存：`rm -rf node_modules/.cache && rm -rf .umi`
 3. 重新安装：`npm install @streams/record-grid`
 
+### Q: 字段权限设置按钮一直是灰色的
+
+A: 权限设置按钮需要管理员权限才能使用。
+
+**原因**：
+- `authService.userInfo.type` 必须是 `'admin'` 或 `'system'`
+- 如果 `userInfo` 是函数，需要返回包含 `type` 字段的对象
+
+**解决方案**：
+
+```javascript
+const authService = {
+  check: (auth) => authInfo?.check?.(auth),
+  userInfo: () => ({
+    username: 'user',
+    type: 'admin',  // 必须是 'admin' 或 'system'
+    // ... 其他字段
+  }),
+  getAppInfo: () => appInfo
+}
+
+<RecordGridServiceProvider
+  dataService={DataService}
+  authService={authService}
+>
+  <RecordGrid subjectName="your-subject" />
+</RecordGridServiceProvider>
+```
+
 ### Q: 使用 Gantt 视图报错或显示空白
 
 A: **从 v2.0.0 开始，Gantt 功能改为可选模式！**