@nocobase/flow-engine 2.0.0-alpha.9 → 2.0.0-beta.2

package/src/utils/__tests__/jsxTransform.test.ts

@@ -0,0 +1,38 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { compileRunJs } from '../../utils/jsxTransform';
+
+describe('compileRunJs', () => {
+  it('returns original code when no JSX is present', async () => {
+    const src = `const a = 1; const b = a + 1;`;
+    const out = await compileRunJs(src);
+    expect(out).toBe(src);
+  });
+
+  it('transforms JSX when sucrase is available (skip if missing)', async () => {
+    const src = `ctx.render(<div className="x">hi</div>);`;
+
+    // Try to import sucrase to decide if this environment has it installed
+    const hasSucrase = await import('sucrase').then(() => true).catch(() => false);
+
+    const out = await compileRunJs(src);
+
+    if (!hasSucrase) {
+      // Environment without sucrase: current implementation falls back to original code
+      expect(out).toBe(src);
+      return;
+    }
+
+    // sucrase available: output should contain React.createElement mapping
+    expect(out).not.toBe(src);
+    expect(out).toMatch(/ctx\.React\.createElement/);
+  });
+});

package/src/utils/__tests__/parsePathnameToViewParams.test.ts

@@ -101,4 +101,29 @@ describe('parsePathnameToViewParams', () => {
     const result = parsePathnameToViewParams('///admin//xxx//tab//yyy//');
     expect(result).toEqual([{ viewUid: 'xxx', tabUid: 'yyy' }]);
   });
+
+  test('should parse filterByTk from key-value encoded segment into object', () => {
+    const kv = encodeURIComponent('id=1&tenant=ac');
+    const path = `/admin/xxx/filterbytk/${kv}`;
+    const result = parsePathnameToViewParams(path);
+    expect(result).toEqual([{ viewUid: 'xxx', filterByTk: { id: '1', tenant: 'ac' } }]);
+  });
+
+  test('should parse filterByTk from JSON object segment', () => {
+    const json = encodeURIComponent('{"id":"1","tenant":"ac"}');
+    const path = `/admin/xxx/filterbytk/${json}`;
+    const result = parsePathnameToViewParams(path);
+    expect(result).toEqual([{ viewUid: 'xxx', filterByTk: { id: '1', tenant: 'ac' } }]);
+  });
+
+  test('should keep non-object JSON (array/number) as string for filterByTk', () => {
+    const arr = encodeURIComponent('["a"]');
+    const num = encodeURIComponent('123');
+    const t = encodeURIComponent('true');
+    expect(parsePathnameToViewParams(`/admin/xxx/filterbytk/${arr}`)).toEqual([
+      { viewUid: 'xxx', filterByTk: '["a"]' },
+    ]);
+    expect(parsePathnameToViewParams(`/admin/xxx/filterbytk/${num}`)).toEqual([{ viewUid: 'xxx', filterByTk: '123' }]);
+    expect(parsePathnameToViewParams(`/admin/xxx/filterbytk/${t}`)).toEqual([{ viewUid: 'xxx', filterByTk: 'true' }]);
+  });
 });

package/src/utils/__tests__/pruneFilter.test.ts

@@ -0,0 +1,38 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { pruneFilter } from '../pruneFilter';
+
+describe('pruneFilter', () => {
+  it('keeps boolean false and number 0', () => {
+    const input = { a: { $eq: false }, b: { $eq: 0 } };
+    const out = pruneFilter(input);
+    expect(out).toEqual(input);
+  });
+
+  it('removes null/undefined/empty string and empty containers', () => {
+    const input = { a: null, b: undefined, c: '', d: [], e: {} } as any;
+    const out = pruneFilter(input);
+    expect(out).toBeUndefined();
+  });
+
+  it('works recursively with nested objects/arrays', () => {
+    const input = {
+      $and: [{ isRead: { $eq: false } }, { name: { $eq: '' } }, {}, [], { nested: { empty: {}, ok: 1 } }],
+    } as any;
+    const out = pruneFilter(input);
+    expect(out).toEqual({ $and: [{ isRead: { $eq: false } }, { nested: { ok: 1 } }] });
+  });
+
+  it('returns undefined for empty arrays/objects produced by pruning', () => {
+    expect(pruneFilter([null, undefined, '', [], {}] as any)).toBeUndefined();
+    expect(pruneFilter({ a: { b: '' } } as any)).toBeUndefined();
+  });
+});

