@nocobase/flow-engine 2.1.0-alpha.40 → 2.1.0-alpha.45

package/src/components/subModel/__tests__/AddSubModelButton.test.tsx

@@ -8,7 +8,7 @@
  */
 
 import React from 'react';
-import { act, render, screen, userEvent, waitFor } from '@nocobase/test/client';
+import { act, fireEvent, render, screen, userEvent, waitFor } from '@nocobase/test/client';
 import { vi, beforeEach } from 'vitest';
 import {
   AddSubModelButton,
@@ -354,6 +354,208 @@ describe('transformItems - searchable flags', () => {
     await user.type(searchInput, 'display');
     await waitFor(() => expect(screen.getByText('Field display name')).toBeInTheDocument());
   });
+
+  it('keeps searchable submenu children during IME composition', async () => {
+    const engine = new FlowEngine();
+    await engine.flowSettings.forceEnable();
+    class Parent extends FlowModel {}
+    engine.registerModels({ Parent });
+    const parent = engine.createModel<FlowModel>({ use: 'Parent' });
+
+    const items = [
+      {
+        key: 'fields',
+        label: 'Fields',
+        searchable: true,
+        children: [
+          { key: 'f1', label: 'Field 1', createModelOptions: { use: 'Parent' } },
+          { key: 'f2', label: 'Field 2', createModelOptions: { use: 'Parent' } },
+        ],
+      },
+    ];
+
+    const user = userEvent.setup();
+    render(
+      <FlowEngineProvider engine={engine}>
+        <ConfigProvider>
+          <App>
+            <AddSubModelButton model={parent} subModelKey="items" items={items as any}>
+              Open
+            </AddSubModelButton>
+          </App>
+        </ConfigProvider>
+      </FlowEngineProvider>,
+    );
+
+    await user.click(screen.getByText('Open'));
+    await waitFor(() => expect(screen.getByText('Fields')).toBeInTheDocument());
+    await user.hover(screen.getByText('Fields'));
+    await waitFor(() => expect(screen.getByText('Field 1')).toBeInTheDocument());
+
+    const input = screen.getByRole('textbox');
+    await user.click(input);
+    fireEvent.compositionStart(input);
+    fireEvent.change(input, { target: { value: 'zzzz' }, nativeEvent: { isComposing: true } });
+    fireEvent.mouseLeave(screen.getByText('Fields'));
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 300));
+    });
+
+    expect(input).toHaveValue('zzzz');
+    expect(screen.getByText('Field 1')).toBeInTheDocument();
+    expect(screen.getByText('Field 2')).toBeInTheDocument();
+
+    fireEvent.compositionEnd(input);
+    fireEvent.change(input, { target: { value: 'zzzz' } });
+
+    await waitFor(() => expect(screen.getAllByText('No data').length).toBeGreaterThan(0));
+  });
+
+  it('closes searchable submenu after focus without input', async () => {
+    const engine = new FlowEngine();
+    await engine.flowSettings.forceEnable();
+    class Parent extends FlowModel {}
+    engine.registerModels({ Parent });
+    const parent = engine.createModel<FlowModel>({ use: 'Parent' });
+
+    const items = [
+      {
+        key: 'fields',
+        label: 'Fields',
+        searchable: true,
+        children: [
+          { key: 'f1', label: 'Field 1', createModelOptions: { use: 'Parent' } },
+          { key: 'f2', label: 'Field 2', createModelOptions: { use: 'Parent' } },
+        ],
+      },
+    ];
+
+    const user = userEvent.setup();
+    render(
+      <FlowEngineProvider engine={engine}>
+        <ConfigProvider>
+          <App>
+            <AddSubModelButton model={parent} subModelKey="items" items={items as any}>
+              Open
+            </AddSubModelButton>
+          </App>
+        </ConfigProvider>
+      </FlowEngineProvider>,
+    );
+
+    await user.click(screen.getByText('Open'));
+    await waitFor(() => expect(screen.getByText('Fields')).toBeInTheDocument());
+    await user.hover(screen.getByText('Fields'));
+    await waitFor(() => expect(screen.getByText('Field 1')).toBeInTheDocument());
+
+    await user.click(screen.getByRole('textbox'));
+    fireEvent.mouseLeave(screen.getByText('Fields'));
+
+    await waitFor(() => expect(screen.queryByText('Field 1')).not.toBeInTheDocument());
+  });
+
+  it('closes active searchable submenu after outside click', async () => {
+    const engine = new FlowEngine();
+    await engine.flowSettings.forceEnable();
+    class Parent extends FlowModel {}
+    engine.registerModels({ Parent });
+    const parent = engine.createModel<FlowModel>({ use: 'Parent' });
+
+    const items = [
+      {
+        key: 'fields',
+        label: 'Fields',
+        searchable: true,
+        children: [
+          { key: 'f1', label: 'Field 1', createModelOptions: { use: 'Parent' } },
+          { key: 'f2', label: 'Field 2', createModelOptions: { use: 'Parent' } },
+        ],
+      },
+    ];
+
+    const user = userEvent.setup();
+    render(
+      <FlowEngineProvider engine={engine}>
+        <ConfigProvider>
+          <App>
+            <AddSubModelButton model={parent} subModelKey="items" items={items as any}>
+              Open
+            </AddSubModelButton>
+          </App>
+        </ConfigProvider>
+      </FlowEngineProvider>,
+    );
+
+    await user.click(screen.getByText('Open'));
+    await waitFor(() => expect(screen.getByText('Fields')).toBeInTheDocument());
+    await user.hover(screen.getByText('Fields'));
+    await waitFor(() => expect(screen.getByText('Field 1')).toBeInTheDocument());
+
+    fireEvent.change(screen.getByRole('textbox'), { target: { value: 'Field' } });
+    expect(screen.getByText('Field 1')).toBeInTheDocument();
+
+    fireEvent.pointerDown(document.body);
+
+    await waitFor(() => expect(screen.queryByText('Fields')).not.toBeInTheDocument());
+  });
+
+  it('switches away from active searchable submenu and resets its input', async () => {
+    const engine = new FlowEngine();
+    await engine.flowSettings.forceEnable();
+    class Parent extends FlowModel {}
+    engine.registerModels({ Parent });
+    const parent = engine.createModel<FlowModel>({ use: 'Parent' });
+
+    const items = [
+      {
+        key: 'fields',
+        label: 'Fields',
+        searchable: true,
+        children: [
+          { key: 'f1', label: 'Field 1', createModelOptions: { use: 'Parent' } },
+          { key: 'f2', label: 'Field 2', createModelOptions: { use: 'Parent' } },
+        ],
+      },
+      {
+        key: 'blocks',
+        label: 'Blocks',
+        searchable: true,
+        children: [
+          { key: 'b1', label: 'Block 1', createModelOptions: { use: 'Parent' } },
+          { key: 'b2', label: 'Block 2', createModelOptions: { use: 'Parent' } },
+        ],
+      },
+    ];
+
+    const user = userEvent.setup();
+    render(
+      <FlowEngineProvider engine={engine}>
+        <ConfigProvider>
+          <App>
+            <AddSubModelButton model={parent} subModelKey="items" items={items as any}>
+              Open
+            </AddSubModelButton>
+          </App>
+        </ConfigProvider>
+      </FlowEngineProvider>,
+    );
+
+    await user.click(screen.getByText('Open'));
+    await waitFor(() => expect(screen.getByText('Fields')).toBeInTheDocument());
+    await user.hover(screen.getByText('Fields'));
+    await waitFor(() => expect(screen.getByText('Field 1')).toBeInTheDocument());
+
+    fireEvent.change(screen.getByRole('textbox'), { target: { value: 'zzzz' } });
+    await waitFor(() => expect(screen.getAllByText('No data').length).toBeGreaterThan(0));
+
+    await user.hover(screen.getByText('Blocks'));
+    await waitFor(() => expect(screen.getByText('Block 1')).toBeInTheDocument());
+    expect(screen.queryByText('No data')).not.toBeInTheDocument();
+
+    await user.hover(screen.getByText('Fields'));
+    await waitFor(() => expect(screen.getByText('Field 1')).toBeInTheDocument());
+    expect(screen.getByRole('textbox')).toHaveValue('');
+  });
 });
 
 describe('transformItems - hide', () => {

package/src/data-source/index.ts

@@ -37,7 +37,13 @@ export class DataSourceManager {
     addFieldInterfaceGroups?: (groups: Record<string, { label: string; order?: number }>) => void;
     addFieldInterfaceComponentOption?: (name: string, option: any) => void;
     addFieldInterfaceOperator?: (name: string, operator: any) => void;
+    registerFieldFilterOperator?: (operator: any) => void;
+    registerFieldFilterOperatorGroup?: (name: string, operators?: any[]) => void;
+    addFieldFilterOperatorsToGroup?: (name: string, operators?: any[]) => void;
     getFieldInterface?: (name: string) => any;
+    registerFieldInterfaceConfigure?: (options: unknown) => void;
+    getFieldInterfaceConfigure?: (name: string, collectionInfo?: unknown) => unknown;
+    getFieldInterfaceConfigureProperties?: (name: string, collectionInfo?: any) => Record<string, any>;
   };
   loaders = new Map<string, DataSourceLoader>();
   loadedKeys = new Set<string>();
@@ -77,6 +83,18 @@ export class DataSourceManager {
     this.collectionFieldInterfaceManager?.addFieldInterfaceOperator?.(name, operator);
   }
 
+  registerFieldFilterOperator(operator: any) {
+    this.collectionFieldInterfaceManager?.registerFieldFilterOperator?.(operator);
+  }
+
+  registerFieldFilterOperatorGroup(name: string, operators: any[] = []) {
+    this.collectionFieldInterfaceManager?.registerFieldFilterOperatorGroup?.(name, operators);
+  }
+
+  addFieldFilterOperatorsToGroup(name: string, operators: any[] = []) {
+    this.collectionFieldInterfaceManager?.addFieldFilterOperatorsToGroup?.(name, operators);
+  }
+
   registerLoader(key: string, loader: DataSourceLoader) {
     this.loaders.set(key, loader);
   }

package/src/executor/__tests__/flowExecutor.test.ts

@@ -81,6 +81,34 @@ describe('FlowExecutor', () => {
     expect(result.step2).toBe('step2-ok');
   });
 
+  it('runFlow warns and skips steps without use or handler', async () => {
+    const flows = {
+      referenceSettings: {
+        steps: {
+          target: {},
+        },
+      },
+    } satisfies Record<string, Omit<FlowDefinitionOptions, 'key'>>;
+    const model = createModelWithFlows('m-empty-step', flows);
+    const loggerChildSpy = vi.spyOn(engine.logger, 'child').mockReturnValue(engine.logger);
+    const loggerWarnSpy = vi.spyOn(engine.logger, 'warn').mockImplementation(() => {});
+    const loggerErrorSpy = vi.spyOn(engine.logger, 'error').mockImplementation(() => {});
+
+    try {
+      const result = await engine.executor.runFlow(model, 'referenceSettings');
+
+      expect(result).toEqual({});
+      expect(loggerWarnSpy).toHaveBeenCalledWith(
+        "BaseModel.applyFlow: Step 'target' in flow 'referenceSettings' has neither 'use' nor 'handler'. Skipping.",
+      );
+      expect(loggerErrorSpy).not.toHaveBeenCalled();
+    } finally {
+      loggerChildSpy.mockRestore();
+      loggerWarnSpy.mockRestore();
+      loggerErrorSpy.mockRestore();
+    }
+  });
+
   it("dispatchEvent('beforeRender') executes flows in sort order and caches result (when options specify)", async () => {
     const calls: string[] = [];
     const mkFlow = (key: string, sort: number) => ({

package/src/flowContext.ts

@@ -3581,6 +3581,9 @@ export class FlowEngineContext extends BaseFlowEngineContext {
       },
     });
     this.defineMethod('aclCheck', function (params) {
+      if (this.skipAclCheck) {
+        return true;
+      }
       return this.acl.aclCheck(params);
     });
     this.defineMethod('createResource', function (this: BaseFlowEngineContext, resourceType) {

package/src/flowEngine.ts

@@ -39,6 +39,8 @@ import type {
 } from './types';
 import { isInheritedFrom } from './utils';
 
+const getFlowEngineLoggerLevel = () => (process.env.NODE_ENV === 'production' ? 'warn' : 'trace');
+
 /**
  * FlowEngine is the core class of the flow engine, responsible for managing flow models, actions, model repository, and more.
  * It provides capabilities for registering, creating, finding, persisting, replacing, and moving models.
@@ -213,7 +215,7 @@ export class FlowEngine {
       MultiRecordResource,
     });
     this.logger = pino({
-      level: 'trace',
+      level: getFlowEngineLoggerLevel(),
       browser: {
         write: {
           fatal: (o) => console.trace(o),
@@ -1009,7 +1011,6 @@ export class FlowEngine {
 
     while (current) {
       if (visited.has(current)) {
-        console.warn(`FlowEngine: resolveUse circular reference detected on '${current.name}'.`);
         break;
       }
       visited.add(current);
@@ -1128,7 +1129,7 @@ export class FlowEngine {
    */
   public removeModel(uid: string): boolean {
     if (!this._modelInstances.has(uid)) {
-      console.warn(`FlowEngine: Model with UID '${uid}' does not exist.`);
+      this.logger.debug(`FlowEngine: Model with UID '${uid}' does not exist.`);
       return false;
     }
     const modelInstance = this._modelInstances.get(uid) as FlowModel;

package/src/models/__tests__/flowEngine.resolveUse.test.ts

@@ -61,21 +61,6 @@ describe('FlowEngine.createModel resolveUse hook', () => {
     expect(warnSpy).not.toHaveBeenCalled();
   });
 
-  test('should break resolveUse on circular reference and warn', () => {
-    class LoopModel extends FlowModel {
-      static resolveUse() {
-        return 'LoopModel';
-      }
-    }
-
-    engine.registerModels({ LoopModel });
-
-    const model = engine.createModel({ use: 'LoopModel', uid: 'loop-model', flowEngine: engine });
-
-    expect(model).toBeInstanceOf(LoopModel);
-    expect(warnSpy).toHaveBeenCalled();
-  });
-
   test('should fall back to ErrorFlowModel when resolveUse returns unregistered name', () => {
     class MissingTargetEntry extends FlowModel {
       static resolveUse() {

package/src/models/__tests__/flowModel.test.ts

@@ -370,15 +370,17 @@ describe('FlowModel', () => {
         };
 
         TestFlowModel.registerFlow(exitFlow);
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
-        const result = await model.applyFlow('exitFlow');
-
-        expect(result).toBeInstanceOf(FlowExitAllException);
-        expect(exitFlow.steps.step2.handler).not.toHaveBeenCalled();
-        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('[FlowModel]'));
+        try {
+          const result = await model.applyFlow('exitFlow');
 
-        consoleSpy.mockRestore();
+          expect(result).toBeInstanceOf(FlowExitAllException);
+          expect(exitFlow.steps.step2.handler).not.toHaveBeenCalled();
+          expect(loggerSpy).toHaveBeenCalledWith(expect.stringContaining('[FlowModel]'));
+        } finally {
+          loggerSpy.mockRestore();
+        }
       });
 
       test('should handle ctx.exit() as FlowExitAllException in beforeRender dispatch', async () => {
@@ -474,15 +476,17 @@ describe('FlowModel', () => {
         };
 
         TestFlowModel.registerFlow(exitFlow);
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-
-        const result = await model.applyFlow('exitFlow');
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
-        expect(result).toBeInstanceOf(FlowExitAllException);
-        expect(exitFlow.steps.step2.handler).not.toHaveBeenCalled();
-        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('[FlowModel]'));
+        try {
+          const result = await model.applyFlow('exitFlow');
 
-        consoleSpy.mockRestore();
+          expect(result).toBeInstanceOf(FlowExitAllException);
+          expect(exitFlow.steps.step2.handler).not.toHaveBeenCalled();
+          expect(loggerSpy).toHaveBeenCalledWith(expect.stringContaining('[FlowModel]'));
+        } finally {
+          loggerSpy.mockRestore();
+        }
       });
 
       test('should propagate step execution errors', async () => {
@@ -796,7 +800,7 @@ describe('FlowModel', () => {
         const eventFlow = createEventFlowDefinition('testEvent');
         TestFlowModel.registerFlow(eventFlow);
 
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
         try {
           model.dispatchEvent('testEvent', { data: 'payload' });
@@ -804,7 +808,7 @@ describe('FlowModel', () => {
           // Use a more reliable approach than arbitrary timeout
           await new Promise((resolve) => setTimeout(resolve, 0));
 
-          expect(consoleSpy).toHaveBeenCalledWith(
+          expect(loggerSpy).toHaveBeenCalledWith(
             expect.stringContaining('[FlowModel] dispatchEvent: uid=test-model-uid, event=testEvent'),
           );
           expect(eventFlow.steps.eventStep.handler).toHaveBeenCalledWith(
@@ -814,7 +818,7 @@ describe('FlowModel', () => {
             expect.any(Object),
           );
         } finally {
-          consoleSpy.mockRestore();
+          loggerSpy.mockRestore();
         }
       });
 
@@ -1625,7 +1629,7 @@ describe('FlowModel', () => {
         fork1.dispose = vi.fn();
         fork2.dispose = vi.fn();
 
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
         try {
           model.clearForks();
@@ -1634,19 +1638,19 @@ describe('FlowModel', () => {
           expect(fork2.dispose).toHaveBeenCalled();
           expect(model.forks.size).toBe(0);
         } finally {
-          consoleSpy.mockRestore();
+          loggerSpy.mockRestore();
         }
       });
 
       test('should handle empty forks collection when clearing', () => {
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
         try {
           model.clearForks();
 
           expect(model.forks.size).toBe(0);
         } finally {
-          consoleSpy.mockRestore();
+          loggerSpy.mockRestore();
         }
       });
     });
@@ -1774,7 +1778,7 @@ describe('FlowModel', () => {
       test('should clean up resources on remove', () => {
         model.createFork();
         model.createFork();
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
         // Mock removeModel to simulate proper fork cleanup
         flowEngine.removeModel = vi.fn().mockImplementation(() => {
@@ -1791,7 +1795,7 @@ describe('FlowModel', () => {
           expect(model.forks.size).toBe(0);
           expect(flowEngine.removeModel).toHaveBeenCalledWith(model.uid);
         } finally {
-          consoleSpy.mockRestore();
+          loggerSpy.mockRestore();
         }
       });
     });
@@ -1868,17 +1872,12 @@ describe('FlowModel', () => {
       });
 
       test('should rerender triggers beforeRender without cache', async () => {
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
         model.dispatchEvent = vi.fn().mockResolvedValue(undefined) as any;
 
-        try {
-          await expect(model.rerender()).resolves.not.toThrow();
-          expect(model.dispatchEvent).toHaveBeenCalledWith('beforeRender', undefined, {
-            useCache: false,
-          });
-        } finally {
-          consoleSpy.mockRestore();
-        }
+        await expect(model.rerender()).resolves.not.toThrow();
+        expect(model.dispatchEvent).toHaveBeenCalledWith('beforeRender', undefined, {
+          useCache: false,
+        });
       });
     });
 
@@ -2918,7 +2917,7 @@ describe('FlowModel', () => {
   describe('Edge Cases & Error Handling', () => {
     test('should handle model destruction gracefully', () => {
       const model = new FlowModel(modelOptions);
-      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
       model.createFork();
       model.setProps({ testProp: 'value' });
@@ -2926,7 +2925,7 @@ describe('FlowModel', () => {
       try {
         expect(() => model.remove()).not.toThrow();
       } finally {
-        consoleSpy.mockRestore();
+        loggerSpy.mockRestore();
       }
     });
 

package/src/models/flowModel.tsx

@@ -823,7 +823,7 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
     }
     const isFork = (this as any).isFork === true;
     const target = this;
-    console.log(
+    currentFlowEngine.logger.debug(
       `[FlowModel] applyFlow: uid=${this.uid}, flowKey=${flowKey}, isFork=${isFork}, cleanRun=${
         this.cleanRun
       }, targetIsFork=${(target as any)?.isFork === true}`,
@@ -843,7 +843,7 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
     }
     const isFork = (this as any).isFork === true;
     const target = this;
-    console.log(
+    currentFlowEngine.logger.debug(
       `[FlowModel] dispatchEvent: uid=${this.uid}, event=${eventName}, isFork=${isFork}, cleanRun=${
         this.cleanRun
       }, targetIsFork=${(target as any)?.isFork === true}`,
@@ -1379,7 +1379,7 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
   }
 
   clearForks() {
-    console.log(`FlowModel ${this.uid} clearing all forks.`);
+    this.flowEngine.logger.debug(`FlowModel ${this.uid} clearing all forks.`);
     // 主动使所有 fork 失效
     if (this.forks?.size) {
       this.forks.forEach((fork) => fork.dispose());

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

@@ -102,6 +102,27 @@ describe('parsePathnameToViewParams', () => {
     expect(result).toEqual([{ viewUid: 'xxx', tabUid: 'yyy' }]);
   });
 
+  test('should parse custom root prefix', () => {
+    const result = parsePathnameToViewParams('/embed/xxx/tab/yyy/view/zzz', { rootPrefix: 'embed' });
+    expect(result).toEqual([{ viewUid: 'xxx', tabUid: 'yyy' }, { viewUid: 'zzz' }]);
+  });
+
+  test('should parse pathname by basePath', () => {
+    const result = parsePathnameToViewParams('/embed/xxx/tab/yyy/view/zzz', { basePath: '/embed' });
+    expect(result).toEqual([{ viewUid: 'xxx', tabUid: 'yyy' }, { viewUid: 'zzz' }]);
+  });
+
+  test('should parse pathname by nested basePath', () => {
+    const result = parsePathnameToViewParams('/admin/settings/public-forms/xxx/view/zzz', {
+      basePath: '/admin/settings/public-forms',
+    });
+    expect(result).toEqual([{ viewUid: 'xxx' }, { viewUid: 'zzz' }]);
+  });
+
+  test('should keep admin as default root prefix', () => {
+    expect(parsePathnameToViewParams('/embed/xxx')).toEqual([]);
+  });
+
   test('should parse filterByTk from key-value encoded segment into object', () => {
     const kv = encodeURIComponent('id=1&tenant=ac');
     const path = `/admin/xxx/filterbytk/${kv}`;

package/src/utils/parsePathnameToViewParams.ts

@@ -18,6 +18,35 @@ export interface ViewParam {
   sourceId?: string;
 }
 
+export interface ParsePathnameToViewParamsOptions {
+  rootPrefix?: string;
+  basePath?: string;
+}
+
+const normalizePathname = (pathname: string) => {
+  if (!pathname || pathname === '/') {
+    return '/';
+  }
+  return `/${pathname.replace(/^\/+/, '').replace(/\/+$/, '')}`;
+};
+
+const normalizeBasePath = (basePath: string) => `/${basePath.replace(/^\/+/, '').replace(/\/+$/, '')}`;
+
+const stripBasePath = (pathname: string, basePath: string) => {
+  const normalizedPathname = normalizePathname(pathname);
+  const normalizedBasePath = normalizeBasePath(basePath);
+
+  if (normalizedPathname === normalizedBasePath) {
+    return '';
+  }
+
+  if (normalizedPathname.startsWith(`${normalizedBasePath}/`)) {
+    return normalizedPathname.slice(normalizedBasePath.length + 1);
+  }
+
+  return '';
+};
+
 /**
  * 解析路径名为视图参数数组
  *
@@ -33,15 +62,21 @@ export interface ViewParam {
  * parsePathnameToViewParams('/admin/xxx/view/yyy') // [{ viewUid: 'xxx' }, { viewUid: 'yyy' }]
  * ```
  */
-export const parsePathnameToViewParams = (pathname: string): ViewParam[] => {
+export const parsePathnameToViewParams = (
+  pathname: string,
+  options: ParsePathnameToViewParamsOptions = {},
+): ViewParam[] => {
   if (!pathname || pathname === '/') {
     return [];
   }
 
+  const rootPrefix = options.rootPrefix || 'admin';
+  const relativePath = options.basePath ? stripBasePath(pathname, options.basePath) : '';
+
   // 移除开头的斜杠并分割路径
-  const segments = pathname.replace(/^\/+/, '').split('/').filter(Boolean);
+  const segments = (options.basePath ? relativePath : pathname).replace(/^\/+/, '').split('/').filter(Boolean);
 
-  if (segments.length < 2) {
+  if (segments.length < (options.basePath ? 1 : 2)) {
     return [];
   }
 
@@ -49,11 +84,16 @@ export const parsePathnameToViewParams = (pathname: string): ViewParam[] => {
   let currentView: ViewParam | null = null;
   let i = 0;
 
+  if (options.basePath) {
+    currentView = { viewUid: segments[0] };
+    i = 1;
+  }
+
   while (i < segments.length) {
     const segment = segments[i];
 
-    // 处理 admin 或 view 关键字
-    if (segment === 'admin' || segment === 'view') {
+    // 处理布局根前缀或 view 关键字
+    if (segment === rootPrefix || segment === 'view') {
       // 如果有当前视图，先保存到结果中
       if (currentView) {
         result.push(currentView);