package/src/utils/__tests__/safeGlobals.test.ts

@@ -8,7 +8,7 @@
  */
 
 import { describe, expect, it } from 'vitest';
-import { createSafeDocument, createSafeWindow } from '../safeGlobals';
+import { createSafeDocument, createSafeWindow, createSafeNavigator } from '../safeGlobals';
 
 describe('safeGlobals', () => {
   it('createSafeWindow exposes only allowed globals and extras', () => {
@@ -16,6 +16,7 @@ describe('safeGlobals', () => {
     expect(typeof win.setTimeout).toBe('function');
     expect(win.console).toBeDefined();
     expect(win.foo).toBe(123);
+    expect(new win.FormData()).toBeInstanceOf(window.FormData);
     // access to location proxy is allowed, but sensitive props throw
     expect(() => win.location.href).toThrow(/not allowed/);
   });
@@ -26,4 +27,25 @@ describe('safeGlobals', () => {
     expect(doc.bar).toBe(true);
     expect(() => doc.cookie).toThrow(/not allowed/);
   });
+
+  it('createSafeNavigator exposes limited props and guards others', () => {
+    const nav: any = createSafeNavigator();
+    // clipboard object should always exist
+    expect(typeof nav.clipboard).toBe('object');
+    // writeText may or may not exist depending on environment
+    if (typeof navigator !== 'undefined' && (navigator as any).clipboard?.writeText) {
+      expect(typeof nav.clipboard.writeText).toBe('function');
+    } else {
+      expect(typeof nav.clipboard.writeText === 'undefined' || typeof nav.clipboard.writeText === 'function').toBe(
+        true,
+      );
+    }
+    // readable properties
+    expect(() => void nav.onLine).not.toThrow();
+    expect(() => void nav.language).not.toThrow();
+    expect(() => void nav.languages).not.toThrow();
+    // blocked properties
+    expect(() => (nav as any).geolocation).toThrow(/not allowed/);
+    expect(() => (nav as any).userAgent).toThrow(/not allowed/);
+  });
 });

package/src/utils/__tests__/utils.test.ts

@@ -13,6 +13,7 @@ import {
   isInheritedFrom,
   resolveDefaultParams,
   resolveStepUiSchema,
+  shouldHideStepInSettings,
   FlowExitException,
   defineAction,
   compileUiSchema,
@@ -30,6 +31,7 @@ import type {
   StepDefinition,
 } from '../../types';
 import { FlowRuntimeContext } from '../../flowContext';
+import { ContextPathProxy } from '../../ContextPathProxy';
 
 // Helper functions
 const createMockFlowEngine = (): FlowEngine => {
@@ -996,26 +998,123 @@ describe('Utils', () => {
 
         consoleSpy.mockRestore();
       });
+    });
+  });
 
-      test('should handle missing getAction method', async () => {
-        // Mock a flowEngine without getAction method
-        const originalGetAction = mockModel.flowEngine.getAction;
-        mockModel.flowEngine.getAction = undefined;
+  // ==================== shouldHideStepInSettings() FUNCTION ====================
+  describe('shouldHideStepInSettings()', () => {
+    let mockFlow: any;
+    let mockStep: StepDefinition;
 
-        mockStep.use = 'testAction';
-        mockStep.uiSchema = {
-          field1: { type: 'string', title: 'Field 1' },
-        };
+    beforeEach(() => {
+      mockFlow = {
+        key: 'testFlow',
+        title: 'Test Flow',
+        steps: {},
+      };
 
-        const result = await resolveStepUiSchema(mockModel, mockFlow, mockStep);
+      mockStep = {
+        key: 'testStep',
+        handler: vi.fn(),
+      };
+    });
 
-        expect(result).toEqual({
-          field1: { type: 'string', title: 'Field 1' },
-        });
+    test('returns true when step is falsy', async () => {
+      const result = await shouldHideStepInSettings(mockModel, mockFlow, null);
+      expect(result).toBe(true);
+    });
 
-        // Restore the original method
-        mockModel.flowEngine.getAction = originalGetAction;
-      });
+    test('respects static step.hideInSettings=true', async () => {
+      mockStep.hideInSettings = true;
+
+      const result = await shouldHideStepInSettings(mockModel, mockFlow, mockStep);
+      expect(result).toBe(true);
+    });
+
+    test('respects static step.hideInSettings=false', async () => {
+      mockStep.hideInSettings = false;
+
+      const result = await shouldHideStepInSettings(mockModel, mockFlow, mockStep);
+      expect(result).toBe(false);
+    });
+
+    test('falls back to action.hideInSettings when step.hideInSettings is undefined', async () => {
+      const action: ActionDefinition = {
+        name: 'testAction',
+        handler: vi.fn(),
+        hideInSettings: true,
+      } as any;
+
+      mockStep.use = 'testAction';
+      mockModel.flowEngine.getAction = vi.fn().mockReturnValue(action);
+
+      const result = await shouldHideStepInSettings(mockModel, mockFlow, mockStep);
+      expect(mockModel.flowEngine.getAction).toHaveBeenCalledWith('testAction');
+      expect(result).toBe(true);
+    });
+
+    test('prefers step.hideInSettings over action.hideInSettings', async () => {
+      const action: ActionDefinition = {
+        name: 'testAction',
+        handler: vi.fn(),
+        hideInSettings: true,
+      } as any;
+
+      mockStep.use = 'testAction';
+      mockStep.hideInSettings = false;
+      mockModel.flowEngine.getAction = vi.fn().mockReturnValue(action);
+
+      const result = await shouldHideStepInSettings(mockModel, mockFlow, mockStep);
+      expect(result).toBe(false);
+    });
+
+    test('evaluates function step.hideInSettings with FlowRuntimeContext', async () => {
+      const hideFn = vi.fn().mockResolvedValue(true);
+      mockStep.hideInSettings = hideFn as any;
+
+      const result = await shouldHideStepInSettings(mockModel, mockFlow, mockStep);
+
+      expect(hideFn).toHaveBeenCalledTimes(1);
+      const ctx = hideFn.mock.calls[0][0] as FlowRuntimeContext;
+      expect(ctx).toBeInstanceOf(FlowRuntimeContext);
+      expect((ctx as any).model).toBe(mockModel);
+      expect((ctx as any).flowKey).toBe('testFlow');
+      expect((ctx as any).mode).toBe('settings');
+      expect((ctx as any).currentStep).toBeInstanceOf(ContextPathProxy);
+      expect(String((ctx as any).currentStep)).toBe('{{ctx.currentStep}}');
+      expect(result).toBe(true);
+    });
+
+    test('evaluates function action.hideInSettings when step.hideInSettings is undefined', async () => {
+      const hideFn = vi.fn().mockResolvedValue(false);
+      const action: ActionDefinition = {
+        name: 'testAction',
+        handler: vi.fn(),
+        hideInSettings: hideFn as any,
+      } as any;
+
+      mockStep.use = 'testAction';
+      mockModel.flowEngine.getAction = vi.fn().mockReturnValue(action);
+
+      const result = await shouldHideStepInSettings(mockModel, mockFlow, mockStep);
+
+      expect(hideFn).toHaveBeenCalledTimes(1);
+      const ctx = hideFn.mock.calls[0][0] as FlowRuntimeContext;
+      expect((ctx as any).currentStep).toBeInstanceOf(ContextPathProxy);
+      expect(String((ctx as any).currentStep)).toBe('{{ctx.currentStep}}');
+      expect(result).toBe(false);
+    });
+
+    test('returns false and logs warning when function hideInSettings throws', async () => {
+      const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const hideFn = vi.fn().mockRejectedValue(new Error('boom'));
+      mockStep.hideInSettings = hideFn as any;
+
+      const result = await shouldHideStepInSettings(mockModel, mockFlow, mockStep);
+
+      expect(consoleSpy).toHaveBeenCalled();
+      expect(result).toBe(false);
+      consoleSpy.mockRestore();
     });
   });
 });

package/src/utils/__tests__/variablesParams.test.ts

@@ -11,9 +11,11 @@ import { describe, expect, it } from 'vitest';
 import {
   collectContextParamsForTemplate,
   createRecordMetaFactory,
+  createRecordResolveOnServerWithLocal,
   inferParentRecordRef,
   inferRecordRef,
 } from '../variablesParams';
+import { FlowEngine, SingleRecordResource } from '../..';
 
 describe('variablesParams helpers', () => {
   it('inferRecordRef and inferParentRecordRef from FlowContext-like object', () => {
@@ -30,6 +32,29 @@ describe('variablesParams helpers', () => {
     expect(inferParentRecordRef(ctx)).toEqual({ collection: 'posts', dataSourceKey: 'main', filterByTk: 9 });
   });
 
+  it('inferRecordRef fallback to collection.getFilterByTK when resource has no filterByTk', () => {
+    const engine = new FlowEngine();
+    const ds = engine.context.dataSourceManager.getDataSource('main')!;
+    ds.addCollection({
+      name: 'users',
+      filterTargetKey: 'id',
+      fields: [
+        { name: 'id', type: 'integer', interface: 'number' },
+        { name: 'roles', type: 'belongsToMany', target: 'roles', interface: 'm2m' },
+      ],
+    });
+    const collection = ds.getCollection('users');
+    const resource = engine.context.createResource(SingleRecordResource);
+    resource.setResourceName('main.users');
+    // 不设置 filterByTk，模拟资源无 filter 时的 fallback
+    const ctx: any = engine.context;
+    ctx.defineProperty('resource', { value: resource });
+    ctx.defineProperty('collection', { value: collection });
+    ctx.defineProperty('record', { value: { id: 5 } });
+
+    expect(inferRecordRef(ctx)).toEqual({ collection: 'users', dataSourceKey: 'main', filterByTk: 5 });
+  });
+
   it('collectContextParamsForTemplate builds input for used variables only', async () => {
     const ctx: any = {
       getPropertyOptions: (k: string) => ({
@@ -49,4 +74,99 @@ describe('variablesParams helpers', () => {
     expect(res).toHaveProperty('record');
     expect(res).not.toHaveProperty('user');
   });
+
+  it('collectContextParamsForTemplate keeps associationName/sourceId from RecordRef', async () => {
+    const ctx: any = {
+      getPropertyOptions: (k: string) => ({
+        meta:
+          k === 'popup'
+            ? async () => ({
+                type: 'object',
+                title: 'Popup',
+                buildVariablesParams: () => ({
+                  record: {
+                    collection: 'posts',
+                    dataSourceKey: 'main',
+                    filterByTk: 1,
+                    associationName: 'users.posts',
+                    sourceId: 9,
+                  },
+                }),
+              })
+            : undefined,
+      }),
+    };
+
+    const tpl = { value: '{{ ctx.popup.record.id }}' } as any;
+    const res = await collectContextParamsForTemplate(ctx, tpl);
+    expect(res?.['popup.record']).toMatchObject({
+      collection: 'posts',
+      dataSourceKey: 'main',
+      filterByTk: 1,
+      associationName: 'users.posts',
+      sourceId: 9,
+    });
+  });
+
+  it('createRecordResolveOnServerWithLocal: no local record => always use server', () => {
+    const resolver = createRecordResolveOnServerWithLocal(
+      () => ({ name: 'posts', dataSourceKey: 'main' }) as any,
+      () => undefined,
+    );
+    expect(resolver('')).toBe(true);
+    expect(resolver('title')).toBe(true);
+    expect(resolver('author.name')).toBe(true);
+  });
+
+  it('createRecordResolveOnServerWithLocal: local record + non-association subpaths => use local', () => {
+    const collection: any = {
+      getField: (name: string) => {
+        if (name === 'id') return { name: 'id', isAssociationField: () => false };
+        if (name === 'title') return { name: 'title', isAssociationField: () => false };
+        return undefined;
+      },
+    };
+    const record = { id: 1, title: 'Hello' };
+    const resolver = createRecordResolveOnServerWithLocal(
+      () => collection,
+      () => record,
+    );
+    expect(resolver('')).toBe(false);
+    expect(resolver('id')).toBe(false);
+    expect(resolver('title')).toBe(false);
+  });
+
+  it('createRecordResolveOnServerWithLocal: association with local value => still use local', () => {
+    const collection: any = {
+      getField: (name: string) => {
+        if (name === 'author') return { name: 'author', isAssociationField: () => true };
+        if (name === 'title') return { name: 'title', isAssociationField: () => false };
+        return undefined;
+      },
+    };
+    const record = { title: 'Hello', author: { id: 1, name: 'Alice' } };
+    const resolver = createRecordResolveOnServerWithLocal(
+      () => collection,
+      () => record,
+    );
+    expect(resolver('author')).toBe(false);
+    expect(resolver('author.name')).toBe(false);
+  });
+
+  it('createRecordResolveOnServerWithLocal: association without local value => use server', () => {
+    const collection: any = {
+      getField: (name: string) => {
+        if (name === 'author') return { name: 'author', isAssociationField: () => true };
+        if (name === 'title') return { name: 'title', isAssociationField: () => false };
+        return undefined;
+      },
+    };
+    const record = { title: 'Hello', author: null };
+    const resolver = createRecordResolveOnServerWithLocal(
+      () => collection,
+      () => record,
+    );
+    expect(resolver('author')).toBe(true);
+    expect(resolver('author.name')).toBe(true);
+  });
 });

package/src/utils/associationObjectVariable.ts

@@ -0,0 +1,180 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import type { Collection, CollectionField } from '../data-source';
+import _ from 'lodash';
+import type { FlowContext, PropertyMeta, PropertyMetaFactory } from '../flowContext';
+import { createCollectionContextMeta } from './createCollectionContextMeta';
+
+/**
+ * 提取变量子路径的顶层字段名。
+ * 例如：
+ * - 'author.name'  => 'author'
+ * - 'tags[0].name' => 'tags'
+ *
+ * @param subPath 变量在对象中的子路径字符串
+ * @returns 顶层字段名，找不到时返回 undefined
+ */
+function baseFieldNameOf(subPath: string): string | undefined {
+  if (!subPath) return undefined;
+  const m = subPath.match(/^([^.[]+)/);
+  return m?.[1];
+}
+
+/**
+ * 在集合中根据字段名查找字段定义，兼容 getField/getFields 两种方式。
+ *
+ * @param collection 集合对象
+ * @param name 字段名
+ * @returns 匹配的字段定义，找不到时返回 undefined
+ */
+function findFieldByName(collection: Collection | null | undefined, name?: string): CollectionField | undefined {
+  if (!collection || !name) return undefined;
+  const direct = collection.getField(name);
+  if (direct) return direct;
+  const fields = collection.getFields?.() || [];
+  return fields.find((f) => f.name === name);
+}
+
+/**
+ * 从值中提取主键：
+ * - 支持主键原始值（string/number）
+ * - 支持对象（按主键名取值）
+ *
+ * @param value 字段当前值
+ * @param primaryKey 主键字段名
+ * @returns 解析出的主键值，无法解析时返回 undefined
+ */
+function toFilterByTk(value: unknown, primaryKey: string | string[]) {
+  if (value == null) return undefined;
+  if (Array.isArray(primaryKey)) {
+    if (typeof value !== 'object' || !value) return undefined;
+    const out: Record<string, any> = {};
+    for (const k of primaryKey) {
+      const v = (value as any)[k];
+      if (typeof v === 'undefined' || v === null) return undefined;
+      out[k] = v;
+    }
+    return out;
+  }
+  if (typeof value === 'string' || typeof value === 'number') return value;
+  if (typeof value === 'object') {
+    return (value as any)[primaryKey];
+  }
+  return undefined;
+}
+
+/**
+ * 创建一个用于“对象类变量”（如 formValues / currentObject）的 `resolveOnServer` 判定函数。
+ * 仅当访问路径以“关联字段名”开头（且继续访问其子属性）时，返回 true 交由服务端解析；
+ * 否则在前端解析即可。
+ *
+ * @param collectionAccessor 返回当前对象所在 collection
+ * @param valueAccessor 可选，本地值访问器。若本地已存在目标子路径的值，则认为无需走后端，优先使用本地值。
+ * @returns `(subPath) => boolean` 判断是否需要服务端解析
+ */
+export function createAssociationSubpathResolver(
+  collectionAccessor: () => Collection | null,
+  valueAccessor?: () => unknown,
+): (subPath: string) => boolean {
+  return (p: string) => {
+    // 仅在访问子属性时才考虑后端
+    if (!p || !p.includes('.')) return false;
+    const base = baseFieldNameOf(p);
+    if (!base) return false;
+    const collection = collectionAccessor();
+    const field = findFieldByName(collection, base);
+    const isAssoc = !!field?.isAssociationField();
+    if (!isAssoc) return false;
+
+    // 可选：本地优先。当提供 valueAccessor 时，若本地已有该子路径值，则不走后端
+    if (typeof valueAccessor === 'function') {
+      const local = valueAccessor();
+      if (local && typeof local === 'object') {
+        const v = _.get(local as Record<string, unknown>, p);
+        if (typeof v !== 'undefined') return false;
+      }
+    }
+
+    return true;
+  };
+}
+
+/**
+ * 构建“对象类变量”的 PropertyMetaFactory：
+ * - 暴露集合字段结构（通过 createCollectionContextMeta）用于变量选择器；
+ * - 提供 buildVariablesParams：基于对象当前值，收集所有“已选择的关联字段”
+ *   以便服务端在 variables:resolve 时按需补全关联数据。
+ *
+ * @param collectionAccessor 获取集合对象，用于字段/元信息来源
+ * @param title 变量组标题（用于 UI 展示）
+ * @param valueAccessor 获取当前对象值（如 ctx.form.getFieldsValue() / ctx.currentObject）
+ * @returns PropertyMetaFactory
+ */
+export function createAssociationAwareObjectMetaFactory(
+  collectionAccessor: () => Collection | null,
+  title: string,
+  valueAccessor: (ctx: FlowContext) => any,
+): PropertyMetaFactory {
+  const baseFactory = createCollectionContextMeta(collectionAccessor, title, true);
+  const factory: PropertyMetaFactory = async () => {
+    const base = (await baseFactory()) as PropertyMeta | null;
+    if (!base) return null;
+
+    const meta: PropertyMeta = {
+      ...base,
+      buildVariablesParams: (ctx: FlowContext) => {
+        const collection = collectionAccessor();
+        const obj = valueAccessor(ctx);
+        if (!collection || !obj || typeof obj !== 'object') return {};
+        const params: Record<string, any> = {};
+
+        const fields: CollectionField[] = collection.getFields?.() || [];
+        for (const field of fields) {
+          const name = field.name as string | undefined;
+          if (!name) continue;
+          if (!field.isAssociationField()) continue;
+          const target = field.target as string | undefined;
+          const targetCollection = field.targetCollection;
+          if (!target || !targetCollection) continue;
+          const primaryKey = targetCollection.filterTargetKey as string | string[];
+
+          const associationValue = (obj as any)[name];
+          if (associationValue == null) continue;
+
+          if (Array.isArray(associationValue)) {
+            const ids = associationValue.map((item) => toFilterByTk(item, primaryKey)).filter((v) => v != null);
+            if (ids.length) {
+              params[name] = {
+                collection: target,
+                dataSourceKey: targetCollection.dataSourceKey,
+                filterByTk: ids,
+              };
+            }
+          } else {
+            const id = toFilterByTk(associationValue, primaryKey);
+            if (id != null) {
+              params[name] = {
+                collection: target,
+                dataSourceKey: targetCollection.dataSourceKey,
+                filterByTk: id,
+              };
+            }
+          }
+        }
+
+        return params;
+      },
+    };
+
+    return meta;
+  };
+  factory.title = title;
+  return factory;
+}

package/src/utils/createCollectionContextMeta.ts

@@ -17,7 +17,7 @@ const NUMERIC_FIELD_TYPES = ['integer', 'float', 'double', 'decimal'] as const;
 /**
  * 创建字段的完整元数据（统一处理关联和非关联字段）
  */
-function createFieldMetadata(field: CollectionField) {
+function createFieldMetadata(field: CollectionField, includeNonFilterable?: boolean) {
   const baseProperties = createMetaBaseProperties(field);
 
   if (field.isAssociationField()) {
@@ -36,7 +36,9 @@ function createFieldMetadata(field: CollectionField) {
       properties: async () => {
         const subProperties: Record<string, any> = {};
         targetCollection.fields.forEach((subField) => {
-          subProperties[subField.name] = createFieldMetadata(subField);
+          if (includeNonFilterable || subField.filterable) {
+            subProperties[subField.name] = createFieldMetadata(subField, includeNonFilterable);
+          }
         });
         return subProperties;
       },
@@ -93,6 +95,7 @@ function createMetaBaseProperties(field: CollectionField) {
 export function createCollectionContextMeta(
   collectionOrFactory: Collection | (() => Collection | null),
   title?: string,
+  includeNonFilterable?: boolean,
 ): PropertyMetaFactory {
   const metaFn: PropertyMetaFactory = async () => {
     const collection = typeof collectionOrFactory === 'function' ? collectionOrFactory() : collectionOrFactory;
@@ -110,7 +113,9 @@ export function createCollectionContextMeta(
 
         // 添加所有字段
         collection.fields.forEach((field) => {
-          properties[field.name] = createFieldMetadata(field);
+          if (includeNonFilterable || field.filterable) {
+            properties[field.name] = createFieldMetadata(field, includeNonFilterable);
+          }
         });
 
         return properties;